authz-keycloak

描述

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

tip

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

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

属性

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

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

• Discovery and endpoints

  • 使用 discovery 属性后，authz-keycloak 插件就可以从其 URL 中发现 Keycloak API 的端点。该 URL 指向 Keyloak 针对相应领域授权服务的发现文档。
  • 如果发现文档可用，则插件将根据该文档确定令牌端点 URL。如果 URL 存在，则 token_endpoint 和 resource_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 标头，username 和 password 作为参数。

    如下示例是当 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 文件中读取权限范畴和其他配置项。