OpenID Connect | Apache APISIX 与 API7 网关插件文档

参数

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

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

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 时，客户端密钥也是可选的。对于使用客户端密钥向提供商进行身份认证的流程（例如令牌内省或不使用 PKCE 的授权码流程），客户端密钥仍为必填项。
discovery
string
必填
OpenID 提供商的 well-known 发现文档的 URL，其中包含 OP API 端点列表。插件可以直接使用发现文档中的端点。你也可以单独配置这些端点，这将优先于发现文档中提供的端点。
scope
string
默认值：openid
对应于应返回的有关已认证用户信息的 OIDC 范围，也称为 claims。这用于通过适当的权限对用户进行授权。默认值为 openid，这是 OIDC 返回唯一标识已认证用户的 sub claim 所需的范围。
其他范围可以追加并用空格分隔，例如 openid email profile。
required_scopes
array[string]
访问令牌中必须存在的范围。当 bearer_only 为 true 时，与内省端点结合使用。如果缺少任何必需的范围，插件将以 403 Forbidden 错误拒绝请求。
realm
string
默认值：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
  默认值：aud
  包含受众的 Claim 名称。
  required
  boolean
  默认值：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
  默认值：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
默认值：false
如果为 true，则严格要求请求中包含 Bearer 访问令牌以进行身份认证。
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 相同，而应是请求 URI 的子路径。例如，如果路由的 uri 为 /api/v1/*，则 redirect_uri 可以配置为 /api/v1/redirect。
如果未配置 redirect_uri，APISIX 将把 /.apisix/redirect 附加到请求 URI 以确定 redirect_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 提供商用于内省访问令牌的令牌内省端点的 URL。如果未设置，则使用 well-known 发现文档中提供的内省端点作为后备。
introspection_endpoint_auth_method
string
默认值：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
默认值：client_secret_basic
令牌端点的身份认证方法。该值应为 well-known 发现文档中 token_endpoint_auth_methods_supported 授权服务器元数据指定的身份认证方法之一，例如 client_secret_basic、client_secret_post、private_key_jwt 和 client_secret_jwt。
如果插件不支持配置的方法，则忽略该配置，并使用 OpenID 提供商公布的第一个可用方法。如果插件支持配置的方法，但 token_endpoint_auth_methods_supported 已提供且不包含该方法，则令牌端点身份认证失败。
client_rsa_private_key
string
用于签署 JWT 以对 OP 进行身份认证的客户端 RSA 私钥。当 token_endpoint_auth_method 为 private_key_jwt 时必填。
该值在存储到 etcd 前会使用 AES 加密。
client_rsa_private_key_id
string
用于计算签名 JWT 的客户端 RSA 私钥 ID。当 token_endpoint_auth_method 为 private_key_jwt 时可选。
client_jwt_assertion_expires_in
integer
默认值：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
默认值：true
如果为 true，则在请求头中设置访问令牌。默认使用 X-Access-Token 请求头。
access_token_in_authorization_header
boolean
默认值：false
如果为 true 且 set_access_token_header 也为 true，则在 Authorization 请求头中设置访问令牌。
accept_none_alg
boolean
默认值：false
如果 OpenID 提供商不对其 ID 令牌进行签名（例如当签名算法设置为 none 时），则设置为 true。
use_jwks
boolean
默认值：false
如果为 true 且未设置 public_key，则使用 JWKS 验证 JWT 签名并跳过客户端凭据流程中的令牌内省。JWKS 端点从发现文档中解析。
jwk_expires_in
integer
默认值：86400
JWK 缓存的过期时间（秒）。
jwt_verification_cache_ignore
boolean
默认值：false
如果为 true，则强制重新验证 Bearer 令牌并忽略任何现有的缓存验证结果。
cache_segment
string
缓存段的可选名称，用于分隔和区分令牌内省或 JWT 验证使用的缓存。
use_pkce
boolean
默认值：false
如果为 true，则对授权码流程使用用于代码交换的证明密钥 (PKCE)，如 RFC 7636 中所定义。
set_id_token_header
boolean
默认值：true
如果为 true 且 ID 令牌可用，则在 X-ID-Token 请求头中设置该值。
set_userinfo_header
boolean
默认值：true
如果为 true 且用户信息数据可用，则在 X-Userinfo 请求头中设置该值。
set_raw_id_token_header
boolean
默认值：false
如果为 true，则把身份提供商签发的原始 ID Token JWT 通过 X-Raw-ID-Token 请求头添加到请求中，便于上游服务自行校验 Token 签名。自 API7 企业版 3.9.x 系列的 3.9.17 版本起可用，3.10.x 系列自 3.10.4 版本起可用。
原始 ID Token 属于 bearer 凭证。请仅对可信上游启用，并确保该请求头不会被写入访问日志或回显给客户端。
set_refresh_token_header
boolean
默认值：false
如果为 true 且刷新令牌可用，则在 X-Refresh-Token 请求头中设置该值。
session
object
当 bearer_only 为 false 且插件使用授权码流程时使用的会话配置。
- secret
  string
  有效值：
  至少 16 个字符
  当 bearer_only 为 false 时，用于会话加密和 HMAC 操作的密钥。
  从 APISIX 3.14.0 和 API7 企业版 3.9.2 开始，当 bearer_only 为 false 时，会话密钥是必需的。
- 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
  空闲超时时间（秒），超过该时间后空闲会话将被重新生成。对应 lua-resty-session 的 idling_timeout 选项。
  自 API7 企业版 3.9.14 和 APISIX 3.17.0 起可用。
- rolling_timeout
  integer
  滚动超时时间（秒），超过该时间后会话将被续期。对应 lua-resty-session 的 rolling_timeout 选项。
  自 API7 企业版 3.9.14 和 APISIX 3.17.0 起可用。
- absolute_timeout
  integer
  会话的绝对生命周期（秒），超过该时间后无论是否活跃，会话都会过期。对应 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
  默认值：3600
  Cookie 生命周期（秒）。已废弃。当未设置 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，则在访问令牌过期或刷新令牌可用时尝试静默更新访问令牌。如果令牌更新失败，则重定向用户以重新进行身份认证。
access_token_expires_in
integer
默认值：3600
如果令牌端点响应中不存在 expires_in 属性，则为访问令牌的生命周期（秒）。
refresh_session_interval
integer
无需重新身份认证即可刷新用户 ID 令牌的时间间隔。在 APISIX 中，未设置时插件不会尝试静默更新。
在 API7 Gateway 中，默认值为 900。
iat_slack
integer
默认值：120
ID 令牌中 iat Claim 的时钟偏差容差（秒）。
introspection_expiry_claim
string
默认值：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
默认值：true
如果为 true，则忽略 ID 令牌签名以接受不受支持的签名算法。
access_token_expires_leeway
integer
访问令牌更新的过期回旋余地（秒）。当设置为大于 0 的值时，令牌更新将在令牌过期前的设定时间进行。这避免了在到达资源服务器时访问令牌刚好过期的情况。
force_reauthorize
boolean
默认值：false
如果为 true，即使已缓存令牌，也执行授权流程。
use_nonce
boolean
默认值：false
如果为 true，则在授权请求中启用 nonce 参数。
revoke_tokens_on_logout
boolean
默认值：false
如果为 true，则在撤销端点通知授权服务器不再需要先前获取的刷新或访问令牌。
session_contents
object
应存储在会话中的内容，用于最小化会话数据的大小。未设置时，所有内容都包含在会话中。
- id_token
  boolean
  如果为 true，则在会话中存储 ID 令牌。
- access_token
  boolean
  如果为 true，则在会话中存储访问令牌和刷新令牌。
- enc_id_token
  boolean
  如果为 true，则在会话中存储加密的 ID 令牌。
- user
  boolean
  如果为 true，则在会话中存储用户信息。
par
object
推送式授权请求（PAR）配置，定义见 RFC 9126。启用 PAR 后，网关通过后通道把授权请求参数发送给身份提供商，并只用返回的 request_uri 重定向用户代理，因此这些参数不会经过浏览器。
自 API7 企业版 3.9.x 系列的 3.9.18 版本起可用，3.10.x 系列自 3.10.5 版本起可用。
- 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 端点上使用的客户端认证方法。未设置时沿用为令牌端点配置的方法。
dpop
object
发送方约束令牌（DPoP）配置，定义见 RFC 9449。网关会为每次令牌请求签发 proof JWT，把签发的令牌绑定到所配置的密钥上，令牌即使被窃取也无法由其它客户端重放。同时设置 par.enabled 时，密钥指纹会以 dpop_jkt 随推送请求一并发送。
自 API7 企业版 3.9.x 系列的 3.9.18 版本起可用，3.10.x 系列自 3.10.5 版本起可用。
- enabled
  boolean
  默认值：false
  如果为 true，则在令牌请求中携带 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 所用的算法，需与所配置密钥的类型匹配。
client_jwt_assertion_alg
string
有效值：
HS256、HS512、RS256、RS512、ES256 或 ES512
当端点认证方法为 client_secret_jwt 或 private_key_jwt 时，用于签名客户端断言 JWT 的算法。
自 API7 企业版 3.9.x 系列的 3.9.18 版本起可用，3.10.x 系列自 3.10.5 版本起可用。
client_jwt_assertion_audience
string
客户端断言 JWT 的 audience 声明。未设置时使用身份提供商的令牌端点。
自 API7 企业版 3.9.x 系列的 3.9.18 版本起可用，3.10.x 系列自 3.10.5 版本起可用。

参数​

参数