12.7. 客户端策略


为了方便保护客户端应用程序,以统一的方式识别以下点会很有用:

  • 在客户端可以有什么配置时设置策略
  • 客户端配置验证
  • 遵守所需的安全标准和配置集,如 发行级 API (FAPI)

为了以统一的方式达到这些点,引入了客户端策略 概念。

12.7.1. 使用案例

客户端策略已确认如下点,如下所示:

在客户端可以有什么配置时设置策略
客户端上的配置设置可以在客户端创建/更新期间由客户端策略实施,也可以在 OpenID Connect 请求到红帽 Keycloak 服务器(与特定客户端相关)期间强制执行。红帽构建的 Keycloak 还通过 保护应用程序和服务指南 中描述的客户端注册策略支持类似的操作。但是,客户端注册策略只能涵盖 OIDC Dynamic Client Registration。客户端策略不仅涵盖了客户端注册策略可以做什么,还可以执行其他客户端注册和配置方式。当前计划是客户端注册以由客户端策略替代。
客户端配置验证
红帽构建的 Keycloak 支持验证客户端是否遵循代码交换、请求对象签名算法、保存密钥令牌等设置,等等。它们可由每个设置项目(在管理控制台、交换机、下拉菜单等)指定。要使客户端应用程序安全,管理员需要以适当的方式设置许多设置,这使得管理员很难保护客户端应用程序。客户端策略可以对上述客户端配置进行这些验证,它们也可用于自动配置一些客户端配置交换机来满足高级安全要求。未来,单个客户端配置设置可能会被直接执行所需的验证的客户端策略替代。
遵循所需的安全标准和配置文件,如 FAPI
默认情况下,全局客户端配置集 是在红帽构建的 Keycloak 中预先配置的客户端配置集。它们预先配置为与 FAPI 等标准安全配置文件兼容,这使管理员可以轻松地确保其客户端应用程序符合特定的安全配置文件。目前,红帽构建的 Keycloak 具有支持 FAPI 1 规格的全局配置集。管理员只需要配置客户端策略,以指定哪些客户端应该与 FAPI 兼容。管理员可以配置客户端配置文件和客户端策略,以便红帽构建的 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 授权请求、令牌端点请求等)时,会在客户端创建/更新时检查一些条件。条件检查是否满足一个指定的条件。例如,一些条件检查客户端访问类型是否是机密的。

条件不能自行使用。它可以在稍后描述 的策略 中使用。

一个条件可以与其他可配置提供程序相同。可以配置什么取决于每个情况的性质。

提供以下条件:

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

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

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

12.7.3.2. executor

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

executor 无法自行使用。它可以在稍后 描述的配置 集中使用。

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

executor 充当各种事件。executor 实现可以忽略特定类型的事件(例如,executor 用于在 OIDC 授权请求中检查 OIDC 请求 对象)。事件是:

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

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

此执行器的几个目的之一就是实现像 FAPI 这样的客户端符合配置文件的安全要求。要做到这一点,需要以下 executor:

  • 客户端使用 强制安全客户端身份验证方法
  • 使用强制密钥令牌
  • 使用 代码交换(PKCE)的 强制密钥
  • 使用 签名 JWT 客户端身份验证(private-key-jwt) 的强制签名算法
  • 强制 HTTPS 重定向 URI,并确保配置的重定向 URI 不包含通配符
  • 强制 OIDC 请求 对象满足高安全级别
  • OIDC Hybrid Flow 的强制响应类型包括用作 分离签名 的 ID 令牌,如 FAPI 1 规格中所述,这意味着从授权响应返回的 ID 令牌不包含用户配置文件数据
  • 强制 更多 安全状态 和防止 CSRF 的处理参数
  • 在客户端注册时强制实施更安全的签名算法
  • enforce binding_message 参数用于 CIBA 请求
  • 强制 客户端 Secret 轮转
  • 强制客户端注册访问令牌
  • 强制检查客户端是否在启动授权代码流前发出成的用例,以获取诸如美国 OpenBanking 等访问令牌
  • 强制禁止隐式和混合流
  • 强制检查 PAR 请求是否包含授权请求中包含的必要参数
  • 强制跳过 刷新令牌轮转,且不会从刷新令牌响应返回刷新令牌

12.7.3.3. profile

配置文件由多个 executors 组成,它可以实现类似 FAPI 的安全配置文件。配置文件可通过 Admin REST API (管理员控制台)及其 executors 配置。有三个 全局配置集,它们默认在 Keycloak 的红帽构建中配置,它们与 FAPI Baseline, FAPI Advanced 和 FAPI CIBA 规格兼容。安全应用程序和服务 指南的 FAPI 部分中存在更多详细信息。

12.7.3.4. 策略

策略由多个条件和配置集组成。该策略可以采用满足此策略条件的客户端。策略引用了多个配置集,以及这些配置集的所有执行者都针对此策略所采用的客户端执行其任务。

12.7.4. Configuration

策略、配置集、条件、executors 可通过 Admin REST API 配置,这意味着管理控制台。为此,有一个 Realm Realm Settings Client Policies 选项卡,这意味着管理员可以为每个域具有客户端策略。

全局客户端配置文件在每个 域中自动可用。但是,默认没有配置任何客户端策略。这意味着,如果管理员希望其域的客户端与 FAPI 兼容,则始终需要创建任何客户端策略。无法更新全局配置文件,但管理员可以轻松地将它们用作模板,如果他们想要在全局配置文件配置中进行一些更改,则创建自己的配置集。管理控制台中提供了 JSON Editor,它简化了根据一些全局配置集创建新配置集。

12.7.5. 向后兼容性

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

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

12.7.6. 客户端 Secret 轮转示例

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

返回顶部
Red Hat logoGithubredditYoutubeTwitter

学习

尝试、购买和销售

社区

关于红帽文档

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

让开源更具包容性

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

關於紅帽

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

Theme

© 2025 Red Hat