Skip to main content
Version: 3.4

authz-keycloak

描述#

authz-keycloak 插件可用于通过 Keycloak Identity Server 添加身份验证。

tip

虽然该插件是为了与 Keycloak 一起使用而开发的,但是它也可以与任何符合 OAuth/OIDC 或 UMA 协议的身份认证软件一起使用。

如果你想了解 Keycloak 的更多信息,请参考 Authorization Services Guide

属性#

名称类型必选项默认值有效值描述
discoverystringhttps://host.domain/auth/realms/foo/.well-known/uma2-configurationKeycloak 授权服务的 discovery document 的 URL。
token_endpointstringhttps://host.domain/auth/realms/foo/protocol/openid-connect/token接受 OAuth2 兼容 token 的接口,需要支持 urn:ietf:params:oauth:grant-type:uma-ticket 授权类型。
resource_registration_endpointstringhttps://host.domain/auth/realms/foo/authz/protection/resource_set符合 UMA 的资源注册端点。如果提供,则覆盖发现中的值。
client_idstring客户端正在寻求访问的资源服务器的标识符。
client_secretstring客户端密码(如果需要)。
grant_typestring"urn:ietf:params:oauth:grant-type:uma-ticket"["urn:ietf:params:oauth:grant-type:uma-ticket"]
policy_enforcement_modestring"ENFORCING"["ENFORCING", "PERMISSIVE"]
permissionsarray[string]描述客户端应用所需访问的资源和权限范围的字符串。格式必须为:RESOURCE_ID#SCOPE_ID
lazy_load_pathsbooleanfalse[true, false]当设置为 true 时,使用资源注册端点而不是静态权限将请求 URI 动态解析为资源。
http_method_as_scopebooleanfalse[true, false]设置为 true 时,将 HTTP 请求类型映射到同名范围并添加到所有请求的权限。
timeoutinteger3000[1000, ...]与 Identity Server 的 HTTP 连接超时(毫秒)。
access_token_expires_ininteger300[1, ...]访问令牌的有效期。token.
access_token_expires_leewayinteger0[0, ...]access_token 更新的到期余地。设置后,令牌将在到期前几秒更新 access_token_expires_leeway。这避免了 access_token 在到达 OAuth 资源服务器时刚刚过期的情况。
refresh_token_expires_ininteger3600[1, ...]刷新令牌的失效时间。
refresh_token_expires_leewayinteger0[0, ...]refresh_token 更新的到期余地。设置后,令牌将在到期前几秒刷新 refresh_token_expires_leeway。这样可以避免在到达 OAuth 资源服务器时 refresh_token 刚刚过期的错误。
ssl_verifybooleantrue[true, false]设置为 true 时,验证 TLS 证书是否与主机名匹配。
cache_ttl_secondsinteger86400 (equivalent to 24h)positive integer >= 1插件缓存插件用于向 Keycloak 进行身份验证的发现文档和令牌的最长时间(以秒为单位)。
keepalivebooleantrue[true, false]当设置为 true 时,启用 HTTP keep-alive 保证在使用后仍然保持连接打开。如果您期望对 Keycloak 有很多请求,请设置为 true
keepalive_timeoutinteger60000positive integer >= 1000已建立的 HTTP 连接将关闭之前的空闲时间。
keepalive_poolinteger5positive integer >= 1连接池中的最大连接数。
access_denied_redirect_uristring[1, 2048]需要将用户重定向到的 URI,而不是返回类似 "error_description":"not_authorized" 这样的错误消息。
password_grant_token_generation_incoming_uristring/api/token将此设置为使用密码授予类型生成令牌。该插件会将传入的请求 URI 与此值进行比较。

注意:schema 中还定义了 encrypt_fields = {"client_secret"},这意味着该字段将会被加密存储在 etcd 中。具体参考 加密存储字段

