跳到主要内容

参数​

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

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

  • client_id

    string

    必填

    Client ID。

  • client_secret

    string

    插件向令牌端点进行身份认证时使用的 Client Secret。启用字段加密且配置存储在 etcd 中时，网关会先加密此值再存储。

  • discovery

    string

    发现文档的 URL。discovery 和 token_endpoint 至少需要配置一个。

  • token_endpoint

    string

    支持 urn:ietf:params:oauth:grant-type:uma-ticket 授权类型并用于权限评估的令牌端点。如果提供此项，它将覆盖发现文档中的值。discovery 和 token_endpoint 至少需要配置一个。

  • resource_registration_endpoint

    string

    符合 UMA 标准的资源注册端点。当 lazy_load_paths 为 true 时，插件优先使用此值，否则从发现文档获取该端点。动态路径加载需要配置 discovery，或同时配置 token_endpoint 和 resource_registration_endpoint。

  • grant_type

    string

    默认值：urn:ietf:params:oauth:grant-type:uma-ticket

    有效值：

    urn:ietf:params:oauth:grant-type:uma-ticket

    用于权限评估的 UMA Ticket 授权类型。这是默认值，也是唯一可接受的值。

  • policy_enforcement_mode

    string

    默认值：ENFORCING

    有效值：

    ENFORCING 或 PERMISSIVE

    控制插件在向 Keycloak 请求决策之前如何处理空权限列表。

    在 ENFORCING 模式下，空权限列表会返回 403 Forbidden；如果配置了 access_denied_redirect_uri，则返回 307 Temporary Redirect。

    在 PERMISSIVE 模式下，插件继续发送不含 permission 参数的 UMA 令牌请求，最终仍由 Keycloak 决定是否授权。

  • permissions

    array[string]

    默认值：[]

    表示客户端要访问的资源和 Scope 的权限。支持 RESOURCE_ID#SCOPE_ID、RESOURCE_ID 和 #SCOPE_ID 三种格式。当 lazy_load_paths 为 false 时使用。参见获取权限。

  • lazy_load_paths

    boolean

    默认值：false

    如果为 true，则通过资源注册端点将请求 URI 动态解析为 Keycloak 资源。参见延迟加载路径。

    动态加载要求插件获取服务账户访问令牌。为 Keycloak 客户端启用 Service account roles，并确保令牌包含 uma_protection 角色，之后才能使用 Protection API。

  • http_method_as_scope

    boolean

    默认值：false

    如果为 true，则使用请求的 HTTP 方法作为 Scope 来检查是否应授予访问权限。

    在 lazy_load_paths 设置为 false 的情况下，插件会将映射的 Scope 添加到 permissions 属性中配置的任何静态权限中，即使它们已经包含一个或多个 Scope。

  • timeout

    integer

    默认值：3000

    有效值：

    大于或等于 1000

    与身份提供商的 HTTP 连接超时时间（以毫秒为单位）。

  • access_token_expires_in

    integer

    默认值：300

    有效值：

    大于或等于 1

    如果令牌端点响应中没有 expires_in 属性，则为访问令牌的生命周期（以秒为单位）。

  • access_token_expires_leeway

    integer

    有效值：

    大于或等于 0

    访问令牌续期的过期缓冲时间（以秒为单位）。当设置为大于 0 的值时，令牌续期将在令牌过期前的设定时间内进行。这避免了访问令牌在刚到达资源服务器时过期的错误。

  • refresh_token_expires_in

    integer

    默认值：3600

    有效值：

    大于 0

    刷新令牌的过期时间（以秒为单位）。

  • refresh_token_expires_leeway

    integer

    有效值：

    大于或等于 0

    刷新令牌续期的过期缓冲时间（以秒为单位）。当设置为大于 0 的值时，令牌续期将在令牌过期前的设定时间内进行。这避免了访问令牌在刚到达资源服务器时过期的错误。

  • ssl_verify

    boolean

    默认值：true

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

  • cache_ttl_seconds

    integer

    默认值：86400

    有效值：

    大于 0

    插件缓存发现文档和访问令牌的 TTL（以秒为单位）。

  • keepalive

    boolean

    默认值：true

    如果为 true，则保持与身份提供商的 HTTP 连接打开以供复用。

  • keepalive_timeout

    integer

    默认值：60000

    有效值：

    大于或等于 1000

    已建立的 HTTP 连接在关闭前可空闲的时间，单位为毫秒。

  • keepalive_pool

    integer

    默认值：5

    有效值：

    大于或等于 1

    连接池中的最大连接数。

  • access_denied_redirect_uri

    string

    在 ENFORCING 模式下权限列表为空，或 Keycloak 返回 403 Forbidden 时，用于返回 307 Temporary Redirect 的 URI。

  • password_grant_token_generation_incoming_uri

    string

    用于兼容旧系统的选项，会公开 OAuth Resource Owner Password Credentials Grant 端点。当包含 username 和 password 的表单编码 POST 请求匹配此 URI 时，插件会向配置的 token_endpoint 提交密码授权请求并返回其响应。OAuth 2.0 安全最佳实践明确规定不得使用此授权方式。新部署请勿配置此字段。参见 RFC 9700 第 2.4 节。

  • max_req_body_size

    integer

    默认值：67108864

    有效值：

    大于或等于 1

    插件生成密码授权令牌时缓冲到内存中的请求体最大字节数。如果请求体超过限制或无法读取，插件会返回 503 Service Unavailable。自 API7 网关 3.9.17 和 3.10.4，以及 APISIX 3.18.0 起可用。