13.7. 客户端策略


为了方便保护客户端应用程序,以统一的方式实现以下点会很有帮助。

  • 对客户端可以有的配置设置策略
  • 验证客户端配置
  • 遵守所需的安全标准和配置文件,如 foundation-grade API (FAPI)和 OAuth 2.1

要以统一的方式实现这些点,引入了 客户端策略 概念。

13.7.1. 使用案例

客户端策略实现了如下所列点:

对客户端可以有的配置设置策略
客户端上的配置设置可以通过客户端创建/更新期间的客户端策略实施,也可以在 OpenID Connect 请求到红帽构建的 Keycloak 服务器期间(与特定客户端相关)。红帽构建的 Keycloak 支持通过 保护应用程序和服务指南中的 客户端注册 策略 中所述的类似内容。但是,客户端注册策略只能涵盖 OIDC Dynamic Client Registration。客户端策略不仅涵盖客户端注册策略可以做什么,以及其他客户端注册和配置方式。当前计划用于客户端注册,由客户端策略替代。
验证客户端配置
红帽构建的 Keycloak 支持验证客户端是否遵循 Code Exchange 的概念验证、Request Object Signing Algorithm、Holder-of-Key Token 等设置,以此类推,如 Authorization Endpoint、Token Endpoint 等。它们可以由每个设置项目(在管理控制台、开关、下拉菜单等)指定。要使客户端应用程序安全,管理员需要以适当的方式设置许多设置,这使管理员很难保护客户端应用程序。客户端策略可以对上述客户端配置进行这些验证,也可以使用它们自动配置一些客户端配置交换机来满足高级安全要求。以后,单个客户端配置设置可能会被客户端策略直接执行所需的验证替代。
遵循所需的安全标准和配置集,如 FAPI 和 OAuth 2.1
全局客户端配置集 是默认情况下,在 Red Hat build of Keycloak 中预先配置的客户端配置集。它们预先配置为符合安全应用程序部分中的 FAPIOAuth 2.1 等标准安全配置集,这有助于管理员轻松确保其客户端应用程序符合特定的安全配置集。https://docs.redhat.com/en/documentation/red_hat_build_of_keycloak/26.2/html-single/securing_applications_and_services_guide/目前,红帽构建的 Keycloak 有全局配置集来支持 FAPI 和 OAuth 2.1 规格。管理员只需要配置客户端策略,以指定哪些客户端应与 FAPI 和 OAuth 2.1 兼容。管理员可以配置客户端配置文件和客户端策略,以便红帽构建的 Keycloak 客户端可以轻松符合 SPA、原生 App、Open bank 等各种安全配置集。

13.7.2. 协议

客户端策略概念独立于任何特定协议。红帽构建的 Keycloak 目前支持 OpenID Connect (OIDC)协议 的特别客户端配置集,但还有可用于 SAML 协议 的客户端配置集。

13.7.3. 架构

客户端策略由四个构建块组成:Condition、Executor、Profile 和 Policy。

13.7.3.1. 状况

条件决定策略的采用哪个客户端以及何时采用。当在客户端请求过程中检查一些其他条件(OIDC 授权请求、Token 端点请求等)时,会在客户端创建/更新时检查一些条件。条件检查是否满足指定条件。例如,一些条件会检查客户端的访问类型是否为 confidential。

条件不能单独使用。它可用于之后描述 的策略

条件可以的配置与其他可配置提供程序相同。可以配置的内容取决于每个条件的性质。

提供了以下条件:

创建/更新客户端的方法
  • 动态客户端注册(使用 Initial 访问令牌或注册访问令牌进行非验证或注册访问令牌)
  • 管理 REST API (管理员控制台等)

例如,在创建客户端时,可以将条件配置为在 OIDC Dynamic Client Registration 创建时评估为 true,而无需初始访问令牌(非动态客户端注册)。因此,这个条件可用于确保通过 OIDC Dynamic Client Registration 注册的所有客户端都兼容 FAPI 或 OAuth 2.1。

