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 开发者控制台创建）

使用方法和配置说明

环境变量

必填环境变量

变量名	描述
`PROXY_PASS`	上游服务器地址，需包含协议、主机和端口，例如 `http://localhost:8080`
`CLIENT_ID`	Okta OIDC 应用的客户端 ID，可在 Okta 应用「General」标签页获取
`CLIENT_SECRET`	Okta OIDC 应用的客户端密钥，可在 Okta 应用「General」标签页获取
`ISSUER`	Okta 授权服务器 URL，格式为 `{Okta 组织 URL}/oauth2/default`，例如 `[***]`（组织 URL 可在 Okta 控制台首页右上角获取）
`LOGIN_REDIRECT_URL`	登录回调 URL，必须在 Okta 应用「General」标签页的「登录重定向 URI」中配置。默认路径为 `/sso/authorization-code/callback`，若设置 `SSO_PATH` 则为 `${SSO_PATH}/authorization-code/callback`

可选环境变量

变量名	默认值	描述
`APP_POST_LOGIN_URL`	-	认证完成后重定向的应用特定 URL，原始请求 URL 通过 `state` 查询参数传递
`COOKIE_DOMAIN`	当前域名	Cookie 作用域，设置后可支持子域名共享（例如 `.example.com`）
`COOKIE_NAME`	`okta-jwt`	存储 Identity Token 的 Cookie 名称
`INJECT_REFRESH_JS`	`true`	是否注入自动刷新 Token 的 JavaScript，设为 `false` 禁用
`ENDPOINT_AUTHORIZE`	`${ISSUER}/v1/authorize`	授权端点 URL
`ENDPOINT_LOGOUT`	`${ISSUER}/v1/logout`	登出端点 URL
`ENDPOINT_TOKEN`	`${ISSUER}/v1/token`	Token 获取端点 URL
`LISTEN`	`80`	NGINX 监听端口，支持 TLS 或 Unix 套接字（参考 nginx listen）
`LOCATIONS_PROTECTED`	`/`	需保护的路径列表（逗号分隔），例如 `/api,/admin`
`LOCATIONS_UNPROTECTED`	禁用	无需保护的路径列表（逗号分隔），直接代理至上游服务器
`LOGOUT_REDIRECT_URL`	应用源 URL（origin）	登出后重定向 URL（可相对或绝对路径），登出路径为 `/sso/logout` 或 `${SSO_PATH}/logout`
`PROXY_SET_HEADER_NAMES`	无	需传递给上游的请求头名称列表（逗号分隔），需与 `PROXY_SET_HEADER_VALUES` 配合使用
`PROXY_SET_HEADER_VALUES`	无	与 `PROXY_SET_HEADER_NAMES` 对应的头值列表（逗号分隔），支持基于断言的 Go 模板（例如 `{{.groups}}`，可使用 sprig 函数）
`REQUEST_TIMEOUT`	`30`	调用 Okta 端点的超时时间（秒）
`SERVER_NAME`	`_`	NGINX 虚拟主机名称（参考 nginx server_name）
`SSO_PATH`	`/sso/`	SSO 错误和刷新端点的路径，需包含首尾斜杠（例如 `/okta-sso/`）
`UPDATE_SCRIPT`	无	配置更新脚本路径（可执行 shell 脚本），首次更新传递参数 `true`，后续传递 `false`
`UPDATE_PERIOD_SECONDS`	`60`	若设置 `UPDATE_SCRIPT`，脚本的执行周期（秒，启动时执行一次，之后按周期执行）
`VALIDATE_CLAIMS_TEMPLATE`	禁用	断言验证模板（Go 模板），需返回 `true` 或 `1`，例如 `{{if has "admin" .groups}}true{{else}}false{{end}}`（支持 sprig 函数）

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

部署示例

Docker Run 命令

bash
docker run -d \
  -p 80:80 \
  -e PROXY_PASS="[***]" \
  -e CLIENT_ID="your-okta-client-id" \
  -e CLIENT_SECRET="your-okta-client-secret" \
  -e ISSUER="[***]" \
  -e LOGIN_REDIRECT_URL="[***]" \
  -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=[***]
      - CLIENT_ID=your-okta-client-id
      - CLIENT_SECRET=your-okta-client-secret
      - ISSUER=[***]
      - LOGIN_REDIRECT_URL=[***]
      - 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
    # 上游应用配置...