cristianchiru/docker-kong-oidc

docker-kong-oidc

镜像概述

docker-kong-oidc是一个基于Kong的Docker镜像，集成了https://github.com/revomatico/kong-oidc%E6%8F%92%E4%BB%B6%EF%BC%88%E5%9F%BA%E4%BA%8Ezmartzone/lua-resty-openidc%EF%BC%89%EF%BC%8C%E6%8F%90%E4%BE%9BOpenID Connect（OIDC）认证能力。镜像仓库地址：https://hub.docker.com/r/cristianchiru/docker-kong-oidc。

注意：从版本https://github.com/revomatico/docker-kong-oidc/releases/tag/3.2.2-1%E5%BC%80%E5%A7%8B%EF%BC%8CDocker%E4%BB%93%E5%BA%93%E8%BF%81%E7%A7%BB%E8%87%B3%E4%B8%AA%E4%BA%BA%E8%B4%A6%E5%8F%B7%E3%80%82%E6%97%A7%E4%BB%93%E5%BA%93%EF%BC%88https://hub.docker.com/r/revomatico/docker-kong-oidc）仍可使用，但已被视为 deprecated。

核心功能与特性

• OIDC认证支持：集成kong-oidc插件，实现OpenID Connect协议的身份验证与授权。
• 多会话存储方式：支持Cookie、Memcached、SHM（共享内存）、DSHM（分布式共享内存）等多种会话存储。
• 灵活配置：通过环境变量自定义会话密钥、存储参数、日志排除规则等。
• 兼容性：支持Kong 2.x至3.x系列版本，适配不同部署场景。

使用场景与适用范围

• API网关的身份验证与授权。
• 单点登录（SSO）集成，保护后端服务。
• 多实例部署环境下的会话共享（如Kubernetes集群）。
• 需要自定义会话存储策略的场景（如高性能单实例或分布式部署）。

使用方法与配置说明

基本配置

启用插件

通过环境变量启用oidc插件：

bash
KONG_PLUGINS=bundled,oidc

会话密钥设置

必须通过环境变量定义会话密钥：

bash
KONG_X_SESSION_SECRET="your-secure-session-secret"

默认会话名称

默认会话名称为oidc_session，可通过以下环境变量修改：

bash
KONG_X_SESSION_NAME="custom-session-name"

会话存储配置

1. Cookie存储（默认，不推荐）

适用于简单场景，但不建议生产环境使用。

• 增大Nginx头大小（当会话信息较多时）：

  bash
  KONG_NGINX_LARGE_CLIENT_HEADER_BUFFERS='4 16k'
  

• 启用会话压缩：

  bash
  KONG_X_SESSION_COMPRESSOR=zlib
  

2. Memcached存储

推荐与支持Memcache协议的分布式缓存（如Hazelcast）配合使用。

• 启用Memcached存储：

  bash
  KONG_X_SESSION_STORAGE=memcache
  

• 配置参数：

  环境变量	描述	默认值
  KONG_X_SESSION_MEMCACHE_HOST	Memcached主机	memcached
  KONG_X_SESSION_MEMCACHE_PORT	Memcached端口（需双重引号）	"'***'"
  KONG_X_SESSION_MEMCACHE_USELOCKING	是否启用锁定	off
  KONG_X_SESSION_MEMCACHE_SPINLOCKWAIT	自旋锁等待时间	150
  KONG_X_SESSION_MEMCACHE_MAXLOCKWAIT	最大锁定等待时间	30
  KONG_X_SESSION_MEMCACHE_POOL_TIMEOUT	连接池超时	10
  KONG_X_SESSION_MEMCACHE_POOL_SIZE	连接池大小	10
  KONG_X_SESSION_MEMCACHE_CONNECT_TIMEOUT	连接超时（毫秒）	1000
  KONG_X_SESSION_MEMCACHE_SEND_TIMEOUT	发送超时（毫秒）	1000
  KONG_X_SESSION_MEMCACHE_READ_TIMEOUT	读取超时（毫秒）	1000

3. DSHM存储（Hazelcast + Vertex）

基于https://github.com/grrolland/ngx-distributed-shm%E5%BA%93%EF%BC%8C%E9%80%82%E7%94%A8%E4%BA%8E%E5%88%86%E5%B8%83%E5%BC%8F%E7%8E%AF%E5%A2%83%E3%80%82

• 启用DSHM存储：

  bash
  KONG_X_SESSION_STORAGE=dshm
  