客户端的作者(通过存在特定角色或组检查)
在 OpenID Connect 动态客户端注册中,客户端的作者是经过身份验证的最终用户,以获取用于生成新客户端的访问令牌,而不是现有客户端实际访问具有访问令牌的注册端点的服务帐户。在 Admin REST API 注册时,客户端的作者是红帽构建的 Keycloak 管理员一样的最终用户。
客户端访问类型(机密、公共、bearer-only)
例如,当客户端发送授权请求时,如果此客户端是机密,则会采用策略。当公共客户端禁用了客户端身份验证时,机密客户端启用了客户端身份验证。bearer-only 是已弃用的客户端类型。
客户端范围
如果客户端具有特定的客户端范围(作为默认值,或作为当前请求中使用的可选范围),则评估为 true。例如,这可用于确保具有范围 fapi-example-scope 的 OIDC 授权请求需要兼容 FAPI。
客户端角色
适用于具有指定名称的客户端角色的客户端。通常,您可以创建指定名称的客户端角色来请求客户端,并将其用作"标记角色",以确保为请求的客户端应用指定的客户端策略。
注意

对于需要特定客户端的应用程序(如 my-client-1my -client-2)时,通常会存在用例。实现此结果的最佳方法是在策略中使用 客户端角色 条件,然后创建指定名称的客户端角色来请求客户端。此客户端角色可用作"标记角色",仅用于为特定客户端标记该特定客户端策略。

客户端域名、主机或 IP 地址
适用于客户端的特定域名。或者,对于管理员从特定主机或 IP 地址注册/更新客户端时。
客户端属性
适用于带有指定 name 和 value 的 client 属性的客户端。如果您指定多个客户端属性,将使用 AND 条件来评估它们。如果要使用 OR 条件来评估,请多次设置此条件。
任何客户端
此条件始终评估为 true。它可用于确保特定域中的所有客户端都兼容 FAPI。
ACR Condition
当身份验证请求中请求的 ACR 值与条件中配置的值匹配时应用。例如,它可以用来根据请求的 ACR 值选择身份验证流。如需了解更多详细信息,请参阅相关文档和 官方 OIDC 规格
授权类型
当使用特定授权类型时,评估为 true。例如,它可以与 Client Scope 结合使用,以便在请求特定客户端范围时阻止令牌交换请求。

13.7.3.2. executor

executor 指定在采用策略的客户端上执行什么操作。executor 执行一个或多个指定的操作。例如,一些 executor 会检查授权请求中参数 redirect_uri 的值是否与 Authorization Endpoint 上预注册重定向 URI 完全匹配,如果不拒绝此请求。

执行程序本身不能单独使用。它可用于之后描述 的配置集

executor 可以像其他可配置的提供程序一样配置。可以配置的内容取决于每个 executor 的性质。

执行器负责各种事件。executor 实现可以忽略某些类型的事件(例如,检查 OIDC 请求 对象的 executor 的行为仅限于 OIDC 授权请求)。事件是:

  • 创建客户端(包括通过动态客户端注册创建)
  • 更新客户端
  • 发送授权请求
  • 发送令牌请求
  • 发送令牌刷新请求
  • 发送令牌撤销请求
  • 发送令牌内省请求
  • 发送 userinfo 请求
  • 使用刷新令牌发送注销请求(请注意,使用刷新令牌的注销是任何规格不支持的 Keycloak 功能的专有构建)。建议依赖 官方 OIDC 注销

在每个事件中,executor 可以在多个阶段工作。例如,在创建/更新客户端时,executor 可以通过自动配置特定的客户端设置来修改客户端配置。之后,executor 在验证阶段验证此配置。

