authz-keycloak

tip

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

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

属性

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

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

• Client ID and secret

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

• Policy enforcement mode

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

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

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

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

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

• 使用 password 授权生成令牌

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

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

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

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

测试插件

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

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

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

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

插件 Roadmap

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