13.6. 客户端范围


使用红帽构建的 Keycloak 在称为 客户端范围 的实体中定义共享客户端配置。客户端范围为 多个客户端 配置协议 映射和 角色范围映射

客户端范围也支持 OAuth 2 scope 参数。客户端应用使用此参数来请求访问令牌中的声明或角色,具体取决于应用的要求。

要创建客户端范围,请按照以下步骤执行:

  1. 点菜单中的 Client Scopes

    客户端范围列表

    client scopes list

  2. Create
  3. 为您的客户端命名范围。
  4. Save

客户端范围 与常规客户端有类似的标签页。您可以定义 协议映射程序 和角色范围映射。这些映射可以被其他客户端继承,并配置为继承此客户端范围。

13.6.1. 协议

创建客户端范围时,请选择 协议。同一范围内链接的客户端必须具有相同的协议。

每个域在菜单中都有一组预定义的内置客户端范围。

  • SAML 协议: role_list。此范围包含一个用于 SAML 断言中角色列表的协议映射器。
  • OpenID Connect 协议:提供客户端范围:

    • roles

      此范围不在 OpenID Connect 规格中定义,不会自动添加到访问令牌中的 scope 声明中。此范围具有映射程序,用于将用户的角色添加到访问令牌中,并为至少一个客户端角色的客户端添加受众。在 Audience 部分中 更详细地描述了这些映射程序。

    • web-origins

      此范围也没有在 OpenID Connect 规格中定义,不会添加到声明访问令牌的 范围中。此范围用于将允许的 Web 源添加到访问令牌 allowed-origins 声明中。

    • microprofile-jwt

      此范围处理 MicroProfile/JWT Auth 规范中定义的声明。此范围为 upn 声明定义了用户属性映射器,并为 声明定义一个 realm 角色映射器。这些映射程序可以更改,以便可以使用不同的属性来创建 MicroProfile/JWT 特定的声明。

    • offline_access

      当客户端需要获取离线令牌时,使用此范围。有关离线令牌的更多详细信息,请参阅 离线访问 部分和 OpenID Connect 规格

    • 配置集
    • email
    • address
    • 电话

客户端范围 配置文件电子邮件地址和 电话OpenID Connect 规格中定义。这些范围没有定义任何角色范围映射,但它们定义了协议映射程序。这些映射程序与 OpenID Connect 规格中定义的声明对应。

例如,当您打开 电话 客户端范围并打开 Mappers 选项卡时,您将看到与范围 电话 规范中定义的声明对应的协议映射器。

客户端范围映射器

client scopes phone

手机 客户端范围链接到客户端时,客户端会自动继承 电话 客户端范围中定义的所有协议映射器。为此客户端发布的访问令牌包含用户的电话号码信息,假设用户具有定义的电话号码。

内置客户端范围包含规格中定义的协议映射程序。您可以自由编辑客户端范围并创建、更新或删除任何协议映射或角色范围映射。

13.6.3. 与客户端的链接客户端范围

客户端范围和客户端之间的链接在客户端的 Client Scopes 选项卡中配置。提供了在客户端范围和客户端之间进行链接的两种方法。

默认客户端范围
此设置适用于 OpenID Connect 和 SAML 客户端。在为客户端发出 OpenID Connect 令牌或 SAML 断言时,会应用默认客户端范围。客户端将继承客户端范围中定义的协议映射程序和角色范围映射。对于 OpenID Connect 协议,无论 OpenID Connect 授权请求中的 scope 参数的值是什么,始终应用 Mappers 和 Role Scope 映射。
可选客户端范围
此设置仅适用于 OpenID Connect 客户端。可选客户端范围在为此客户端发布令牌时应用,但仅在 OpenID Connect 授权请求中的 scope 参数请求时应用。

13.6.3.1. Example

在本例中,假设客户端具有链接到默认客户端范围的 配置文件和 电子邮件,以及链接到可选客户端范围的电话和 地址在向 OpenID Connect 授权端点发送请求时,客户端使用 scope 参数的值。

scope=openid phone

scope 参数包含字符串,范围值除以空格。openid 值是用于所有 OpenID Connect 请求的元数据值。令牌将包含来自默认客户端范围 配置文件和 电子邮件的 映射程序和角色范围映射,以及 电话,这是 scope 参数请求的可选客户端范围。

13.6.4. 评估客户端范围

Mappers 选项卡包含协议映射程序,scope 选项卡包含为此客户端声明的角色范围映射。它们不包含从客户端范围继承的映射程序和范围映射。可以看到有效的协议映射器(这是客户端本身定义的协议映射,也可以继承从链接的客户端范围中)以及为客户端生成令牌时使用的有效角色范围映射。

流程

  1. 点客户端的 Client Scopes 选项卡。
  2. 打开子选项卡 的评估
  3. 选择您要应用的可选客户端范围。

这也向您显示 scope 参数的值。这个参数需要从应用程序发送到 Keycloak OpenID Connect 授权端点的红帽构建。

评估客户端范围

client scopes evaluate

注意

要从应用程序为 scope 参数发送自定义值,请参阅 安全 应用程序部分中的 Keycloak JavaScript 适配器

所有示例都是为特定用户生成,并为特定客户端发布,且值为 scope 参数。示例包括所有使用的声明和角色映射。

13.6.5. 客户端范围权限

当用户被允许使用令牌时,客户端范围才会应用。

当客户端范围没有定义任何角色范围映射时,每个用户都被允许使用此客户端范围。但是,当客户端范围定义了角色范围映射时,该用户必须是至少一个角色的成员。用户角色和客户端范围的角色之间必须有交集。复合角色是评估此交集的因素。

如果用户不允许使用客户端范围,则在生成令牌时不会使用协议映射程序或角色范围映射。客户端范围不会出现在令牌中的 scope 值中。

13.6.6. 域默认客户端范围

使用 Realm Default Client Scopes 定义自动链接到新创建的客户端的一组客户端范围。

流程

  1. 点客户端的 Client Scopes 选项卡。
  2. 单击 Default Client Scopes

在这里,选择要添加为 Default Client Scopes 的客户端范围到新创建的客户端和 可选客户端范围

默认客户端范围

client scopes default

创建客户端时,如果需要,您可以取消链接默认客户端范围。这与删除 默认角色类似

13.6.7. 范围解释

客户端范围
客户端范围是 Red Hat build of Keycloak (在域级别配置)中的实体,并可链接到客户端。当请求发送到带有对应的 scope 参数的 Keycloak 授权端点的红帽构建的 Keycloak 授权端点时,客户端范围由其名称引用。如需了解更多详细信息,请参阅 客户端范围链接 部分。
角色范围映射
这在客户端或客户端 范围 的范围选项卡下提供。使用 Role 范围映射 来限制访问令牌中可以使用的角色。如需了解更多详细信息 ,请参阅角色范围映射部分
Red Hat logoGithubRedditYoutubeTwitter

学习

尝试、购买和销售

社区

关于红帽文档

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

让开源更具包容性

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

關於紅帽

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

© 2024 Red Hat, Inc.