此 executor 的几个目的之一是实现客户端一致性配置集的安全要求,如 FAPI 和 OAuth 2.1。要做到这一点,需要以下 executor:

  • enforce 安全客户端 验证方法用于客户端
  • 使用 enforce Holder-of-key 令牌
  • 使用强制代码交换(PKCE)
  • Signed JWT 客户端身份验证强制执行安全签名算法(private-key-jwt)
  • 强制 HTTPS 重定向 URI,并确保配置的重定向 URI 不包含通配符
  • 强制 OIDC 请求 对象满足高安全性级别
  • 强制响应 OIDC 混合流,包括用作 分离签名 的 ID 令牌,如 FAPI 1 规格 中所述,这意味着从授权响应返回的 ID 令牌不包含用户配置集数据
  • 为防止 CSRF 强制更安全 状态 和非ce 参数处理
  • 在客户端注册时强制实施更安全的签名算法
  • enforce binding_message 参数用于 CIBA 请求
  • enforce Client Secret Rotation
  • 强制客户端注册访问令牌
  • 强制检查客户端是否在用例中发出意图,在启动授权代码流前发出意图,以获取英国 OpenBanking 等访问令牌
  • 强制禁止隐式和混合流程
  • 强制检查 PAR 请求是否包含授权请求包含的必要参数
  • 使用强制 DPoP-binding 令牌 (启用 dpop 功能时可用)
  • 使用轻量级访问令牌强制
  • 强制 刷新令牌轮转,且不会从刷新令牌响应中返回刷新令牌
  • 强制 OAuth 2.1 规格所需的有效重定向 URI
  • 强制 SAML 重定向绑定无法使用,或者 SAML 请求和断言被签名

另一个可用的 executor 是 auth-flow-enforce,可用于在身份验证请求期间强制执行身份验证流。例如,它可用于根据特定条件(如特定范围或 ACR 值)选择流。如需了解更多详细信息,请参阅相关文档

13.7.3.3. profile

配置集由多个 executors 组成,它可以实现 FAPI 和 OAuth 2.1 等安全配置集。配置集可以通过 Admin REST API (Admin Console)及其 executor 配置。红帽构建的 Keycloak 有三个 全局配置集,它们默认与 FAPI 1 Baseline, FAPI 1 Baseline, FAPI CIBA, FAPI CIBA, FAPI 2 和 OAuth 2.1 规范兼容预先配置的 executor。FAPIOAuth 2.1 中的 安全应用程序部分提供了更多详细信息

13.7.3.4. policy

策略由多个条件和配置集组成。该策略可适用于满足此策略的所有条件的客户端。该策略指的是多个配置集,以及这些配置集的所有 executors 对这个策略要应用到的客户端执行其任务。

13.7.4. Configuration

策略、配置文件、条件、executor 可以由 Admin REST API 配置,这意味着管理控制台。为此,有一个 tab Realm Realm Settings Client Policies,这意味着管理员可以为每个域具有客户端策略。

Global Client Profiles 在每个域中自动可用。但是,没有默认配置的客户端策略。这意味着,如果管理员希望其域的客户端兼容 FAPI,则需要创建任何客户端策略。全局配置文件无法更新,但如果管理员想要在全局配置集配置中做一些更改,则管理员可以轻松地将其用作模板,并创建自己的配置集。Admin 控制台中提供了 JSON 编辑器,它简化了基于某些全局配置集的创建新配置集。

13.7.5. 后向兼容性

客户端策略可以替换 客户端注册服务 中与安全 应用程序和服务指南中的 客户端注册 策略。但是,客户端注册策略仍共存。这意味着,例如,在动态客户端注册请求创建/更新客户端期间,会应用客户端策略和客户端注册策略。

当前计划正在删除客户端注册策略功能,现有的客户端注册策略将自动迁移到新的客户端策略中。

13.7.6. 客户端 Secret 轮转示例

请参阅 客户端 secret 轮转的示例配置

返回顶部
Red Hat logoGithubredditYoutubeTwitter

学习

尝试、购买和销售

社区

关于红帽文档

通过我们的产品和服务,以及可以信赖的内容,帮助红帽用户创新并实现他们的目标。 了解我们当前的更新.

让开源更具包容性

红帽致力于替换我们的代码、文档和 Web 属性中存在问题的语言。欲了解更多详情,请参阅红帽博客.

關於紅帽

我们提供强化的解决方案,使企业能够更轻松地跨平台和环境(从核心数据中心到网络边缘)工作。

Theme

© 2025 Red Hat