# Authz Keycloak 配置选项

Authz Keycloak 插件将 APISIX 和 API7 网关请求的 UMA 权限决策委托给 Keycloak 授权服务。<!-- --> <!-- -->配置涵盖插件参数。

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

请参阅 [插件通用配置](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

  必填

  ***

  Client ID。

* client\_secret

  string

  ***

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

* discovery

  string

  ***

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

* token\_endpoint

  string

  ***

  支持 `urn:ietf:params:oauth:grant-type:uma-ticket` 授权类型并用于权限评估的 Token 端点。如果提供此项，它将覆盖发现文档中的值。`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 Token 请求，最终仍由 Keycloak 决定是否授权。

* permissions

  array\[string]

  默认值：`[]`

  ***

  表示客户端要访问的资源和 Scope 的权限。支持 `RESOURCE_ID#SCOPE_ID`、`RESOURCE_ID` 和 `#SCOPE_ID` 三种格式。同一资源的多个 Scope 用逗号分隔，例如 `RESOURCE_ID#SCOPE_1,SCOPE_2`。当 `lazy_load_paths` 为 `false` 时使用。参见[获取权限](https://www.keycloak.org/docs/latest/authorization_services/index.html#_service_obtaining_permissions)。

  Keycloak 必须授予配置的每个权限及每个权限中的所有 Scope。Scope 名称前后的空格会被忽略。APISIX 3.20.0、API7 Enterprise 3.9.23 和 3.10.9 实施此要求。更早的版本只要请求的权限中有任意一个被授予就会转发请求。

* lazy\_load\_paths

  boolean

  默认值：`false`

  ***

  如果为 `true`，则通过资源注册端点将请求 URI 动态解析为 Keycloak 资源。参见[延迟加载路径](https://www.keycloak.org/docs/latest/authorization_services/index.html#_enforcer_configuration)。

  动态加载要求插件获取服务账户访问 Token。为 Keycloak 客户端启用 **Service account roles**，并确保 Token 包含 `uma_protection` 角色，之后才能使用 [Protection API](https://www.keycloak.org/docs/latest/authorization_services/index.html#authorization-services)。

* http\_method\_as\_scope

  boolean

  默认值：`false`

  ***

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

  当 `lazy_load_paths` 为 `false` 时，插件会将 HTTP 方法对应的 Scope 添加到 `permissions` 中的每个静态权限，即使这些权限已指定 Scope。

  Keycloak 必须授予 HTTP 方法对应的 Scope，以及权限中配置的所有 Scope。此行为自 APISIX 3.20.0、API7 Enterprise 3.9.23 和 3.10.9 起引入。

* timeout

  integer

  默认值：`3000`

  有效值：

  大于或等于 1000

  ***

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

* access\_token\_expires\_in

  integer

  默认值：`300`

  有效值：

  大于或等于 1

  ***

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

* access\_token\_expires\_leeway

  integer

  默认值：`0`

  有效值：

  大于或等于 0

  ***

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

* refresh\_token\_expires\_in

  integer

  默认值：`3600`

  有效值：

  大于 0

  ***

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

* refresh\_token\_expires\_leeway

  integer

  默认值：`0`

  有效值：

  大于或等于 0

  ***

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

* ssl\_verify

  boolean

  默认值：`true`

  ***

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

* cache\_ttl\_seconds

  integer

  默认值：`86400`

  有效值：

  大于 0

  ***

  插件缓存发现文档和访问 Token 的 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 节](https://www.rfc-editor.org/rfc/rfc9700.html#section-2.4)。

* max\_req\_body\_size

  integer

  默认值：`67108864`

  有效值：

  大于或等于 1

  ***

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