13.6. 客户端范围
使用红帽构建的 Keycloak 在称为 客户端范围 的实体中定义共享客户端配置。客户端范围为 多个客户端 配置协议 映射和 角色范围映射。
客户端范围也支持 OAuth 2 scope 参数。客户端应用使用此参数来请求访问令牌中的声明或角色,具体取决于应用的要求。
要创建客户端范围,请按照以下步骤执行:
点菜单中的 Client Scopes。
客户端范围列表
- 点 Create。
- 为您的客户端命名范围。
- 点 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 规格。
- 配置集
- address
- 电话
客户端范围 配置文件、电子邮件、地址和 电话 在 OpenID Connect 规格中定义。这些范围没有定义任何角色范围映射,但它们定义了协议映射程序。这些映射程序与 OpenID Connect 规格中定义的声明对应。
例如,当您打开 电话 客户端范围并打开 Mappers 选项卡时,您将看到与范围 电话 规范中定义的声明对应的协议映射器。
客户端范围映射器
当 手机 客户端范围链接到客户端时,客户端会自动继承 电话 客户端范围中定义的所有协议映射器。为此客户端发布的访问令牌包含用户的电话号码信息,假设用户具有定义的电话号码。
内置客户端范围包含规格中定义的协议映射程序。您可以自由编辑客户端范围并创建、更新或删除任何协议映射或角色范围映射。
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 选项卡包含为此客户端声明的角色范围映射。它们不包含从客户端范围继承的映射程序和范围映射。可以看到有效的协议映射器(这是客户端本身定义的协议映射,也可以继承从链接的客户端范围中)以及为客户端生成令牌时使用的有效角色范围映射。
流程
- 点客户端的 Client Scopes 选项卡。
- 打开子选项卡 的评估。
- 选择您要应用的可选客户端范围。
这也向您显示 scope 参数的值。这个参数需要从应用程序发送到 Keycloak OpenID Connect 授权端点的红帽构建。
评估客户端范围
要从应用程序为 scope 参数发送自定义值,请参阅 安全 应用程序部分中的 Keycloak JavaScript 适配器。
所有示例都是为特定用户生成,并为特定客户端发布,且值为 scope 参数。示例包括所有使用的声明和角色映射。
13.6.5. 客户端范围权限
当用户被允许使用令牌时,客户端范围才会应用。
当客户端范围没有定义任何角色范围映射时,每个用户都被允许使用此客户端范围。但是,当客户端范围定义了角色范围映射时,该用户必须是至少一个角色的成员。用户角色和客户端范围的角色之间必须有交集。复合角色是评估此交集的因素。
如果用户不允许使用客户端范围,则在生成令牌时不会使用协议映射程序或角色范围映射。客户端范围不会出现在令牌中的 scope 值中。
13.6.6. 域默认客户端范围
使用 Realm Default Client Scopes 定义自动链接到新创建的客户端的一组客户端范围。
流程
- 点客户端的 Client Scopes 选项卡。
- 单击 Default Client Scopes。
在这里,选择要添加为 Default Client Scopes 的客户端范围到新创建的客户端和 可选客户端范围。
默认客户端范围
创建客户端时,如果需要,您可以取消链接默认客户端范围。这与删除 默认角色类似。
13.6.7. 范围解释
- 客户端范围
- 客户端范围是 Red Hat build of Keycloak (在域级别配置)中的实体,并可链接到客户端。当请求发送到带有对应的 scope 参数的 Keycloak 授权端点的红帽构建的 Keycloak 授权端点时,客户端范围由其名称引用。如需了解更多详细信息,请参阅 客户端范围链接 部分。
- 角色范围映射
- 这在客户端或客户端 范围 的范围选项卡下提供。使用 Role 范围映射 来限制访问令牌中可以使用的角色。如需了解更多详细信息 ,请参阅角色范围映射部分。