boxboat/okta-nginx

okta-nginx

镜像概述和主要用途

okta-nginx 是一个 Docker 镜像，通过 Okta OpenID Connect 授权码流程（Authorization Code flow）保护上游服务器（upstream server）。该镜像基于 NGINX，集成 Okta OIDC 认证机制，实现对上游应用的身份验证与授权控制，确保只有通过 Okta 认证的用户才能访问受保护资源。

核心功能和特性

• Okta OIDC 认证集成：基于 Okta 授权码流程实现用户认证，支持 JWT（JSON Web Token）验证
• 反向代理能力：将认证通过的请求代理至指定上游服务器
• 灵活的访问控制：可配置受保护路径（LOCATIONS_PROTECTED）与无需保护路径（LOCATIONS_UNPROTECTED）
• 动态配置更新：支持通过脚本（UPDATE_SCRIPT）定期刷新配置
• 自定义请求头传递：可向上游服务器传递基于 JWT 断言（claims）的自定义请求头
• 多服务器支持：通过环境变量后缀（如 _2、_N）配置多个独立的 NGINX 虚拟主机
• 令牌自动刷新：默认注入 JavaScript 实现 Identity Token 过期前自动刷新（可通过 INJECT_REFRESH_JS 禁用）

使用场景和适用范围

• 需要通过 Okta 进行身份验证的 Web 应用或 API 服务
• 需对特定路径实施访问控制的上游服务（如管理后台、敏感数据接口）
• 多域名或多端口场景下的统一认证入口
• 需要向上游传递用户身份信息（如用户名、用户组）的场景

前提条件

• Okta 开发者账户
• 支持 授权码流程 的 OpenID Connect 应用（在 Okta 开发者控制台创建）

使用方法和配置说明

环境变量

必填环境变量

可选环境变量

使用方法和配置说明（续）

部署示例

Docker Run 命令

bash
docker run -d \
  -p 80:80 \
  -e PROXY_PASS="http://upstream-app:8080" \
  -e CLIENT_ID="your-okta-client-id" \
  -e CLIENT_SECRET="your-okta-client-secret" \
  -e ISSUER="https://your-okta-domain.com/oauth2/default" \
  -e LOGIN_REDIRECT_URL="https://your-app-domain.com/sso/authorization-code/callback" \
  -e LOCATIONS_PROTECTED="/api,/admin" \
  -e LOCATIONS_UNPROTECTED="/public" \
  okta-nginx:latest

Docker Compose 配置

yaml
version: '3'
services:
  okta-nginx:
    image: okta-nginx:latest
    ports:
      - "80:80"
    environment:
      - PROXY_PASS=http://upstream-app:8080
      - CLIENT_ID=your-okta-client-id
      - CLIENT_SECRET=your-okta-client-secret
      - ISSUER=https://your-okta-domain.com/oauth2/default
      - LOGIN_REDIRECT_URL=https://your-app-domain.com/sso/authorization-code/callback
      - LOCATIONS_PROTECTED=/api,/admin
      - LOCATIONS_UNPROTECTED=/public
      - LISTEN=80
      - SERVER_NAME=your-app-domain.com
    depends_on:
      - upstream-app

  upstream-app:
    image: your-upstream-app:latest
    # 上游应用配置...

从源码构建（可选）

若需从源码构建镜像，执行以下步骤：

1. 构建容器：

   bash
   ./docker-build.sh
   

2. 在 vars.env 中设置环境变量（参考上文环境变量说明）

3. 运行容器：

   bash
   ./docker-run.sh
   

传递给上游服务器的认证头

认证通过后，镜像会向上游服务器传递以下标准头：

• X-Forwarded-User：用户唯一标识，取自 JWT 断言中的 sub 字段

自定义 NGINX 配置

添加配置至 http 块

将自定义配置文件（.conf 后缀）挂载至 /etc/nginx/conf.d 目录，文件内容会被包含到 NGINX 的 http 块中。

添加配置至 server 块

创建文件 /etc/nginx/includes/default-server.conf，其内容会被包含到默认 server 块中，用于自定义服务器级配置（如 SSL 证书、额外的 location 块等）。

多服务器支持

通过为环境变量添加数字后缀（从 2 开始），可配置多个独立的 NGINX 虚拟主机（server）。

服务器 2 配置示例（必填变量）

• LISTEN_2：服务器 2 的监听端口（必填）
• SERVER_NAME_2：服务器 2 的虚拟主机名称（必填）
• PROXY_PASS_2：服务器 2 的上游地址（必填）
• LOGIN_REDIRECT_URL_2：服务器 2 的登录回调 URL（必填）

服务器 2 配置示例（可选变量）

• APP_POST_LOGIN_URL_2
• COOKIE_DOMAIN_2
• COOKIE_NAME_2
• LOCATIONS_PROTECTED_2
• LOCATIONS_UNPROTECTED_2
• LOGOUT_REDIRECT_URL_2
• PROXY_SET_HEADER_NAMES_2
• PROXY_SET_HEADER_VALUES_2
• VALIDATE_CLAIMS_TEMPLATE_2

服务器 N 通用规则

对于第 N 个服务器（N ≥ 2）：

• 所有与服务器相关的环境变量需添加 _N 后缀（如 LISTEN_N、SERVER_NAME_N）
• 自定义服务器 N 的 server 块配置需挂载至 /etc/nginx/includes/default-server.N.conf