ngx_http_oidc_module 模块详解-CSDN博客

本文链接：https://blog.csdn.net/weixin_43114209/article/details/147965426

一、模块概述

ngx_http_oidc_module 让 Nginx 成为 OpenID Connect（OIDC）的客户端，支持以下流程：

动态发现：从 Provider 的 .well-known/openid-configuration 获取元数据（需开启 resolver）。
授权码流程：重定向到 OIDC 授权端点登录，获取 Code；
交换 Token：携带 Code 向 Token 端点请求 ID Token & Access Token；
会话管理：将 Token 保存在 Key-Value 存储并通过 Cookie 维持会话；
反向代理：登录成功后，可将 JWT Claim 注入请求头，转发给后端服务。

可与其他访问控制模块（如 auth_jwt）通过 satisfy 指令结合使用。

二、前置条件

商业版 专属模块。
必须有 动态 DNS 解析（resolver 指令）。
OIDC Provider 端须正确配置 Redirect URI 指向 Nginx。

三、示例配置

http {
    # DNS 动态解析，用于获取 Provider 的 metadata 和 Token 端点
    resolver 10.0.0.1;

    # 定义一个 OIDC Provider 实例
    oidc_provider my_idp {
        issuer        "https://provider.domain";
        client_id     "your_client_id";
        client_secret "your_client_secret";
        # 可选自定义：
        # config_url      https://provider.domain/custom/.well-known/openid-configuration;
        # redirect_uri    /custom_callback;
        # scope           openid email profile;
        # extra_auth_args "prompt=login";
        # cookie_name     my_oidc_session;
        # session_store   redis_store;
        # session_timeout 12h;
        # ssl_trusted_certificate /etc/ssl/certs/ca.pem;
        # ssl_crl                /etc/ssl/crl/crl.pem;
    }

    server {
        listen 443 ssl;
        server_name app.example.com;

        location / {
            # 启用 OIDC 身份验证，指定上面定义的 Provider
            auth_oidc my_idp;

            # 将用户标识（sub Claim）传给后端
            proxy_set_header X-User-Id $oidc_claim_sub;
            proxy_pass       http://backend;
        }
    }
}

在 Provider 端必须注册回调地址 https://app.example.com/oidc_callback（与 redirect_uri 保持一致）。

四、指令详解

1. `oidc_provider`

Syntax:   oidc_provider <name> { … }
Context:  http

功能：定义一个 OIDC Provider 协议上下文，包含以下必选／可选参数。

2. `auth_oidc`

Syntax:   auth_oidc <name> | off;
Default:  off
Context:  http, server, location

功能：在当前上下文启用或关闭 OIDC 登录，<name> 对应 oidc_provider 定义。

3. `issuer`

Syntax:   issuer <URL>;
Context:  oidc_provider

功能：设置 OpenID Provider 的 Issuer URL，必须以 HTTPS 开头，且与其 metadata 中 issuer 字段完全一致。

4. `client_id`

Syntax:   client_id <string>;
Context:  oidc_provider

功能：Relying Party（客户端）的 ID。

5. `client_secret`

Syntax:   client_secret <string>;
Context:  oidc_provider

功能：用于与 Provider 交换 Token 的密钥。

6. `config_url`

Syntax:   config_url <URL>;
Default:  <issuer>/.well-known/openid-configuration
Context:  oidc_provider

功能：自定义从何处获取 OIDC 配置元数据。

7. `redirect_uri`

Syntax:   redirect_uri <uri>;
Default:  /oidc_callback
Context:  oidc_provider

功能：OIDC 授权服务器在用户授权后回调的路径，必须与 Provider 上注册一致。

8. `scope`

Syntax:   scope <scope> …;
Default:  openid
Context:  oidc_provider

功能：请求的授权范围，至少需包含 openid。

9. `cookie_name`

Syntax:   cookie_name <name>;
Default:  NGX_OIDC_SESSION
Context:  oidc_provider

功能：保存会话 ID 的 Cookie 名称。

10. `session_store`

Syntax:   session_store <name>;
Context:  oidc_provider

功能：指定会话（Token）存储后端，默认自动创建 oidc_default_store_<provider> 8 MB KV 库；如使用 Redis、Memcached、自定义 DB 请在此注册。

11. `session_timeout`

Syntax:   session_timeout <time>;
Default:  8h
Context:  oidc_provider

功能：会话过期时间，超过该周期未刷新则删除。

12. `extra_auth_args`

Syntax:   extra_auth_args "<query_string>";
Context:  oidc_provider

功能：在授权请求 URL 上追加自定义查询参数（如 prompt=login、display=page 等）。

13. `ssl_trusted_certificate`

Syntax:   ssl_trusted_certificate <file>;
Default:  系统默认 CA
Context:  oidc_provider

功能：用于验证 Provider HTTPS 端点证书的信任根。

14. `ssl_crl`

Syntax:   ssl_crl <file>;
Context:  oidc_provider

功能：提供证书吊销列表（CRL），以增强证书验证安全性。

五、嵌入变量

变量	含义
`$oidc_id_token`	原始 ID Token
`$oidc_access_token`	Access Token
`$oidc_claim_<name>`	ID Token 中顶层 Claim 值

示例：将用户邮箱注入请求头
proxy_set_header X-User-Email $oidc_claim_email;

如需读取嵌套 Claim，可结合 auth_jwt 模块：

http {
    auth_jwt_claim_set $postal_code address postal_code;

    server {
        auth_oidc my_idp;
        auth_jwt off token=$oidc_id_token;

        proxy_set_header X-Postal-Code $postal_code;
    }
}