参数
请参阅 插件通用配置 了解所有插件可用的配置选项。
该插件支持使用 env:// 前缀引用环境变量中的敏感参数值，或使用 secret:// 前缀引用 Secret 管理器（如 HashiCorp Vault 的 KV 密钥引擎）中的值。更多信息，请参阅环境变量中的插件和密钥。
client_id
Client ID。
client_secret
插件向 Token 端点进行身份认证时使用的 Client Secret。启用字段加密且配置存储在 etcd 中时，网关会先加密此值再存储。
discovery
发现文档的 URL。
discovery和token_endpoint至少需要配置一个。token_endpoint
支持
urn:ietf:params:oauth:grant-type:uma-ticket授权类型并用于权限评估的 Token 端点。如果提供此项，它将覆盖发现文档中的值。discovery和token_endpoint至少需要配置一个。resource_registration_endpoint
符合 UMA 标准的资源注册端点。当
lazy_load_paths为true时，插件优先使用此值，否则从发现文档获取该端点。动态路径加载需要配置discovery，或同时配置token_endpoint和resource_registration_endpoint。grant_type
有效值：
urn:ietf:params:oauth:grant-type:uma-ticket
用于权限评估的 UMA Ticket 授权类型。这是默认值，也是唯一可接受的值。
policy_enforcement_mode
有效值：
ENFORCING或PERMISSIVE控制插件在向 Keycloak 请求决策之前如何处理空权限列表。
在
ENFORCING模式下，空权限列表会返回403 Forbidden；如果配置了access_denied_redirect_uri，则返回307 Temporary Redirect。在
PERMISSIVE模式下，插件继续发送不含 permission 参数的 UMA Token 请求，最终仍由 Keycloak 决定是否授权。permissions
表示客户端要访问的资源和 Scope 的权限。支持
RESOURCE_ID#SCOPE_ID、RESOURCE_ID和#SCOPE_ID三种格式。当lazy_load_paths为false时使用。参见获取权限。lazy_load_paths
如果为
true，则通过资源注册端点将请求 URI 动态解析为 Keycloak 资源。参见延迟加载路径。动态加载要求插件获取服务账户访问 Token。为 Keycloak 客户端启用 Service account roles，并确保 Token 包含
uma_protection角色，之后才能使用 Protection API。http_method_as_scope
如果为 true，则使用请求的 HTTP 方法作为 Scope 来检查是否应授予访问权限。
在
lazy_load_paths设置为 false 的情况下，插件会将映射的 Scope 添加到permissions属性中配置的任何静态权限中，即使它们已经包含一个或多个 Scope。timeout
有效值：
大于或等于 1000
与身份提供商的 HTTP 连接超时时间（以毫秒为单位）。
access_token_expires_in
有效值：
大于或等于 1
如果 Token 端点响应中没有
expires_in属性，则为访问 Token 的生命周期（以秒为单位）。access_token_expires_leeway
有效值：
大于或等于 0
访问 Token 续期的过期缓冲时间（以秒为单位）。当设置为大于 0 的值时，Token 续期将在 Token 过期前的设定时间内进行。这避免了访问 Token 在刚到达资源服务器时过期的错误。
refresh_token_expires_in
有效值：
大于 0
刷新 Token 的过期时间（以秒为单位）。
refresh_token_expires_leeway
有效值：
大于或等于 0
刷新 Token 续期的过期缓冲时间（以秒为单位）。当设置为大于 0 的值时，Token 续期将在 Token 过期前的设定时间内进行。这避免了访问 Token 在刚到达资源服务器时过期的错误。
ssl_verify
如果为 true，验证 OpenID 提供商的 SSL 证书。
cache_ttl_seconds
有效值：
大于 0
插件缓存发现文档和访问 Token 的 TTL（以秒为单位）。
keepalive
如果为
true，则保持与身份提供商的 HTTP 连接打开以供复用。keepalive_timeout
有效值：
大于或等于 1000
已建立的 HTTP 连接在关闭前可空闲的时间，单位为毫秒。
keepalive_pool
有效值：
大于或等于 1
连接池中的最大连接数。
access_denied_redirect_uri
在
ENFORCING模式下权限列表为空，或 Keycloak 返回403 Forbidden时，用于返回307 Temporary Redirect的 URI。password_grant_token_generation_incoming_uri
用于兼容旧系统的选项，会公开 OAuth Resource Owner Password Credentials Grant 端点。当包含
username和password的表单编码POST请求匹配此 URI 时，插件会向配置的token_endpoint提交密码授权请求并返回其响应。OAuth 2.0 安全最佳实践明确规定不得使用此授权方式。新部署请勿配置此字段。参见 RFC 9700 第 2.4 节。max_req_body_size
有效值：
大于或等于 1
插件生成密码授权 Token 时缓冲到内存中的请求体最大字节数。如果请求体超过限制或无法读取，插件会返回
503 Service Unavailable。自 API7 企业版 3.9.17 和 3.10.4，以及 APISIX 3.18.0 起可用。