OpenID Connect | API 网关文档

参数

请参阅插件通用配置了解所有插件可用的配置选项。

该插件支持使用 env:// 前缀引用环境变量中的敏感参数值，或使用 secret:// 前缀引用 Secret 管理器（如 HashiCorp Vault 的 KV 密钥引擎中的值。更多信息，请参阅环境变量中的插件和Secrets。

client_id
string
required
客户端 ID。
client_secret
string
required
客户端密钥。该值在存储到 etcd 之前会使用 AES 加密。
discovery
string
required
OpenID 提供商的 well-known 发现文档的 URL，其中包含 OP API 端点列表。插件可以直接使用发现文档中的端点。你也可以单独配置这些端点，这将优先于发现文档中提供的端点。
scope
string
default: openid
对应于应返回的有关已认证用户信息的 OIDC 范围，也称为 claims。这用于通过适当的权限对用户进行授权。默认值为 openid，这是 OIDC 返回唯一标识已认证用户的 sub claim 所需的范围。
其他范围可以追加并用空格分隔，例如 openid email profile。
required_scopes
array[string]
访问令牌中必须存在的范围。当 bearer_only 为 true 时，与内省端点结合使用。如果缺少任何必需的范围，插件将以 403 Forbidden 错误拒绝请求。
realm
string
default: apisix
由于身份验证失败而返回的 401 Unauthorized 响应中 WWW-Authenticate 响应头的 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 颁发者数组。如果未配置，将使用发现端点返回的颁发者。如果两者都不可用，则不会验证颁发者。
- audience
  object
  受众 Claim 验证配置。
  claim
  string
  default: aud
  包含受众的 Claim 名称。
  required
  boolean
  default: false
  如果为 true，则受众 Claim 是必需的，且 Claim 名称将是在 claim 中定义的名称。例如，假设 claim_validator 配置如下： json { "audience": { "claim": "custom_claim", "required": true } } 如果请求中不存在 Claim custom_claim，你将收到 required audience claim not present 错误。
  match_with_client_id
  boolean
  default: false
  如果为 true，则要求受众与客户端 ID 匹配。如果受众是字符串，则必须与客户端 ID 完全匹配。如果受众是字符串数组，则必须至少有一个值与客户端 ID 匹配。如果没有找到匹配项，你将收到 mismatched audience 错误。
  此要求在 OpenID Connect 规范中说明，以确保令牌是针对特定客户端的。
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
default: false
如果为 true，则严格要求请求中包含 Bearer 访问令牌以进行身份验证。
logout_path
string
default: /logout
激活注销的路径。
post_logout_redirect_uri
string
logout_path 收到注销请求后将用户重定向到的 URL。
redirect_uri
string
default: `${ngx.var.request_uri}/.apisix/redirect`
与 OpenID 提供商认证后重定向到的 URI。
请注意，重定向 URI 不应与请求 URI 相同，而应是请求 URI 的子路径。例如，如果路由的 uri 为 /api/v1/*，则 redirect_uri 可以配置为 /api/v1/redirect。
如果未配置 redirect_uri，APISIX 将把 /.apisix/redirect 附加到请求 URI 以确定 redirect_uri 的值。
timeout
integer
default: 3
vaild vaule:
大于 0
请求超时时间（秒）。
ssl_verify
boolean
default: false
如果为 true，则验证 OpenID 提供商的 SSL 证书。
introspection_endpoint
string
OpenID 提供商用于内省访问令牌的令牌内省端点的 URL。如果未设置，则使用 well-known 发现文档中提供的内省端点作为后备。
introspection_endpoint_auth_method
string
default: client_secret_basic
令牌内省端点的身份验证方法。该值应为 well-known 发现文档中 introspection_endpoint_auth_methods_supported 授权服务器元数据指定的身份验证方法之一，例如 client_secret_basic、client_secret_post、private_key_jwt 和 client_secret_jwt。
token_endpoint_auth_method
string
default: client_secret_basic
令牌端点的身份验证方法。该值应为 well-known 发现文档中 token_endpoint_auth_methods_supported 授权服务器元数据指定的身份验证方法之一，例如 client_secret_basic、client_secret_post、private_key_jwt 和 client_secret_jwt。
如果配置的方法不受支持，则回退到 token_endpoint_auth_methods_supported 数组中的第一个方法。
client_rsa_private_key
string
用于签署 JWT 以对 OP 进行身份验证的客户端 RSA 私钥。当 token_endpoint_auth_method 为 private_key_jwt 时必填。
client_rsa_private_key_id
string
用于计算签名 JWT 的客户端 RSA 私钥 ID。当 token_endpoint_auth_method 为 private_key_jwt 时可选。
client_jwt_assertion_expires_in
integer
default: 60
用于对 OP 进行身份验证的签名 JWT 的生命周期（秒）。当 token_endpoint_auth_method 为 private_key_jwt 或 client_secret_jwt 时使用。
public_key
string
如果使用非对称算法，则用于验证 JWT 签名的公钥。提供此值以执行令牌验证将跳过客户端凭据流程中的令牌内省。
你可以使用 -----BEGIN PUBLIC KEY----- …… -----END PUBLIC KEY----- 格式传递公钥。
token_signing_alg_values_expected
string
用于签署 JWT 的算法，例如 RS256。
set_access_token_header
boolean
default: true
如果为 true，则在请求头中设置访问令牌。默认情况下，使用 X-Access-Token 头部。
access_token_in_authorization_header
boolean
default: false
如果为 true 且 set_access_token_header 也为 true，则在 Authorization 头部中设置访问令牌。
accept_none_alg
boolean
default: false
如果 OpenID 提供商不对其 ID 令牌进行签名（例如当签名算法设置为 none 时），则设置为 true。
use_jwks
boolean
default: false
如果为 true 且未设置 public_key，则使用 JWKS 验证 JWT 签名并跳过客户端凭据流程中的令牌内省。JWKS 端点从发现文档中解析。
jwk_expires_in
integer
default: 86400
JWK 缓存的过期时间（秒）。
jwt_verification_cache_ignore
boolean
default: false
如果为 true，则强制重新验证 Bearer 令牌并忽略任何现有的缓存验证结果。
cache_segment
string
缓存段的可选名称，用于分隔和区分令牌内省或 JWT 验证使用的缓存。
use_pkce
boolean
default: false
如果为 true，则对授权码流程使用用于代码交换的证明密钥 (PKCE)，如 RFC 7636 中所定义。
set_id_token_header
boolean
default: true
如果为 true 且 ID 令牌可用，则在 X-ID-Token 请求头中设置该值。
set_userinfo_header
boolean
default: true
如果为 true 且用户信息数据可用，则在 X-Userinfo 请求头中设置该值。
set_refresh_token_header
boolean
default: false
如果为 true 且刷新令牌可用，则在 X-Refresh-Token 请求头中设置该值。
session
object
当 bearer_only 为 false 且插件使用授权码流程时使用的会话配置。
- secret
  string
  vaild vaule:
  16 or more characters
  当 bearer_only 为 false 时，用于会话加密和 HMAC 操作的密钥。
  从 APISIX 3.14.0 和 API7 企业版 3.9.2 开始，当 bearer_only 为 false 时，会话密钥是必需的。
- cookie
  object
  Cookie 配置。
  lifetime
  integer
  default: 3600
  Cookie 生命周期（秒）。
unauth_action
string
default: auth
vaild vaule:
auth, deny, or 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
default: true
如果为 true，则在访问令牌过期或刷新令牌可用时尝试静默更新访问令牌。如果令牌更新失败，则重定向用户以重新进行身份验证。
access_token_expires_in
integer
default: 3600
如果令牌端点响应中不存在 expires_in 属性，则为访问令牌的生命周期（秒）。
refresh_session_interval
integer
无需重新身份验证即可刷新用户 ID 令牌的时间间隔。未设置时，插件将不会尝试静默更新。
iat_slack
integer
default: 120
ID 令牌中 iat Claim 的时钟偏差容差（秒）。
introspection_expiry_claim
string
default: exp
过期时间 Claim 的名称，用于控制缓存和内省的访问令牌的 TTL。
introspection_interval
integer
缓存和内省的访问令牌的 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
default: true
如果为 true，则忽略 ID 令牌签名以接受不受支持的签名算法。
access_token_expires_leeway
integer
访问令牌更新的过期回旋余地（秒）。当设置为大于 0 的值时，令牌更新将在令牌过期前的设定时间进行。这避免了在到达资源服务器时访问令牌刚好过期的情况。
force_reauthorize
boolean
default: false
如果为 true，即使已缓存令牌，也执行授权流程。
use_nonce
boolean
default: false
如果为 true，则在授权请求中启用 nonce 参数。
revoke_tokens_on_logout
boolean
default: false
如果为 true，则在撤销端点通知授权服务器不再需要先前获取的刷新或访问令牌。
session_contents
object
应存储在会话中的内容，用于最小化会话数据的大小。未设置时，所有内容都包含在会话中。
- id_token
  boolean
  如果为 true，则在会话中存储 ID 令牌。
- access_token
  boolean
  如果为 true，则在会话中存储访问令牌和刷新令牌。
- enc_id_token
  boolean
  如果为 true，则在会话中存储加密的 ID 令牌。
- user
  boolean
  如果为 true，则在会话中存储用户信息。

参数​

参数