# OpenID Connect 配置选项

openid-connect 插件与 Keycloak、Auth0 等 OIDC 提供方集成，简化 API 管理中的用户身份认证。<!-- --> <!-- -->配置涵盖插件参数。

## 参数[​](#参数 "参数的直接链接")

请参阅 [插件通用配置](https://docs.apiseven.com/apisix/reference/plugin-common-configurations.md) 了解所有插件可用的配置选项。

该插件支持在字符串类型的配置字段中使用网关引用。使用 `$env://` 前缀引用环境变量中的值，或使用 `$secret://` 前缀引用密钥管理器中的值，例如 HashiCorp Vault 的 [KV 密钥引擎](https://developer.hashicorp.com/vault/docs/secrets/kv)。网关在运行时解析这些引用。ADC 的 `${NAME}` 插值有所不同：ADC 在同步前加载配置文件时解析插值。有关更多信息，请参阅[插件中的环境变量](https://docs.apiseven.com/apisix/reference/environment-variables.md#plugins)和[密钥](https://docs.apiseven.com/apisix/key-concepts/secrets.md)。

* client\_id

  string

  必填

  ***

  客户端 ID。

* client\_secret

  string

  ***

  客户端密钥。该值在存储到 etcd 之前会使用 AES 加密。

  自 API7 企业版 3.9.14 和 APISIX 3.17.0 起，对于不与 OpenID 提供商通信的本地 JWT 验证模式（例如将 `bearer_only` 与 `public_key` 或 `use_jwks` 组合使用），客户端密钥是可选的。使用 `private_key_jwt` 进行客户端身份认证，或授权码流程使用 PKCE 时，客户端密钥也是可选的。对于使用客户端密钥向提供商进行身份认证的流程（例如 Token 内省或不使用 PKCE 的授权码流程），客户端密钥仍为必填项。

* discovery

  string

  必填

  ***

  OpenID 提供商的 well-known 发现文档的 URL，其中包含 [OP API 端点](https://samples.auth0.com/.well-known/openid-configuration) 列表。插件可以直接使用发现文档中的端点。你也可以单独配置这些端点，这将优先于发现文档中提供的端点。

* scope

  string

  默认值：`openid`

  ***

  对应于应返回的有关已认证用户信息的 OIDC 范围，也称为 [claims](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims)。这用于通过适当的权限对用户进行授权。默认值为 `openid`，这是 OIDC 返回唯一标识已认证用户的 `sub` claim 所需的范围。

  其他范围可以追加并用空格分隔，例如 `openid email profile`。

* required\_scopes

  array\[string]

  ***

  授权所需的范围。如果缺少任一必需范围，插件将以 `403 Forbidden` 拒绝请求。

  使用 Bearer Token 内省时，范围从内省响应中读取。在授权码流程中，先从访问 Token 读取范围，再从 ID Token 读取。如果无法确定会话获授的范围，则拒绝该会话。授权码会话的范围校验自 APISIX 3.18.0、API7 企业版 3.9.19 和 3.10.6 起支持。

* realm

  string

  默认值：`apisix`

  ***

  因身份认证失败而返回 `401 Unauthorized` 响应时，[`WWW-Authenticate`](https://www.rfc-editor.org/rfc/rfc6750#section-3) 响应头中的 Realm。例如：

  * 如果 `realm` 设置为 `apisix-oidc`，401 响应将包含以下响应头：

    ```
    WWW-Authenticate: Bearer realm="apisix-oidc"
    ```

  * 如果未配置 `realm`，401 响应将包含以下响应头：

    ```
    WWW-Authenticate: Bearer realm="apisix"
    ```

* claim\_validator

  object

  ***

  JWT Claim 验证配置。

  * issuer

    object

    ***

    Claim 颁发者验证配置。

    * valid\_issuers

      array\[string]

      ***

      本地 JWT 验证信任的颁发者。省略时，APISIX 使用发现文档中的颁发者；无法确定受信任颁发者时，APISIX 会拒绝 Token。API7 企业版 3.9.18 和 3.10.7 在发现失败时会跳过颁发者验证，除非显式配置该列表；3.9.21 和 3.10.8 则会拒绝请求。

      在 API7 企业版 3.9.21、3.10.8 和 APISIX 3.19.0 中，显式列表也适用于远程内省。响应必须包含与列表匹配的字符串 `iss`，否则身份认证返回 HTTP 401。空列表会拒绝所有颁发者；省略该字段则不会对内省执行此检查。

      API7 企业版 3.10.7 不会将该列表应用于远程内省响应。

  * audience

    object

    ***

    受众 Claim 验证配置。

    * claim

      string

      默认值：`aud`

      ***

      包含受众的 Claim 名称。

    * required

      boolean

      默认值：`false`

      ***

      如果为 true，则必须提供受众 Claim，其名称由 `claim` 定义。

      例如，假设 `claim_validator` 配置如下：

      ```json
      {
        "audience": {
          "claim": "custom_claim",
          "required": true
        }
      }
      ```

      如果请求中不存在 `custom_claim`，则会返回 `required audience claim not present` 错误。

    * match\_with\_client\_id

      boolean

      默认值：`false`

      ***

      如果为 true，则要求受众与客户端 ID 匹配。如果受众是字符串，则必须与客户端 ID 完全匹配；如果受众是字符串数组，则必须至少有一个值匹配。缺少受众 Claim 的 Token 也会被拒绝。缺失受众 Claim 的校验自 APISIX 3.18.0、API7 企业版 3.9.19 和 3.10.6 起支持。

      此要求在 [OpenID Connect 规范](https://openid.net/specs/openid-connect-core-1_0-final.html) 中说明，以确保 Token 是针对特定客户端的。

* claim\_schema

  object

  ***

  用于验证 OIDC 响应中返回的 Claim 的 JSON Schema。例如，schema `{"type":"object","properties":{"access_token":{"type":"string"}},"required":["access_token"]}` 确保响应包含名为 `access_token` 的必需字符串字段。

  从 APISIX 3.14.0 和 API7 企业版 3.9.2 起可用。

* bearer\_only

  boolean

  默认值：`false`

  ***

  如果为 true，则严格要求请求中包含 Bearer 访问 Token 以进行身份认证。

* logout\_path

  string

  默认值：`/logout`

  ***

  激活注销的路径。

* post\_logout\_redirect\_uri

  string

  ***

  `logout_path` 收到注销请求后将用户重定向到的 URL。

* redirect\_uri

  string

  默认值：`` `${ngx.var.request_uri}/.apisix/redirect` ``

  ***

  与 OpenID 提供商认证后重定向到的 URI。

  请配置包含协议方案和主机的完全限定 URI。其路径应当匹配路由，但不能与受保护的请求路径完全相同。例如，如果路由 `uri` 为 `/api/v1/*`，请把 `redirect_uri` 设为 `https://gateway.example.com/api/v1/redirect`。

  如果未配置 `redirect_uri`，或其值是以 `/` 开头的根相对路径，网关会根据请求的协议方案和主机构建 URI。它会保留请求中显式指定的端口，并且仅当直接代理位于 `apisix.trusted_addresses` 中时才使用转发的来源请求头。

  完全限定 URI 不依赖从请求推导的来源。请在 OpenID 提供商中把同一 URI 配置为允许的重定向 URI。

* timeout

  integer

  默认值：`3`

  有效值：

  大于 0

  ***

  请求超时时间（秒）。

* ssl\_verify

  boolean

  默认值：`true`

  ***

  如果为 `true`，则验证 OpenID 提供商的 SSL 证书。

  自 APISIX 3.16.0 和 API7 企业版 3.9.8 起，默认值由 `false` 更改为 `true`。这是一个不兼容变更。

* introspection\_endpoint

  string

  ***

  OpenID 提供商用于内省访问 Token 的[Token 内省](https://datatracker.ietf.org/doc/html/rfc7662)端点 URL。如果未设置，则使用 well-known 发现文档中提供的内省端点作为后备。

* introspection\_endpoint\_auth\_method

  string

  默认值：`client_secret_basic`

  ***

  Token 内省端点的身份认证方法。该值应为 well-known 发现文档中 `introspection_endpoint_auth_methods_supported` [授权服务器元数据](https://www.rfc-editor.org/rfc/rfc8414.html)指定的身份认证方法之一，例如 `client_secret_basic`、`client_secret_post`、`private_key_jwt` 和 `client_secret_jwt`。

  使用默认的 `client_secret_basic` 时，客户端凭据仅通过 `Authorization` 请求头发送。如果身份提供商要求在内省请求体中接收凭据，请将此字段设置为 `client_secret_post`。

* token\_endpoint\_auth\_method

  string

  默认值：`client_secret_basic`

  ***

  Token 端点的身份认证方法。该值应为 well-known 发现文档中 `token_endpoint_auth_methods_supported` [授权服务器元数据](https://www.rfc-editor.org/rfc/rfc8414.html) 指定的身份认证方法之一，例如 `client_secret_basic`、`client_secret_post`、`private_key_jwt` 和 `client_secret_jwt`。

  如果插件不支持配置的方法，则忽略该配置，并使用 OpenID 提供商公布的第一个可用方法。如果插件支持配置的方法，但 `token_endpoint_auth_methods_supported` 已提供且不包含该方法，则 Token 端点身份认证失败。

* client\_rsa\_private\_key

  string

  ***

  用于签署客户端断言 JWT 的私钥。当 Token、内省或 PAR 端点选择 `private_key_jwt` 时必填。密钥类型必须与 `client_jwt_assertion_alg` 匹配：`RS*` 使用 RSA 密钥，`ES*` 使用对应曲线上的 EC 密钥。

  该值在存储到 etcd 前会使用 AES 加密。

* client\_rsa\_private\_key\_id

  string

  ***

  端点选择 `private_key_jwt` 时，签名客户端断言 JWT 中使用的可选密钥 ID。

* client\_jwt\_assertion\_expires\_in

  integer

  默认值：`60`

  ***

  Token、内省或 PAR 端点使用 `private_key_jwt` 或 `client_secret_jwt` 时，客户端断言 JWT 的生命周期（秒）。

* public\_key

  string

  ***

  如果使用非对称算法，则用于验证 JWT 签名的公钥。提供此值以执行 Token 验证将跳过客户端凭据流程中的 Token 内省。

  你可以使用 `-----BEGIN PUBLIC KEY-----\n……\n-----END PUBLIC KEY-----` 格式传递公钥。

* token\_signing\_alg\_values\_expected

  string

  ***

  用于签署 JWT 的算法，例如 `RS256`。

* set\_access\_token\_header

  boolean

  默认值：`true`

  ***

  如果为 `true`，则在请求头中设置已认证请求所使用的访问 Token。默认使用 `X-Access-Token` 请求头。网关会先清除客户端提供的同名值，再设置该 Token。

* access\_token\_in\_authorization\_header

  boolean

  默认值：`false`

  ***

  如果为 `true` 且 `set_access_token_header` 也为 `true`，则在 `Authorization` 请求头中设置访问 Token。

* accept\_none\_alg

  boolean

  默认值：`false`

  ***

  如果 OpenID 提供商不对其 ID Token 进行签名（例如当签名算法设置为 `none` 时），则设置为 true。

* use\_jwks

  boolean

  默认值：`false`

  ***

  如果为 true 且未设置 `public_key`，则使用 JWKS 验证 JWT 签名并跳过客户端凭据流程中的 Token 内省。JWKS 端点从发现文档中解析。

* jwk\_expires\_in

  integer

  默认值：`86400`

  ***

  JWK 缓存的过期时间（秒）。

* jwt\_verification\_cache\_ignore

  boolean

  默认值：`false`

  ***

  如果为 true，则强制重新验证 Bearer Token 并忽略任何现有的缓存验证结果。

* cache\_segment

  string

  ***

  缓存段的可选名称，用于分隔和区分 Token 内省或 JWT 验证使用的缓存。

* use\_pkce

  boolean

  默认值：`false`

  ***

  如果为 true，则对授权码流程使用用于代码交换的证明密钥 (PKCE)，如 [RFC 7636](https://datatracker.ietf.org/doc/html/rfc7636) 中所定义。

* set\_id\_token\_header

  boolean

  默认值：`true`

  ***

  如果为 true 且经过验证的 ID Token 可用，则在 `X-ID-Token` 请求头中设置经过 Base64 编码的解码后 Claim。该值不是签名 JWT，无法使用身份提供商的 JWKS 进行验证。网关会先清除客户端提供的同名值。

* set\_userinfo\_header

  boolean

  默认值：`true`

  ***

  如果为 true 且用户信息数据可用，则在 `X-Userinfo` 请求头中设置该值。网关会先清除客户端提供的同名值。

* set\_raw\_id\_token\_header

  boolean

  默认值：`false`

  ***

  如果为 true 且原始 ID Token 可用，则把身份提供商签发的原始签名 JWT 添加到 `X-Raw-ID-Token` 请求头中。该 Token 会持久化到会话，以便上游服务使用身份提供商的 JWKS 进行验证。自 API7 企业版 3.9.17 和 3.10.4 以及 APISIX 3.18.0 起可用。

  原始 ID Token 属于 bearer 凭证。请仅对可信上游启用，并确保该请求头不会被写入访问日志或回显给客户端。

* set\_refresh\_token\_header

  boolean

  默认值：`false`

  ***

  如果为 true 且从身份提供商获取的刷新 Token 可用，则在 `X-Refresh-Token` 请求头中设置该值。网关会先清除客户端提供的同名值。

* upstream\_headers

  array\[object]

  ***

  要作为请求头转发到上游的 Claim。每个条目将一个 Claim 映射到一个请求头。至少包含一个条目。

  自 APISIX 3.20.0 和 API7 Enterprise 3.10.10 起可用。

  网关会先清除所有已声明的请求头，然后只使用已验证的 Claim 设置它们。客户端无法自行提供这些请求头的值，包括 `unauth_action` 设置为 `pass` 时放行的请求。

  使用 `bearer_only`、`public_key`、`use_jwks` 或内省时，Claim 来自已验证的访问 Token 载荷或内省响应。在授权码流程中，Claim 来自 ID Token；ID Token 中不包含的 Claim 再从用户信息中获取。值为 `null` 或 `false` 的 Claim 视为不包含，此时会使用下一个来源。

  * header

    string

    必填

    ***

    上游请求头的名称。

    只能包含字母、数字以及字符 ``!#$%&'*+-.^_`|~``。

  * path

    array\[string]

    必填

    ***

    指向 Claim 的键，每一层嵌套对应一个键。例如，`["org", "id"]` 读取 `org` Claim 中的 `id`。

    至少包含一个键，且每个键都必须是非空字符串。

    键按字面匹配，因此包含 `://`、`/` 或 `.` 的 Claim 名称是一个单独的键。

    字符串按原样转发。数字和 `true` 以文本形式转发。数组和对象以 base64 编码的 JSON 转发。空数组或空对象转发为 `e30=`，即 `{}` 的 base64 编码。如果 Claim 不存在，或值为 `null`、`false` 或空字符串，则不设置该请求头。

* session

  object

  ***

  当 `bearer_only` 为 `false` 且插件使用授权码流程时使用的会话配置。

  * secret

    string

    有效值：

    至少 16 个字符

    ***

    当 `bearer_only` 为 `false` 时，用于会话加密和 HMAC 操作的密钥。

    当 `bearer_only` 为 `false` 时，此字段为必填项。该要求自 API7 企业版 3.9.2 和 APISIX 3.14.0 起生效。

    API7 网关使用 AES 对该值进行静态加密；当启用 `apisix.data_encryption.enable_encrypt_fields` 时，APISIX 会在写入 etcd 前对其加密。

  * cookie\_name

    string

    ***

    会话 Cookie 的名称。对应 lua-resty-session 的 `cookie_name` 选项。

    自 API7 企业版 3.9.14 和 APISIX 3.17.0 起可用。

  * cookie\_path

    string

    ***

    会话 Cookie 的路径范围。对应 lua-resty-session 的 `cookie_path` 选项。

    自 API7 企业版 3.9.14 和 APISIX 3.17.0 起可用。

  * cookie\_domain

    string

    ***

    会话 Cookie 的域范围。对应 lua-resty-session 的 `cookie_domain` 选项。

    自 API7 企业版 3.9.14 和 APISIX 3.17.0 起可用。

  * cookie\_secure

    boolean

    ***

    如果为 true，则在会话 Cookie 上设置 `Secure` 属性。对应 lua-resty-session 的 `cookie_secure` 选项。

    自 API7 企业版 3.9.14 和 APISIX 3.17.0 起可用。

  * cookie\_http\_only

    boolean

    ***

    如果为 true，则在会话 Cookie 上设置 `HttpOnly` 属性。对应 lua-resty-session 的 `cookie_http_only` 选项。

    自 API7 企业版 3.9.14 和 APISIX 3.17.0 起可用。

  * cookie\_same\_site

    string

    有效值：

    `Strict`、`Lax`、`None` 或 `Default`

    ***

    会话 Cookie 的 SameSite 属性。对应 lua-resty-session 的 `cookie_same_site` 选项。

    自 API7 企业版 3.9.14 和 APISIX 3.17.0 起可用。

  * idling\_timeout

    integer

    默认值：`900`

    ***

    最长空闲时间（秒）。超过该时间后会话失效，下一次访问受保护资源的请求会启动新的授权流程。对应 lua-resty-session 的 `idling_timeout` 选项。

    自 API7 企业版 3.9.14 和 APISIX 3.17.0 起可用。

  * rolling\_timeout

    integer

    默认值：`3600`

    ***

    会话必须续期前的最长时间（秒）。对应 lua-resty-session 的 `rolling_timeout` 选项。

    自 API7 企业版 3.9.14 和 APISIX 3.17.0 起可用。

  * absolute\_timeout

    integer

    默认值：`86400`

    ***

    会话的绝对生命周期（秒），超过该时间后无论是否活跃，会话都会过期。对应 lua-resty-session 的 `absolute_timeout` 选项。

    自 API7 企业版 3.9.14 和 APISIX 3.17.0 起可用。

  * cookie

    object

    ***

    Cookie 配置。已废弃，仅为与 lua-resty-session 3.x schema 向后兼容而保留。请改用扁平的 `session.*` 选项，例如 `cookie_name` 和 `absolute_timeout`。

    * lifetime

      integer

      ***

      Cookie 生命周期（秒）。已废弃。配置此字段且未设置 `absolute_timeout` 时，运行时会将此值映射到 `absolute_timeout`。省略此字段时，使用 `absolute_timeout` 的默认值。

  * storage

    string

    默认值：`cookie`

    有效值：

    `cookie` 或 `redis`

    ***

    会话存储后端。当设置为 `redis` 时，会话存储在 Redis 中而非 Cookie 中。

    自 API7 企业版 3.9.15 和 APISIX 3.16.0 起可用。

  * redis

    object

    ***

    Redis 连接配置。当 `storage` 为 `redis` 时必填。

    自 API7 企业版 3.9.15 和 APISIX 3.16.0 起可用。

    * host

      string

      默认值：`127.0.0.1`

      ***

      Redis 主机。

    * port

      integer

      默认值：`6379`

      有效值：

      大于或等于 1

      ***

      Redis 端口。

    * username

      string

      ***

      Redis 用户名。

    * password

      string

      ***

      Redis 密码。该值在存储到 etcd 前会使用 AES 加密。

    * database

      integer

      默认值：`0`

      有效值：

      大于或等于 0

      ***

      Redis 数据库索引。

    * prefix

      string

      默认值：`sessions`

      ***

      Redis 会话 key 的前缀。

    * ssl

      boolean

      默认值：`false`

      ***

      如果为 true，则使用 SSL 连接 Redis。

    * ssl\_verify

      boolean

      默认值：`true`

      ***

      如果为 true，则校验 Redis 服务器的 SSL 证书。

    * server\_name

      string

      ***

      连接 Redis 时用于 TLS SNI 的服务器名称。

    * connect\_timeout

      integer

      默认值：`1000`

      有效值：

      大于或等于 1

      ***

      Redis 连接超时时间（毫秒）。

    * send\_timeout

      integer

      默认值：`1000`

      有效值：

      大于或等于 1

      ***

      Redis 发送超时时间（毫秒）。

    * read\_timeout

      integer

      默认值：`1000`

      有效值：

      大于或等于 1

      ***

      Redis 读取超时时间（毫秒）。

    * keepalive\_timeout

      integer

      默认值：`10000`

      有效值：

      大于或等于 1000

      ***

      Redis keepalive 超时时间（毫秒）。

* unauth\_action

  string

  默认值：`auth`

  有效值：

  `auth`、`deny` 或 `pass`

  ***

  未经身份认证的请求的操作。

  当设置为 `auth` 时，重定向到 OpenID 提供商的身份认证端点。

  当设置为 `pass` 时，允许请求通过而无需身份认证。

  当设置为 `deny` 时，返回 401 未经身份认证的响应，而不是启动授权码授予流程。

* proxy\_opts

  object

  ***

  OpenID 提供商所在的代理服务器的配置。

  * http\_proxy

    string

    ***

    HTTP 请求的代理服务器地址，例如 `http://<proxy_host>:<proxy_port>`。

  * https\_proxy

    string

    ***

    HTTPS 请求的代理服务器地址，例如 `http://<proxy_host>:<proxy_port>`。

  * http\_proxy\_authorization

    string

    ***

    用于 `http_proxy` 的默认 `Proxy-Authorization` 请求头值。可以使用自定义 `Proxy-Authorization` 请求头覆盖。

  * https\_proxy\_authorization

    string

    ***

    用于 `https_proxy` 的默认 `Proxy-Authorization` 请求头值。不能使用自定义 `Proxy-Authorization` 请求头覆盖，因为对于 HTTPS，授权在建立连接时完成。

  * no\_proxy

    string

    ***

    不应被代理的主机的逗号分隔列表。

* authorization\_params

  object

  ***

  发送到授权端点的请求中的附加参数。

* renew\_access\_token\_on\_expiry

  boolean

  默认值：`true`

  ***

  如果为 true，则在访问 Token 过期或刷新 Token 可用时尝试静默更新访问 Token。如果 Token 更新失败，则重定向用户以重新进行身份认证。

* access\_token\_expires\_in

  integer

  默认值：`3600`

  ***

  如果 Token 端点响应中不存在 `expires_in` 属性，则为访问 Token 的生命周期（秒）。

* refresh\_session\_interval

  integer

  ***

  无需重新身份认证即可刷新用户 ID Token 的时间间隔。未设置时，插件不会定期刷新 ID Token。

* iat\_slack

  integer

  默认值：`120`

  ***

  ID Token 中 `iat` Claim 的时钟偏差容差（秒）。

* introspection\_expiry\_claim

  string

  默认值：`exp`

  ***

  过期时间 Claim 的名称，用于控制缓存和内省的访问 Token 的 TTL。

* introspection\_interval

  integer

  默认值：`0`

  ***

  缓存和内省的访问 Token 的 TTL（秒）。

  默认值为 0，表示不使用此选项，插件默认使用由 `introspection_expiry_claim` 中定义的过期时间 Claim 传递的 TTL。

  如果 `introspection_interval` 大于 0 且小于由 `introspection_expiry_claim` 中定义的过期时间 Claim 传递的 TTL，则使用 `introspection_interval`。

* introspection\_addon\_headers

  array\[string]

  ***

  用于向内省 HTTP 请求附加额外的请求头值。如果原始请求中不存在指定的请求头，则不会附加该值。

* accept\_unsupported\_alg

  boolean

  默认值：`true`

  ***

  如果 ID Token 使用了网关不支持的预期签名算法，设置为 true 会在不验证签名的情况下继续；设置为 false 会拒绝该 Token。

  对于安全敏感的部署，请将其设置为 false，除非你明确接受 ID Token 签名未验证的风险。设置为 false 不会增加对其他签名算法的支持。

  在 APISIX 3.18.0 以及 API7 网关 3.9.18 和 3.10.5 中，ID Token 验证路径支持 `RS256`、`RS512`、`HS256` 和 `HS512`，不验证 `PS*`、`ES*` 或 `EdDSA` 签名。

* access\_token\_expires\_leeway

  integer

  默认值：`0`

  ***

  访问 Token 更新的过期回旋余地（秒）。当设置为大于 0 的值时，Token 更新将在 Token 过期前的设定时间进行。这避免了在到达资源服务器时访问 Token 刚好过期的情况。

* force\_reauthorize

  boolean

  默认值：`false`

  ***

  如果为 true，即使已缓存 Token，也执行授权流程。

* use\_nonce

  boolean

  默认值：`false`

  ***

  如果为 true，则在授权请求中启用 nonce 参数。

* revoke\_tokens\_on\_logout

  boolean

  默认值：`false`

  ***

  如果为 true，则在撤销端点通知授权服务器不再需要先前获取的刷新或访问 Token。

* session\_contents

  object

  ***

  应存储在会话中的内容，用于最小化会话数据的大小。未设置时，所有内容都包含在会话中。

  * id\_token

    boolean

    ***

    如果为 true，则在会话中存储 ID Token。

  * access\_token

    boolean

    ***

    如果为 true，则在会话中存储访问 Token 和刷新 Token。

  * enc\_id\_token

    boolean

    ***

    如果为 true，则在会话中存储加密的 ID Token。

  * user

    boolean

    ***

    如果为 true，则在会话中存储用户信息。

* par

  object

  ***

  推送式授权请求（PAR）配置，定义见 [RFC 9126](https://datatracker.ietf.org/doc/html/rfc9126)。启用 PAR 后，网关通过后通道把授权请求参数发送给身份提供商，并只用返回的 `request_uri` 重定向用户代理，因此这些参数不会经过浏览器。

  请通过此嵌套对象配置 PAR。插件会拒绝扁平选项 `use_par`、`pushed_authorization_request_endpoint` 和 `pushed_authorization_request_endpoint_auth_method`，以便验证端点和身份认证方法。

  自 API7 企业版 3.9.18 和 3.10.5 以及 APISIX 3.18.0 起可用。

  * enabled

    boolean

    默认值：`false`

    ***

    如果为 true，则把授权请求推送到 PAR 端点，而不是在重定向到授权端点时携带其参数。

  * endpoint

    string

    ***

    身份提供商 PAR 端点的 URL。未设置时使用其发现文档中声明的端点。

  * endpoint\_auth\_method

    string

    有效值：

    `client_secret_basic`、`client_secret_post`、`client_secret_jwt` 或 `private_key_jwt`

    ***

    PAR 端点使用的客户端身份认证方法。未设置时沿用 Token 端点配置的方法。`private_key_jwt` 需要 `client_rsa_private_key`，`client_secret_jwt` 需要 `client_secret`。如果所选方法无法使用，PAR 请求将失败。

* dpop

  object

  ***

  发送方约束 Token（DPoP）配置，定义见 [RFC 9449](https://datatracker.ietf.org/doc/html/rfc9449)。网关会为每次 Token 请求签署证明 JWT，将签发的访问 Token 绑定到所配置的密钥。如果资源端点启用了 DPoP 保护，即使访问 Token 被窃取，缺少该密钥也无法重放。同时设置 `par.enabled` 时，密钥指纹会以 `dpop_jkt` 随推送请求一并发送。

  网关充当向身份提供商发起 Token 请求和用户信息请求的 DPoP 客户端。此配置不会验证外部 API 客户端入站请求中的 DPoP 证明。

  如果 Token 响应的 `token_type` 不是 `DPoP`，网关会拒绝该响应。Token 请求收到携带 `DPoP-Nonce` 请求头的 `400` 或 `401` 响应时会重试一次；用户信息请求收到携带该请求头的 `401` 响应时也会重试一次。

  请通过此嵌套对象配置 DPoP。插件会拒绝扁平选项 `use_dpop`、`dpop_signing_alg`、`dpop_private_key` 和 `dpop_public_jwk`，以便应用 DPoP 验证和加密字段处理。

  自 API7 企业版 3.9.18 和 3.10.5 以及 APISIX 3.18.0 起可用。

  * enabled

    boolean

    默认值：`false`

    ***

    如果为 true，则在 Token 请求中携带 DPoP proof JWT。启用时 `private_key` 与 `public_jwk` 均为必填。

  * private\_key

    string

    ***

    用于签名 DPoP proof JWT 的 PEM 格式私钥。启用数据面数据加密时，该字段会落盘加密。

  * public\_jwk

    object

    ***

    与 `private_key` 匹配的公开 JWK，会嵌入 proof JWT 的头部。其中不得包含私钥参数。

  * signing\_alg

    string

    默认值：`ES256`

    有效值：

    `ES256`、`RS256` 或 `PS256`

    ***

    用于签署 DPoP proof JWT 的算法。该算法必须与所配置密钥的类型匹配；如果发现文档列出了支持的 DPoP 算法，还必须是身份提供商接受的算法。

* client\_jwt\_assertion\_alg

  string

  有效值：

  `HS256`、`HS512`、`RS256`、`RS512`、`ES256` 或 `ES512`

  ***

  当端点认证方法为 `client_secret_jwt` 或 `private_key_jwt` 时，用于签名客户端断言 JWT 的算法。

  `client_secret_jwt` 应使用 `HS*` 算法，`private_key_jwt` 应使用 `RS*` 或 `ES*` 算法。算法必须与 `client_rsa_private_key` 匹配；如果发现文档列出了支持的客户端断言算法，还必须是身份提供商接受的算法。所有端点共用一个配置的算法。

  自 API7 企业版 3.9.18 和 3.10.5 以及 APISIX 3.18.0 起可用。

* client\_jwt\_assertion\_audience

  string

  ***

  客户端断言 JWT 的 audience Claim。未设置时使用正在调用的端点 URL。当网关访问的是内部端点 URL，而身份提供商要求 audience 使用其外部 URL 时，请配置此字段。

  自 API7 企业版 3.9.18 和 3.10.5 以及 APISIX 3.18.0 起可用。