• 配置参数：

  环境变量	描述	默认值
  X_SESSION_DSHM_REGION	会话区域	oidc_sessions
  X_SESSION_DSHM_CONNECT_TIMEOUT	连接超时（毫秒）	1000
  X_SESSION_DSHM_SEND_TIMEOUT	发送超时（毫秒）	1000
  X_SESSION_DSHM_READ_TIMEOUT	读取超时（毫秒）	1000
  X_SESSION_DSHM_HOST	DSHM主机	hazelcast
  X_SESSION_DSHM_PORT	DSHM端口	4321
  X_SESSION_DSHM_POOL_NAME	连接池名称	oidc_sessions
  X_SESSION_DSHM_POOL_TIMEOUT	连接池超时（毫秒）	1000
  X_SESSION_DSHM_POOL_SIZE	连接池大小	10
  X_SESSION_DSMM_POOL_BACKLOG	连接池等待队列长度	10

4. SHM存储（共享内存）

适用于单实例部署，无需额外软件。

• 启用SHM存储：

  bash
  KONG_X_SESSION_STORAGE=shm
  

• 配置参数：

  环境变量	描述	默认值
  KONG_X_SESSION_SHM_STORE	共享内存区域名称	oidc_sessions
  KONG_X_SESSION_SHM_STORE_SIZE	共享内存大小	5m
  KONG_X_SESSION_SHM_USELOCKING	是否启用锁定	no
  KONG_X_SESSION_SHM_LOCK_EXPTIME	锁过期时间	30
  KONG_X_SESSION_SHM_LOCK_TIMEOUT	锁超时时间	5
  KONG_X_SESSION_SHM_LOCK_STEP	锁等待步长	0.001
  KONG_X_SESSION_SHM_LOCK_RATIO	锁等待比例	2
  KONG_X_SESSION_SHM_LOCK_MAX_STEP	最大锁等待步长	0.5

排除IP访问日志

通过环境变量指定IP排除列表文件：

bash
KONG_X_NOLOG_LIST_FILE=/tmp/nolog.txt

文件格式（每行一个IP，格式为ip 0;）：

127.0.0.1 0;  # 排除本地访问日志

Docker部署示例

基本运行命令

bash
docker run -d \
  -p 8000:8000 \
  -p 8443:8443 \
  -e "KONG_PLUGINS=bundled,oidc" \
  -e "KONG_X_SESSION_SECRET=your-secret-key" \
  -e "KONG_X_SESSION_STORAGE=shm" \
  cristianchiru/docker-kong-oidc:latest

docker-compose配置示例

yaml
version: '3'
services:
  kong-oidc:
    image: cristianchiru/docker-kong-oidc:latest
    ports:
      - "8000:8000"
      - "8443:8443"
    environment:
      - KONG_PLUGINS=bundled,oidc
      - KONG_X_SESSION_SECRET=your-secure-secret
      - KONG_X_SESSION_STORAGE=memcache
      - KONG_X_SESSION_MEMCACHE_HOST=memcached-service
      - KONG_X_SESSION_MEMCACHE_PORT="'11211'"
    depends_on:
      - memcached-service
  memcached-service:
    image: memcached:alpine
    ports:
      - "11211:11211"

版本信息

支持的Kong版本

• Kong v3.4.0: https://github.com/revomatico/docker-kong-oidc/blob/master/Dockerfile
• Kong v3.3.1: https://github.com/revomatico/docker-kong-oidc/blob/3.3.1-1/Dockerfile
• Kong v3.3.0: https://github.com/revomatico/docker-kong-oidc/blob/3.3.0-1/Dockerfile
• Kong v3.2.2: https://github.com/revomatico/docker-kong-oidc/blob/3.2.2-4/Dockerfile
• Kong v3.2.1: https://github.com/revomatico/docker-kong-oidc/blob/3.2.1-2/Dockerfile
• Kong v3.1.1: https://github.com/revomatico/docker-kong-oidc/blob/3.1.1-1/Dockerfile
• Kong v3.1.0: https://github.com/revomatico/docker-kong-oidc/blob/3.1.0-1/Dockerfile
• Kong v3.0.1: https://github.com/revomatico/docker-kong-oidc/blob/3.0.1-1/Dockerfile
• Kong v3.0.0: https://github.com/revomatico/docker-kong-oidc/blob/3.0.0-6/Dockerfile
• Kong v2.8.1: https://github.com/revomatico/docker-kong-oidc/blob/2.8.1-1/Dockerfile
• ...（更多历史版本请参考原仓库）

发布说明（部分重要更新）

• 2023-09-04 [3.4.0-2]：升级kong-oidc插件至1.4.0-1。
• 2023-03-26 [3.2.2-4]：新增KONG_X_NOLOG_LIST_FILE，支持排除指定IP的访问日志。
• 2023-03-21 [3.2.2-1]：升级Kong至3.2.2，基于官方Kong镜像构建。
• 2022-09-08 [3.0.0-1]：升级Kong至3.0.0。
• 2020-07-03 [2.0.5-3]：新增DSHM会话存储支持（基于ngx-distributed-shm）。
• 2019-10-28 [1.4.1-1]：新增SHM会话存储支持。