除上述释义外,还有以下需要注意的点:

  • Discovery and endpoints

    • 使用 discovery 属性后,authz-keycloak 插件就可以从其 URL 中发现 Keycloak API 的端点。该 URL 指向 Keyloak 针对相应领域授权服务的发现文档。
    • 如果发现文档可用,则插件将根据该文档确定令牌端点 URL。如果 URL 存在,则 token_endpointresource_registration_endpoint 的值将被其覆盖。
  • Client ID and secret

    • 该插件需配置 client_id 属性来标识自身。
    • 如果 lazy_load_paths 属性被设置为 true,那么该插件还需要从 Keycloak 中获得一个自身访问令牌。在这种情况下,如果客户端对 Keycloak 的访问是加密的,就需要配置 client_secret 属性。
  • Policy enforcement mode

    • policy_enforcement_mode 属性指定了在处理发送到服务器的授权请求时,该插件如何执行策略。
      • ENFORCING mode:即使没有与给定资源关联的策略,请求也会默认被拒绝。policy_enforcement_mode 默认设置为 ENFORCING
      • PERMISSIVE mode:如果资源没有绑定任何访问策略,也被允许请求。
  • Permissions

    • 在处理传入的请求时,插件可以根据请求的参数确定静态或动态检查 Keycloak 的权限。

    • 如果 lazy_load_paths 参数设置为 false,则权限来自 permissions 属性。permissions 中的每个条目都需要按照令牌端点预设的 permission 属性进行格式化。详细信息请参考 Obtaining Permissions.

      note

      有效权限可以是单个资源,也可以是与一个或多个范围配对的资源。

      如果 lazy_load_paths 属性设置为 true,则请求 URI 将解析为使用资源注册端点在 Keycloak 中配置的一个或多个资源。已经解析的资源被用作于检查的权限。

      note

      需要该插件从令牌端点为自己获取单独的访问令牌。因此,请确保在 Keycloak 的客户端设置中设置了 Service Accounts Enabled 选项。

      还需要确保颁发的访问令牌包含具有 uma_protection 角色的 resource_access 声明,以保证插件能够通过 Protection API 查询资源。

  • 自动将 HTTP method 映射到作用域

    http_method_as_scope 通常与 lazy_load_paths 一起使用,但也可以与静态权限列表一起使用。

    • 如果 http_method_as_scope 属性设置为 true,插件会将请求的 HTTP 方法映射到同名范围。然后将范围添加到每个要检查的权限。

    • 如果 lazy_load_paths 属性设置为 false,则插件会将映射范围添加到 permissions 属性中配置的任意一个静态权限——即使它们已经包含一个或多个范围。

  • 使用 password 授权生成令牌

    • 如果要使用 password 授权生成令牌,你可以设置 password_grant_token_generation_incoming_uri 属性的值。

    • 如果传入的 URI 与配置的属性匹配并且请求方法是 POST,则使用 token_endpoint 生成一个令牌。

      同时,你还需要添加 application/x-www-form-urlencoded 作为 Content-Type 标头,usernamepassword 作为参数。

      如下示例是当 password_grant_token_generation_incoming_uri 设置为 /api/token 时的命令:

      curl --location --request POST 'http://127.0.0.1:9080/api/token' \
      --header 'Accept: application/json, text/plain, */*' \
      --header 'Content-Type: application/x-www-form-urlencoded' \
      --data-urlencode 'username=<User_Name>' \
      --data-urlencode 'password=<Password>'

如何启用#

以下示例为你展示了如何在指定 Route 中启用 authz-keycloak 插件,其中 ${realm} 是 Keycloak 中的 realm 名称:

curl http://127.0.0.1:9180/apisix/admin/routes/1 \
-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"uri": "/get",
"plugins": {
"authz-keycloak": {
"token_endpoint": "http://127.0.0.1:8090/auth/realms/${realm}/protocol/openid-connect/token",
"permissions": ["resource name#scope name"],
"client_id": "Client ID"
}
},
"upstream": {
"type": "roundrobin",
"nodes": {
"127.0.0.1:8080": 1
}
}
}'

测试插件#

通过上述命令启用插件后,可以通过以下方法测试插件。

首先需要从 Keycloak 获取 JWT 令牌:

curl \
-d "client_id=<YOUR_CLIENT_ID>" \
-d "username=<YOUR_USERNAMED>" \
-d "password=<YOUR_PASSWORD>" \
-d "grant_type=password" "http://<YOUR_KEYCLOAK_HOST>/auth/realms/${realm}/protocol/openid-connect/token"

之后就可以使用获得的 JWT 令牌发起请求:

curl http://127.0.0.1:9080/get \
-H 'Authorization: Bearer {JWT Token}'

禁用插件#

当你需要禁用 authz-keycloak 插件时,可以通过以下命令删除相应的 JSON 配置,APISIX 将会自动重新加载相关配置,无需重启服务:

curl http://127.0.0.1:9180/apisix/admin/routes/1 \
-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"uri": "/get",
"plugins": {
},
"upstream": {
"type": "roundrobin",
"nodes": {
"127.0.0.1:8080": 1
}
}
}'

插件 Roadmap#

  • 目前,authz-keycloak 插件通过要求定义资源名称和所需的范围,来强制执行路由策略。但 Keycloak 官方适配的其他语言客户端(Java、JavaScript)仍然可以通过动态查询 Keycloak 路径以及延迟加载身份资源的路径来提供路径匹配。在 Apache APISIX 之后发布的插件中即将支持此功能。

  • 支持从 Keycloak JSON 文件中读取权限范畴和其他配置项。