Copilot commented on code in PR #13246: URL: https://github.com/apache/apisix/pull/13246#discussion_r3099162114
########## docs/zh/latest/plugins/authz-keycloak.md: ########## @@ -28,189 +28,757 @@ description: 本文介绍了关于 Apache APISIX `authz-keycloak` 插件的基 # --> +<head> + <link rel="canonical" href="https://docs.api7.ai/hub/authz-keycloak"; /> +</head> + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + ## 描述 -`authz-keycloak` 插件可用于通过 [Keycloak Identity Server](https://www.keycloak.org/) 添加身份验证。 +`authz-keycloak` 插件支持与 [Keycloak](https://www.keycloak.org/) 集成以对用户进行身份验证和授权。更多配置选项信息请参阅 Keycloak 的 [Authorization Services Guide](https://www.keycloak.org/docs/latest/authorization_services/)。 + +虽然该插件是为 Keycloak 开发的，但理论上也可以与其他符合 OAuth/OIDC 和 UMA 协议的身份提供者一起使用。 + +## 参数 + +| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 | +|------|------|--------|--------|--------|------| +| client_id | string | 是 | | | 客户端 ID。 | +| client_secret | string | 否 | | | 客户端密钥。该值在存储到 etcd 之前会使用 AES 加密。 | +| discovery | string | 否 | | | 发现文档的 URL。 | +| token_endpoint | string | 否 | | | 支持 `urn:ietf:params:oauth:grant-type:uma-ticket` 授权类型的令牌端点，用于获取访问令牌。若提供，则覆盖发现文档中的值。 | +| resource_registration_endpoint | string | 否 | | | 符合 UMA 规范的资源注册端点。当 `lazy_load_paths` 为 `true` 时必填。插件将首先从此配置项查找资源注册端点；若未找到，则从发现文档中查找。 | +| grant_type | string | 否 | `urn:ietf:params:oauth:grant-type:uma-ticket` | `urn:ietf:params:oauth:grant-type:uma-ticket` | 必须设置为 `urn:ietf:params:oauth:grant-type:uma-ticket`。 | +| policy_enforcement_mode | string | 否 | `ENFORCING` | `ENFORCING` 或 `PERMISSIVE` | [策略执行](https://www.keycloak.org/docs/latest/authorization_services/index.html#policy-enforcement)模式。`ENFORCING` 模式下，当没有与给定资源关联的策略时，请求将被拒绝。`PERMISSIVE` 模式下，当没有与给定资源关联的策略时，请求将被允许。 | +| permissions | array[string] | 否 | | | 表示客户端请求访问的一组资源和范围的权限数组。格式可以为 `RESOURCE_ID#SCOPE_ID`、`RESOURCE_ID` 或 `#SCOPE_ID`。当 `lazy_load_paths` 为 `false` 时使用。 | +| lazy_load_paths | boolean | 否 | `false` | | 若为 `true`，则需要发现文档或资源注册端点来动态将请求 URI 解析为资源。这需要插件从令牌端点为自己获取单独的访问令牌。请确保在 Keycloak 中勾选 `Service Accounts Enabled` 选项，并确保颁发的访问令牌包含带有 `uma_protection` 角色的 `resource_access` 声明。 | +| http_method_as_scope | boolean | 否 | `false` | | 若为 `true`，则使用请求的 HTTP 方法作为范围来检查是否应授予访问权限。当 `lazy_load_paths` 为 `false` 时，插件会将映射的范围添加到 `permissions` 属性中配置的任何静态权限，即使它们已经包含一个或多个范围。 | +| timeout | integer | 否 | 3000 | >= 1 | 与身份提供者的 HTTP 连接超时时间（毫秒）。 | Review Comment: `timeout` 的有效值在文档中写为 `>= 1`，但插件 schema 对该字段的最小值限制为 1000（毫秒）。请将表格中的有效值更新为与 schema 一致的范围，以免误导用户。 ########## docs/zh/latest/plugins/authz-keycloak.md: ########## @@ -28,189 +28,757 @@ description: 本文介绍了关于 Apache APISIX `authz-keycloak` 插件的基 # --> +<head> + <link rel="canonical" href="https://docs.api7.ai/hub/authz-keycloak"; /> +</head> + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + ## 描述 -`authz-keycloak` 插件可用于通过 [Keycloak Identity Server](https://www.keycloak.org/) 添加身份验证。 +`authz-keycloak` 插件支持与 [Keycloak](https://www.keycloak.org/) 集成以对用户进行身份验证和授权。更多配置选项信息请参阅 Keycloak 的 [Authorization Services Guide](https://www.keycloak.org/docs/latest/authorization_services/)。 + +虽然该插件是为 Keycloak 开发的，但理论上也可以与其他符合 OAuth/OIDC 和 UMA 协议的身份提供者一起使用。 + +## 参数 + +| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 | +|------|------|--------|--------|--------|------| +| client_id | string | 是 | | | 客户端 ID。 | +| client_secret | string | 否 | | | 客户端密钥。该值在存储到 etcd 之前会使用 AES 加密。 | +| discovery | string | 否 | | | 发现文档的 URL。 | +| token_endpoint | string | 否 | | | 支持 `urn:ietf:params:oauth:grant-type:uma-ticket` 授权类型的令牌端点，用于获取访问令牌。若提供，则覆盖发现文档中的值。 | +| resource_registration_endpoint | string | 否 | | | 符合 UMA 规范的资源注册端点。当 `lazy_load_paths` 为 `true` 时必填。插件将首先从此配置项查找资源注册端点；若未找到，则从发现文档中查找。 | Review Comment: `resource_registration_endpoint` 在表格中被描述为当 `lazy_load_paths` 为 `true` 时必填，但插件 schema 实际只要求此时提供 `discovery` 或 `resource_registration_endpoint` 其一（并且代码可以从 discovery 文档读取该端点）。建议调整描述为：当 `lazy_load_paths` 为 `true` 且无法从 `discovery` 获取端点时才需要显式配置该字段。 ########## docs/en/latest/plugins/authz-keycloak.md: ########## @@ -28,214 +28,757 @@ description: This document contains information about the Apache APISIX authz-ke # --> -## Description - -The `authz-keycloak` Plugin can be used to add authentication with [Keycloak Identity Server](https://www.keycloak.org/). +<head> + <link rel="canonical" href="https://docs.api7.ai/hub/authz-keycloak"; /> +</head> -:::tip +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; -Although this Plugin was developed to work with Keycloak, it should work with any OAuth/OIDC and UMA compliant identity providers as well. +## Description -::: +The `authz-keycloak` Plugin supports the integration with [Keycloak](https://www.keycloak.org/) to authenticate and authorize users. See Keycloak's [Authorization Services Guide](https://www.keycloak.org/docs/latest/authorization_services/) for more information about the configuration options available in this Plugin. -Refer to [Authorization Services Guide](https://www.keycloak.org/docs/latest/authorization_services/) for more information on Keycloak. +While the Plugin was developed for Keycloak, it could theoretically be used with other OAuth/OIDC and UMA-compliant identity providers. ## Attributes -| Name | Type | Required | Default | Valid values | Description | -|----------------------------------------------|---------------|----------|-----------------------------------------------|--------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| discovery | string | False | | https://host.domain/realms/foo/.well-known/uma2-configuration | URL to [discovery document](https://www.keycloak.org/docs/latest/authorization_services/index.html) of Keycloak Authorization Services. | -| token_endpoint | string | False | | https://host.domain/realms/foo/protocol/openid-connect/token | An OAuth2-compliant token endpoint that supports the `urn:ietf:params:oauth:grant-type:uma-ticket` grant type. If provided, overrides the value from discovery. | -| resource_registration_endpoint | string | False | | https://host.domain/realms/foo/authz/protection/resource_set | A UMA-compliant resource registration endpoint. If provided, overrides the value from discovery. | -| client_id | string | True | | | The identifier of the resource server to which the client is seeking access. | -| client_secret | string | False | | | The client secret, if required. You can use APISIX secret to store and reference this value. APISIX currently supports storing secrets in two ways. [Environment Variables and HashiCorp Vault](../terminology/secret.md) | -| grant_type | string | False | "urn:ietf:params:oauth:grant-type:uma-ticket" | ["urn:ietf:params:oauth:grant-type:uma-ticket"] | | -| policy_enforcement_mode | string | False | "ENFORCING" | ["ENFORCING", "PERMISSIVE"] | | -| permissions | array[string] | False | | | An array of strings, each representing a set of one or more resources and scopes the client is seeking access. | -| lazy_load_paths | boolean | False | false | | When set to true, dynamically resolves the request URI to resource(s) using the resource registration endpoint instead of the static permission. | -| http_method_as_scope | boolean | False | false | | When set to true, maps the HTTP request type to scope of the same name and adds to all requested permissions. | -| timeout | integer | False | 3000 | [1000, ...] | Timeout in ms for the HTTP connection with the Identity Server. | -| access_token_expires_in | integer | False | 300 | [1, ...] | Expiration time(s) of the access token. | -| access_token_expires_leeway | integer | False | 0 | [0, ...] | Expiration leeway(s) for access_token renewal. When set, the token will be renewed access_token_expires_leeway seconds before expiration. This avoids errors in cases where the access_token just expires when reaching the OAuth Resource Server. | -| refresh_token_expires_in | integer | False | 3600 | [1, ...] | The expiration time(s) of the refresh token. | -| refresh_token_expires_leeway | integer | False | 0 | [0, ...] | Expiration leeway(s) for refresh_token renewal. When set, the token will be renewed refresh_token_expires_leeway seconds before expiration. This avoids errors in cases where the refresh_token just expires when reaching the OAuth Resource Server. | -| ssl_verify | boolean | False | true | | When set to true, verifies if TLS certificate matches hostname. | -| cache_ttl_seconds | integer | False | 86400 (equivalent to 24h) | positive integer >= 1 | Maximum time in seconds up to which the Plugin caches discovery documents and tokens used by the Plugin to authenticate to Keycloak. | -| keepalive | boolean | False | true | | When set to true, enables HTTP keep-alive to keep connections open after use. Set to `true` if you are expecting a lot of requests to Keycloak. | -| keepalive_timeout | integer | False | 60000 | positive integer >= 1000 | Idle time after which the established HTTP connections will be closed. | -| keepalive_pool | integer | False | 5 | positive integer >= 1 | Maximum number of connections in the connection pool. | -| access_denied_redirect_uri | string | False | | [1, 2048] | URI to redirect the user to instead of returning an error message like `"error_description":"not_authorized"`. | -| password_grant_token_generation_incoming_uri | string | False | | /api/token | Set this to generate token using the password grant type. The Plugin will compare incoming request URI to this value. | +| Name | Type | Required | Default | Valid values | Description | +|------|------|----------|---------|--------------|-------------| +| client_id | string | True | | | Client ID. | +| client_secret | string | False | | | Client secret. The value is encrypted with AES before being stored in etcd. | +| discovery | string | False | | | URL to the discovery document. | +| token_endpoint | string | False | | | Token endpoint that supports the `urn:ietf:params:oauth:grant-type:uma-ticket` grant type to obtain access token. If provided, overrides the value from the discovery document. | +| resource_registration_endpoint | string | False | | | A UMA-compliant resource registration endpoint. Required when `lazy_load_paths` is `true`. The Plugin will first look for the resource registration endpoint from this configuration option; if not found, look for the resource registration endpoint from the discovery document. | Review Comment: `resource_registration_endpoint` is documented as required when `lazy_load_paths` is `true`, but the plugin schema only requires either `discovery` or `resource_registration_endpoint` in that case (and the code can read the endpoint from the discovery document). Please adjust the table description to reflect the actual requirement (e.g., required when `lazy_load_paths` is `true` *and* the endpoint can’t be obtained from `discovery`). ########## docs/zh/latest/plugins/authz-keycloak.md: ########## @@ -28,189 +28,757 @@ description: 本文介绍了关于 Apache APISIX `authz-keycloak` 插件的基 # --> +<head> + <link rel="canonical" href="https://docs.api7.ai/hub/authz-keycloak"; /> +</head> + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + ## 描述 -`authz-keycloak` 插件可用于通过 [Keycloak Identity Server](https://www.keycloak.org/) 添加身份验证。 +`authz-keycloak` 插件支持与 [Keycloak](https://www.keycloak.org/) 集成以对用户进行身份验证和授权。更多配置选项信息请参阅 Keycloak 的 [Authorization Services Guide](https://www.keycloak.org/docs/latest/authorization_services/)。 + +虽然该插件是为 Keycloak 开发的，但理论上也可以与其他符合 OAuth/OIDC 和 UMA 协议的身份提供者一起使用。 + +## 参数 + +| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 | +|------|------|--------|--------|--------|------| +| client_id | string | 是 | | | 客户端 ID。 | +| client_secret | string | 否 | | | 客户端密钥。该值在存储到 etcd 之前会使用 AES 加密。 | +| discovery | string | 否 | | | 发现文档的 URL。 | +| token_endpoint | string | 否 | | | 支持 `urn:ietf:params:oauth:grant-type:uma-ticket` 授权类型的令牌端点，用于获取访问令牌。若提供，则覆盖发现文档中的值。 | +| resource_registration_endpoint | string | 否 | | | 符合 UMA 规范的资源注册端点。当 `lazy_load_paths` 为 `true` 时必填。插件将首先从此配置项查找资源注册端点；若未找到，则从发现文档中查找。 | +| grant_type | string | 否 | `urn:ietf:params:oauth:grant-type:uma-ticket` | `urn:ietf:params:oauth:grant-type:uma-ticket` | 必须设置为 `urn:ietf:params:oauth:grant-type:uma-ticket`。 | +| policy_enforcement_mode | string | 否 | `ENFORCING` | `ENFORCING` 或 `PERMISSIVE` | [策略执行](https://www.keycloak.org/docs/latest/authorization_services/index.html#policy-enforcement)模式。`ENFORCING` 模式下，当没有与给定资源关联的策略时，请求将被拒绝。`PERMISSIVE` 模式下，当没有与给定资源关联的策略时，请求将被允许。 | +| permissions | array[string] | 否 | | | 表示客户端请求访问的一组资源和范围的权限数组。格式可以为 `RESOURCE_ID#SCOPE_ID`、`RESOURCE_ID` 或 `#SCOPE_ID`。当 `lazy_load_paths` 为 `false` 时使用。 | +| lazy_load_paths | boolean | 否 | `false` | | 若为 `true`，则需要发现文档或资源注册端点来动态将请求 URI 解析为资源。这需要插件从令牌端点为自己获取单独的访问令牌。请确保在 Keycloak 中勾选 `Service Accounts Enabled` 选项，并确保颁发的访问令牌包含带有 `uma_protection` 角色的 `resource_access` 声明。 | +| http_method_as_scope | boolean | 否 | `false` | | 若为 `true`，则使用请求的 HTTP 方法作为范围来检查是否应授予访问权限。当 `lazy_load_paths` 为 `false` 时，插件会将映射的范围添加到 `permissions` 属性中配置的任何静态权限，即使它们已经包含一个或多个范围。 | +| timeout | integer | 否 | 3000 | >= 1 | 与身份提供者的 HTTP 连接超时时间（毫秒）。 | +| access_token_expires_in | integer | 否 | 300 | >= 1 | 访问令牌的有效期（秒），当令牌端点响应中不存在 `expires_in` 属性时使用。 | +| access_token_expires_leeway | integer | 否 | 0 | >= 0 | 访问令牌续期的提前量（秒）。当设置为大于 0 的值时，令牌将在过期前提前该时间进行续期。 | +| refresh_token_expires_in | integer | 否 | 3600 | > 0 | 刷新令牌的过期时间（秒）。 | +| refresh_token_expires_leeway | integer | 否 | 0 | >= 0 | 刷新令牌续期的提前量（秒）。当设置为大于 0 的值时，令牌将在过期前提前该时间进行续期。 | +| ssl_verify | boolean | 否 | `true` | | 若为 `true`，则验证 OpenID 提供者的 SSL 证书。 | +| cache_ttl_seconds | integer | 否 | 86400 | > 0 | 插件缓存发现文档和访问令牌的 TTL（秒）。 | +| keepalive | boolean | 否 | `true` | | 若为 `true`，则启用 HTTP keep-alive 以在使用后保持连接打开。如果预期对 Keycloak 有大量请求，请设置为 `true`。 | +| keepalive_timeout | integer | 否 | 60000 | >= 1000 | 已建立的 HTTP 连接关闭前的空闲时间（毫秒）。 | +| keepalive_pool | integer | 否 | 5 | >= 1 | 连接池中的最大连接数。 | +| access_denied_redirect_uri | string | 否 | | | 访问被拒绝时将用户重定向到的 URI，而不是返回类似 `"error_description":"not_authorized"` 的错误消息。 | +| password_grant_token_generation_incoming_uri | string | 否 | | | 使用密码授权生成令牌的传入请求 URI，例如 `/api/token`。若传入请求的 URI 与配置值匹配、请求方法为 POST 且 `Content-Type` 为 `application/x-www-form-urlencoded`，则在 `token_endpoint` 生成令牌。 | + +注意：schema 中还定义了 `encrypt_fields = {"client_secret"}`，这意味着该字段将会被加密存储在 etcd 中。具体参考[加密存储字段](../plugin-develop.md#加密存储字段)。 + +## 示例 + +以下示例展示了如何针对不同场景配置 `authz-keycloak`。 + +请先完成 [Keycloak 的初始配置](#配置-keycloak)，然后再进行以下操作。 + +:::note -:::tip +您可以通过以下命令从 `config.yaml` 中获取 `admin_key` 并保存到环境变量： -虽然该插件是为了与 Keycloak 一起使用而开发的，但是它也可以与任何符合 OAuth/OIDC 或 UMA 协议的身份认证软件一起使用。 +```shell +admin_key=$(yq '.deployment.admin.admin_key[0].key' /usr/local/apisix/conf/config.yaml | sed 's/"//g') Review Comment: 文档提示从 `config.yaml` 获取 `admin_key`，但示例命令使用了绝对路径 `/usr/local/apisix/conf/config.yaml`，在不少常见部署/源码目录结构下可能不存在。建议改为仓库文档中常用的 `conf/config.yaml` 路径，或明确说明该路径需要根据安装/容器环境调整。 ########## docs/en/latest/plugins/authz-keycloak.md: ########## @@ -28,214 +28,757 @@ description: This document contains information about the Apache APISIX authz-ke # --> -## Description - -The `authz-keycloak` Plugin can be used to add authentication with [Keycloak Identity Server](https://www.keycloak.org/). +<head> + <link rel="canonical" href="https://docs.api7.ai/hub/authz-keycloak"; /> +</head> -:::tip +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; -Although this Plugin was developed to work with Keycloak, it should work with any OAuth/OIDC and UMA compliant identity providers as well. +## Description -::: +The `authz-keycloak` Plugin supports the integration with [Keycloak](https://www.keycloak.org/) to authenticate and authorize users. See Keycloak's [Authorization Services Guide](https://www.keycloak.org/docs/latest/authorization_services/) for more information about the configuration options available in this Plugin. -Refer to [Authorization Services Guide](https://www.keycloak.org/docs/latest/authorization_services/) for more information on Keycloak. +While the Plugin was developed for Keycloak, it could theoretically be used with other OAuth/OIDC and UMA-compliant identity providers. ## Attributes -| Name | Type | Required | Default | Valid values | Description | -|----------------------------------------------|---------------|----------|-----------------------------------------------|--------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| discovery | string | False | | https://host.domain/realms/foo/.well-known/uma2-configuration | URL to [discovery document](https://www.keycloak.org/docs/latest/authorization_services/index.html) of Keycloak Authorization Services. | -| token_endpoint | string | False | | https://host.domain/realms/foo/protocol/openid-connect/token | An OAuth2-compliant token endpoint that supports the `urn:ietf:params:oauth:grant-type:uma-ticket` grant type. If provided, overrides the value from discovery. | -| resource_registration_endpoint | string | False | | https://host.domain/realms/foo/authz/protection/resource_set | A UMA-compliant resource registration endpoint. If provided, overrides the value from discovery. | -| client_id | string | True | | | The identifier of the resource server to which the client is seeking access. | -| client_secret | string | False | | | The client secret, if required. You can use APISIX secret to store and reference this value. APISIX currently supports storing secrets in two ways. [Environment Variables and HashiCorp Vault](../terminology/secret.md) | -| grant_type | string | False | "urn:ietf:params:oauth:grant-type:uma-ticket" | ["urn:ietf:params:oauth:grant-type:uma-ticket"] | | -| policy_enforcement_mode | string | False | "ENFORCING" | ["ENFORCING", "PERMISSIVE"] | | -| permissions | array[string] | False | | | An array of strings, each representing a set of one or more resources and scopes the client is seeking access. | -| lazy_load_paths | boolean | False | false | | When set to true, dynamically resolves the request URI to resource(s) using the resource registration endpoint instead of the static permission. | -| http_method_as_scope | boolean | False | false | | When set to true, maps the HTTP request type to scope of the same name and adds to all requested permissions. | -| timeout | integer | False | 3000 | [1000, ...] | Timeout in ms for the HTTP connection with the Identity Server. | -| access_token_expires_in | integer | False | 300 | [1, ...] | Expiration time(s) of the access token. | -| access_token_expires_leeway | integer | False | 0 | [0, ...] | Expiration leeway(s) for access_token renewal. When set, the token will be renewed access_token_expires_leeway seconds before expiration. This avoids errors in cases where the access_token just expires when reaching the OAuth Resource Server. | -| refresh_token_expires_in | integer | False | 3600 | [1, ...] | The expiration time(s) of the refresh token. | -| refresh_token_expires_leeway | integer | False | 0 | [0, ...] | Expiration leeway(s) for refresh_token renewal. When set, the token will be renewed refresh_token_expires_leeway seconds before expiration. This avoids errors in cases where the refresh_token just expires when reaching the OAuth Resource Server. | -| ssl_verify | boolean | False | true | | When set to true, verifies if TLS certificate matches hostname. | -| cache_ttl_seconds | integer | False | 86400 (equivalent to 24h) | positive integer >= 1 | Maximum time in seconds up to which the Plugin caches discovery documents and tokens used by the Plugin to authenticate to Keycloak. | -| keepalive | boolean | False | true | | When set to true, enables HTTP keep-alive to keep connections open after use. Set to `true` if you are expecting a lot of requests to Keycloak. | -| keepalive_timeout | integer | False | 60000 | positive integer >= 1000 | Idle time after which the established HTTP connections will be closed. | -| keepalive_pool | integer | False | 5 | positive integer >= 1 | Maximum number of connections in the connection pool. | -| access_denied_redirect_uri | string | False | | [1, 2048] | URI to redirect the user to instead of returning an error message like `"error_description":"not_authorized"`. | -| password_grant_token_generation_incoming_uri | string | False | | /api/token | Set this to generate token using the password grant type. The Plugin will compare incoming request URI to this value. | +| Name | Type | Required | Default | Valid values | Description | +|------|------|----------|---------|--------------|-------------| +| client_id | string | True | | | Client ID. | +| client_secret | string | False | | | Client secret. The value is encrypted with AES before being stored in etcd. | +| discovery | string | False | | | URL to the discovery document. | +| token_endpoint | string | False | | | Token endpoint that supports the `urn:ietf:params:oauth:grant-type:uma-ticket` grant type to obtain access token. If provided, overrides the value from the discovery document. | +| resource_registration_endpoint | string | False | | | A UMA-compliant resource registration endpoint. Required when `lazy_load_paths` is `true`. The Plugin will first look for the resource registration endpoint from this configuration option; if not found, look for the resource registration endpoint from the discovery document. | +| grant_type | string | False | `urn:ietf:params:oauth:grant-type:uma-ticket` | `urn:ietf:params:oauth:grant-type:uma-ticket` | Must be set to `urn:ietf:params:oauth:grant-type:uma-ticket`. | +| policy_enforcement_mode | string | False | `ENFORCING` | `ENFORCING` or `PERMISSIVE` | The mode of [policy enforcement](https://www.keycloak.org/docs/latest/authorization_services/index.html#policy-enforcement). In `ENFORCING` mode, requests are denied when there is no policy associated with a given resource. In `PERMISSIVE` mode, requests are allowed when there is no policy associated with a given resource. | +| permissions | array[string] | False | | | An array of permissions representing a set of resources and scopes the client is seeking access. The format could be `RESOURCE_ID#SCOPE_ID`, `RESOURCE_ID`, or `#SCOPE_ID`. Used when `lazy_load_paths` is `false`. See [obtaining permissions](https://www.keycloak.org/docs/latest/authorization_services/index.html#_service_obtaining_permissions). | +| lazy_load_paths | boolean | False | `false` | | If `true`, require discovery or resource registration endpoint to dynamically resolve the request URI to resources. This requires the Plugin to obtain a separate access token for itself from the token endpoint. Make sure the `Service Accounts Enabled` option is checked in Keycloak to allow for client credentials grant, and that the issued access token contains the `resource_access` claim with the `uma_protection` role for the Plugin to query resources through the [Protection API](https://www.keycloak.org/docs/latest/authorization_services/index.html#authorization-services). | +| http_method_as_scope | boolean | False | `false` | | If `true`, use the HTTP method of the request as the scope to check whether access should be granted. When `lazy_load_paths` is `false`, the Plugin adds the mapped scope to any of the static permissions configured in the `permissions` attribute, even when they contain one or more scopes already. | +| timeout | integer | False | 3000 | >= 1 | Timeout in milliseconds for the HTTP connection with the identity provider. | +| access_token_expires_in | integer | False | 300 | >= 1 | Lifetime of the access token in seconds if no `expires_in` attribute is present in the token endpoint response. | +| access_token_expires_leeway | integer | False | 0 | >= 0 | Expiration leeway in seconds for access token renewal. When set to a value greater than 0, token renewal will take place the configured amount of time before token expiration. | +| refresh_token_expires_in | integer | False | 3600 | > 0 | Expiration time of the refresh token in seconds. | +| refresh_token_expires_leeway | integer | False | 0 | >= 0 | Expiration leeway in seconds for refresh token renewal. When set to a value greater than 0, token renewal will take place the configured amount of time before token expiration. | +| ssl_verify | boolean | False | `true` | | If `true`, verify the OpenID provider's SSL certificates. | +| cache_ttl_seconds | integer | False | 86400 | > 0 | TTL in seconds for the Plugin to cache discovery document and access tokens. | +| keepalive | boolean | False | `true` | | If `true`, enable HTTP keep-alive to keep connections open after use. Set to `true` if you are expecting a lot of requests to Keycloak. | +| keepalive_timeout | integer | False | 60000 | >= 1000 | Idle time after which the established HTTP connections will be closed. | +| keepalive_pool | integer | False | 5 | >= 1 | Maximum number of connections in the connection pool. | +| access_denied_redirect_uri | string | False | | | URI to redirect the user to instead of returning an error message like `"error_description":"not_authorized"` when access is denied. | +| password_grant_token_generation_incoming_uri | string | False | | | The URI incoming requests hit to generate a token using the password grant, for example, `/api/token`. If the incoming request's URI matches the configured value, the request method is POST, and `Content-Type` is `application/x-www-form-urlencoded`, a token is generated at the `token_endpoint`. | NOTE: `encrypt_fields = {"client_secret"}` is also defined in the schema, which means that the field will be stored encrypted in etcd. See [encrypted storage fields](../plugin-develop.md#encrypted-storage-fields). -### Discovery and endpoints +## Examples -It is recommended to use the `discovery` attribute as the `authz-keycloak` Plugin can discover the Keycloak API endpoints from it. +The examples below demonstrate how you can configure `authz-keycloak` for different scenarios. -If set, the `token_endpoint` and `resource_registration_endpoint` will override the values obtained from the discovery document. +To follow along, complete the [preliminary setups](#set-up-keycloak) for Keycloak. -### Client ID and secret +:::note -The Plugin needs the `client_id` attribute for identification and to specify the context in which to evaluate permissions when interacting with Keycloak. +You can fetch the `admin_key` from `config.yaml` and save to an environment variable with the following command: -If the `lazy_load_paths` attribute is set to true, then the Plugin additionally needs to obtain an access token for itself from Keycloak. In such cases, if the client access to Keycloak is confidential, you need to configure the `client_secret` attribute. +```shell +admin_key=$(yq '.deployment.admin.admin_key[0].key' /usr/local/apisix/conf/config.yaml | sed 's/"//g') +``` Review Comment: The docs say you can fetch `admin_key` from `config.yaml`, but the command uses an absolute path (`/usr/local/apisix/conf/config.yaml`) that may not exist in common setups (for example, when running from the source tree or using the docs’ typical `conf/config.yaml` path). Consider switching to the repo-conventional path or explicitly noting that the path depends on your installation/container layout. ########## docs/en/latest/plugins/authz-keycloak.md: ########## @@ -28,214 +28,757 @@ description: This document contains information about the Apache APISIX authz-ke # --> -## Description - -The `authz-keycloak` Plugin can be used to add authentication with [Keycloak Identity Server](https://www.keycloak.org/). +<head> + <link rel="canonical" href="https://docs.api7.ai/hub/authz-keycloak"; /> +</head> -:::tip +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; -Although this Plugin was developed to work with Keycloak, it should work with any OAuth/OIDC and UMA compliant identity providers as well. +## Description -::: +The `authz-keycloak` Plugin supports the integration with [Keycloak](https://www.keycloak.org/) to authenticate and authorize users. See Keycloak's [Authorization Services Guide](https://www.keycloak.org/docs/latest/authorization_services/) for more information about the configuration options available in this Plugin. -Refer to [Authorization Services Guide](https://www.keycloak.org/docs/latest/authorization_services/) for more information on Keycloak. +While the Plugin was developed for Keycloak, it could theoretically be used with other OAuth/OIDC and UMA-compliant identity providers. ## Attributes -| Name | Type | Required | Default | Valid values | Description | -|----------------------------------------------|---------------|----------|-----------------------------------------------|--------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| discovery | string | False | | https://host.domain/realms/foo/.well-known/uma2-configuration | URL to [discovery document](https://www.keycloak.org/docs/latest/authorization_services/index.html) of Keycloak Authorization Services. | -| token_endpoint | string | False | | https://host.domain/realms/foo/protocol/openid-connect/token | An OAuth2-compliant token endpoint that supports the `urn:ietf:params:oauth:grant-type:uma-ticket` grant type. If provided, overrides the value from discovery. | -| resource_registration_endpoint | string | False | | https://host.domain/realms/foo/authz/protection/resource_set | A UMA-compliant resource registration endpoint. If provided, overrides the value from discovery. | -| client_id | string | True | | | The identifier of the resource server to which the client is seeking access. | -| client_secret | string | False | | | The client secret, if required. You can use APISIX secret to store and reference this value. APISIX currently supports storing secrets in two ways. [Environment Variables and HashiCorp Vault](../terminology/secret.md) | -| grant_type | string | False | "urn:ietf:params:oauth:grant-type:uma-ticket" | ["urn:ietf:params:oauth:grant-type:uma-ticket"] | | -| policy_enforcement_mode | string | False | "ENFORCING" | ["ENFORCING", "PERMISSIVE"] | | -| permissions | array[string] | False | | | An array of strings, each representing a set of one or more resources and scopes the client is seeking access. | -| lazy_load_paths | boolean | False | false | | When set to true, dynamically resolves the request URI to resource(s) using the resource registration endpoint instead of the static permission. | -| http_method_as_scope | boolean | False | false | | When set to true, maps the HTTP request type to scope of the same name and adds to all requested permissions. | -| timeout | integer | False | 3000 | [1000, ...] | Timeout in ms for the HTTP connection with the Identity Server. | -| access_token_expires_in | integer | False | 300 | [1, ...] | Expiration time(s) of the access token. | -| access_token_expires_leeway | integer | False | 0 | [0, ...] | Expiration leeway(s) for access_token renewal. When set, the token will be renewed access_token_expires_leeway seconds before expiration. This avoids errors in cases where the access_token just expires when reaching the OAuth Resource Server. | -| refresh_token_expires_in | integer | False | 3600 | [1, ...] | The expiration time(s) of the refresh token. | -| refresh_token_expires_leeway | integer | False | 0 | [0, ...] | Expiration leeway(s) for refresh_token renewal. When set, the token will be renewed refresh_token_expires_leeway seconds before expiration. This avoids errors in cases where the refresh_token just expires when reaching the OAuth Resource Server. | -| ssl_verify | boolean | False | true | | When set to true, verifies if TLS certificate matches hostname. | -| cache_ttl_seconds | integer | False | 86400 (equivalent to 24h) | positive integer >= 1 | Maximum time in seconds up to which the Plugin caches discovery documents and tokens used by the Plugin to authenticate to Keycloak. | -| keepalive | boolean | False | true | | When set to true, enables HTTP keep-alive to keep connections open after use. Set to `true` if you are expecting a lot of requests to Keycloak. | -| keepalive_timeout | integer | False | 60000 | positive integer >= 1000 | Idle time after which the established HTTP connections will be closed. | -| keepalive_pool | integer | False | 5 | positive integer >= 1 | Maximum number of connections in the connection pool. | -| access_denied_redirect_uri | string | False | | [1, 2048] | URI to redirect the user to instead of returning an error message like `"error_description":"not_authorized"`. | -| password_grant_token_generation_incoming_uri | string | False | | /api/token | Set this to generate token using the password grant type. The Plugin will compare incoming request URI to this value. | +| Name | Type | Required | Default | Valid values | Description | +|------|------|----------|---------|--------------|-------------| +| client_id | string | True | | | Client ID. | +| client_secret | string | False | | | Client secret. The value is encrypted with AES before being stored in etcd. | +| discovery | string | False | | | URL to the discovery document. | +| token_endpoint | string | False | | | Token endpoint that supports the `urn:ietf:params:oauth:grant-type:uma-ticket` grant type to obtain access token. If provided, overrides the value from the discovery document. | +| resource_registration_endpoint | string | False | | | A UMA-compliant resource registration endpoint. Required when `lazy_load_paths` is `true`. The Plugin will first look for the resource registration endpoint from this configuration option; if not found, look for the resource registration endpoint from the discovery document. | +| grant_type | string | False | `urn:ietf:params:oauth:grant-type:uma-ticket` | `urn:ietf:params:oauth:grant-type:uma-ticket` | Must be set to `urn:ietf:params:oauth:grant-type:uma-ticket`. | +| policy_enforcement_mode | string | False | `ENFORCING` | `ENFORCING` or `PERMISSIVE` | The mode of [policy enforcement](https://www.keycloak.org/docs/latest/authorization_services/index.html#policy-enforcement). In `ENFORCING` mode, requests are denied when there is no policy associated with a given resource. In `PERMISSIVE` mode, requests are allowed when there is no policy associated with a given resource. | +| permissions | array[string] | False | | | An array of permissions representing a set of resources and scopes the client is seeking access. The format could be `RESOURCE_ID#SCOPE_ID`, `RESOURCE_ID`, or `#SCOPE_ID`. Used when `lazy_load_paths` is `false`. See [obtaining permissions](https://www.keycloak.org/docs/latest/authorization_services/index.html#_service_obtaining_permissions). | +| lazy_load_paths | boolean | False | `false` | | If `true`, require discovery or resource registration endpoint to dynamically resolve the request URI to resources. This requires the Plugin to obtain a separate access token for itself from the token endpoint. Make sure the `Service Accounts Enabled` option is checked in Keycloak to allow for client credentials grant, and that the issued access token contains the `resource_access` claim with the `uma_protection` role for the Plugin to query resources through the [Protection API](https://www.keycloak.org/docs/latest/authorization_services/index.html#authorization-services). | +| http_method_as_scope | boolean | False | `false` | | If `true`, use the HTTP method of the request as the scope to check whether access should be granted. When `lazy_load_paths` is `false`, the Plugin adds the mapped scope to any of the static permissions configured in the `permissions` attribute, even when they contain one or more scopes already. | +| timeout | integer | False | 3000 | >= 1 | Timeout in milliseconds for the HTTP connection with the identity provider. | Review Comment: The `timeout` attribute’s documented valid range (`>= 1`) doesn’t match the plugin schema, which enforces a minimum of 1000 ms. Please update the valid values column (and any related wording) to match the schema constraints. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
