12.7. 客户端策略
为了便于保护客户端应用程序,以统一方式实现以下点很有用:
- 对客户端可以有的配置设置策略
- 验证客户端配置
- 遵守所需的安全标准和配置文件,如 financial-grade API (FAPI)和 OAuth 2.1
为了以统一的方式实现这些点,引入了 客户端策略 概念。
12.7.1. 使用案例
客户端策略实现以下提到的点:
- 对客户端可以有的配置设置策略
- 客户端上的配置设置可以在客户端创建/更新期间由客户端策略实施,也可以在 OpenID Connect 请求到红帽 Keycloak 服务器(与特定客户端相关)期间强制执行。红帽构建的 Keycloak 支持通过 保护应用程序和服务指南中的客户端注册政策类似的内容。但是,客户端注册策略只能涵盖 OIDC 动态客户端注册。客户端策略不仅涵盖客户端注册策略可以执行的操作,还涵盖其他客户端注册和配置方式。当前计划用于客户端注册,以替换为客户端策略。
- 验证客户端配置
- 红帽构建的 Keycloak 支持验证客户端是否遵循代码交换、请求对象签名算法、保存密钥令牌等设置,等等。它们可以通过每个设置项(在管理控制台、切换、下拉菜单等)来指定。为了使客户端应用程序安全,管理员需要以适当的方式设置许多设置,从而让管理员难以保护客户端应用。客户端策略可以对上述客户端配置进行这些验证,它们也可用于自动配置一些客户端配置交换机来满足高级安全要求。以后,单个客户端配置设置可能会被 客户端策略直接执行所需的验证替代。
- 符合所需的安全标准和配置集,如 FAPI 和 OAuth 2.1
- 默认情况下,全局客户端配置集 是在红帽构建的 Keycloak 中预先配置的客户端配置集。它们预先配置为符合 FAPI 和 OAuth 2.1 等标准安全配置集,这有助于管理员轻松保护其客户端应用程序以遵守特定的安全配置集。目前,红帽构建的 Keycloak 具有支持 FAPI 和 OAuth 2.1 规范的全局配置集。管理员只需要配置客户端策略,以指定哪些客户端应与 FAPI 和 OAuth 2.1 兼容。管理员可以配置客户端配置文件和客户端策略,以便红帽构建的 Keycloak 客户端可轻松与各种其他安全配置集兼容,如 SPA、Native App、Open banking 等。
12.7.2. 协议
客户端策略概念独立于任何特定的协议。但是,红帽构建的 Keycloak 目前只支持 OpenID Connect (OIDC)协议。
12.7.3. 架构
客户端策略由四个构建块组成:Condition、Executor、Profile 和 Policy。
12.7.3.1. 状况
条件决定策略被采用的客户端以及何时采用。当在客户端请求过程中检查一些其他条件(OIDC Authorization request, Token endpoint request 等),在客户端创建/更新时检查一些条件。该条件检查是否满足一个指定的条件。例如,一些条件检查客户端的访问类型是机密。
该条件不能自行使用。它可用于之后描述 的策略。
条件可以与其他可配置提供程序相同。可以配置的内容取决于每个条件的性质。
提供以下条件:
- 创建/更新客户端的方法
- 动态客户端注册(具有初始访问令牌或注册访问令牌的非匿名或授权)
- 管理 REST API (管理员控制台等)
例如,在创建客户端时,当没有初始访问令牌(非动态客户端注册)的情况下,可将条件配置为由 OIDC Dynamic Client Registration 创建为 true。因此,这个条件可用于确保通过 OIDC 动态客户端注册的所有客户端都兼容 FAPI 或 OAuth 2.1。
- 客户端作者(通过存在特定角色或组来检查)
- 在 OpenID Connect 动态客户端注册中,客户端的作者是经过身份验证以获取生成新客户端的访问令牌的最终用户,而不是实际通过访问令牌访问注册端点的现有客户端的服务帐户。在由 Admin REST API 注册时,客户端的作者是类似红帽构建的 Keycloak 管理员的最终用户。
- 客户端访问类型(机密、公共、仅 bearer)
- 例如,当客户端发送授权请求时,如果此客户端机密,则使用策略。当公共客户端禁用了客户端身份验证时,机密客户端启用了客户端身份验证。bearer-only 是已弃用的客户端类型。
- 客户端范围
-
如果客户端具有特定的客户端范围(为默认值或当前请求中使用的可选范围,则评估为 true)。例如,这可用于确保具有范围
fapi-example-scope
的 OIDC 授权请求需要兼容 FAPI。 - 客户端角色
- 适用于具有指定名称的客户端角色。通常,您可以创建指定名称的客户端角色来请求客户端,并将其用作"标记角色",以确保将针对请求的客户端策略应用指定的客户端策略。
对于需要特定客户端应用(如 my-client-1
和 my-client-2)的用例,通常存在
用例。实现此结果的最佳方法是在您的策略中使用 客户端角色 条件,然后创建指定名称的客户端角色来请求客户端。此客户端角色可用作"标记角色",仅用于为特定客户端标记该特定客户端策略。
- 客户端域名、主机或 IP 地址
- 适用于客户端的特定域名。或者,当管理员从特定主机或 IP 地址注册/更新客户端时。
- 任何客户端
- 此条件始终评估为 true。例如,它可用于确保特定域中的所有客户端都兼容 FAPI。
12.7.3.2. executor
executor 指定在采用策略的客户端上执行哪些操作。executor 执行一个或多个指定操作。例如,一些 executor 会检查授权请求中的参数 redirect_uri
的值是否与授权端点上预注册的重定向 URI 完全匹配,并在未授权端点上拒绝此请求。
executor 本身不能单独使用。它可用于之后描述 的配置集。
executor 可以与其他可配置供应商相同。可以配置的内容取决于每个 executor 的性质。
executor 会对各种事件执行操作。executor 的实现可以忽略某些类型的事件(例如,检查 OIDC 请求
对象的 executor 仅适用于 OIDC 授权请求)。事件是:
- 创建客户端(包括通过动态客户端注册创建)
- 更新客户端
- 发送授权请求
- 发送令牌请求
- 发送令牌刷新请求
- 发送令牌撤销请求
- 发送令牌内省请求
- 发送 userinfo 请求
- 使用刷新令牌发送注销请求(请注意,使用刷新令牌退出时,任何规格不支持的 Keycloak 功能的专有红帽构建)。相反,建议您依赖 官方 OIDC 注销。
在每个事件中,executor 都可以在多个阶段工作。例如,在创建/更新客户端时,executor 可以通过自动配置特定的客户端设置来修改客户端配置。之后,executor 会在验证阶段验证此配置。
此 executor 的几个目的之一是实现客户端一致性配置集的安全要求,如 FAPI 和 OAuth 2.1。要做到这一点,需要以下 executors:
- 强制使用安全 客户端身份验证方法进行 客户端
- 使用 enforce Holder-of-key 令牌
- 使用 代码交换强制概念验证(PKCE)
- 使用 Signed JWT 客户端身份验证(private-key-jwt) 的安全签名算法
- 强制 HTTPS 重定向 URI,并确保配置的重定向 URI 不包含通配符
-
强制 OIDC
请求
对象满足高级别 - 对 OIDC Hybrid Flow 强制执行响应类型,包括用作 分离签名 的 ID 令牌,如 FAPI 1 规格中所述,这意味着从授权响应返回的 ID Token 不包含用户配置集数据
-
强制更安全的
状态
和非ce
参数处理以防止 CSRF - 在客户端注册时强制实施更安全的签名算法
-
enforce
binding_message
参数用于 CIBA 请求 - 强制 客户端 Secret 轮转
- 强制客户端注册访问令牌
- 强制检查客户端是否为在启动授权代码流之前发出意图的用例中发布的意图,以获取英国 OpenBanking 等访问令牌
- 强制禁止隐式和混合流
- 强制检查 PAR 请求是否包含授权请求中包含的必要参数
-
使用强制 DPoP-binding 令牌 (在启用
dpop
功能时可用) - 使用轻量级访问令牌强制
- 强制跳过 刷新令牌轮转,且不会从刷新令牌响应返回刷新令牌
- 强制 OAuth 2.1 规格所需的有效重定向 URI
12.7.3.3. profile
配置集由多个 executors 组成,它可以实现一个安全配置集,如 FAPI 和 OAuth 2.1。配置集可以通过 Admin REST API (Admin Console)与其 executors 一起配置。有三个 全局配置集,它们默认在 Keycloak 的红帽构建中配置,并带有预配置的 executors,与 FAPI 1 Baseline, FAPI 1 Advanced, FAPI CIBA, FAPI 2 和 OAuth 2.1 规格兼容。更多相关信息,请参阅 Securing Applications and Services Guide 中的 FAPI 和 OAuth 2.1 部分。
12.7.3.4. policy
策略由多个条件和配置集组成。该策略可用于满足此策略的所有条件的客户端。该策略指的是多个配置集,这些配置集的所有 executors 会根据这个策略的客户端执行其任务。
12.7.4. Configuration
策略、配置集、条件、executors 可由 Admin REST API 配置,这意味着管理控制台。为此,有一个标签 Realm
全局客户端配置集 在每个域中自动可用。但是,默认情况下不配置任何客户端策略。这意味着,如果管理员希望其域的客户端符合 FAPI,则始终需要创建任何客户端策略。全局配置集无法更新,但管理员可轻松将它们用作模板,并在需要在全局配置集配置中进行一些小修改的情况下创建自己的配置集。Admin Console 中提供了 JSON 编辑器,它简化了基于某些全局配置集的新配置集的创建。
12.7.5. 向后兼容性
客户端策略可以替换客户端注册策略,如 保护应用程序和服务指南 中所述。但是,客户端注册政策仍然是共存的。这意味着,在动态客户端注册请求创建/更新客户端期间,会应用客户端策略和客户端注册策略。
当前计划是要删除的客户端注册策略功能,并且现有客户端注册策略将自动迁移到新的客户端策略中。
12.7.6. 客户端 Secret 轮转示例
请参阅 客户端 secret 轮转的示例配置。