12.6. 客户端范围
使用红帽构建的 Keycloak 在名为 客户端范围 的实体中定义共享客户端配置。客户端范围为 多个客户端配置 协议映射器 和角色范围映射。
客户端范围也支持 OAuth 2 范围 参数。客户端应用程序使用此参数请求访问令牌中的声明或角色，具体取决于应用程序的要求。
要创建客户端范围，请按照以下步骤执行：
点菜单中的 Client Scopes。
客户端范围列表
- 点 Create。
- 为您的客户端范围命名。
- 点 Save。
客户端范围 与常规客户端有类似的标签页。您可以定义 协议映射器 和角色范围映射。这些映射可由其他客户端继承，并配置为继承此客户端范围。
12.6.1. 协议
在创建客户端范围时，选择 协议。在同一范围内链接的客户端必须具有相同的协议。
每个 realm 在菜单中都有一组预定义的内置客户端范围。
- SAML 协议： role_list.此范围包含 SAML 断言中角色列表的一个协议映射程序。
OpenID Connect 协议：提供 Several 客户端范围：
roles
此范围在 OpenID Connect 规格中未定义，不会自动添加到访问令牌中的 范围 声明中。此范围具有映射程序，用于将用户的角色添加到访问令牌中，并为至少有一个客户端角色的客户端添加受众。在 Audience 部分 更详细地描述了这些映射程序。
web-origins
此范围也没有在 OpenID Connect 规格中定义，且不添加到声明访问令牌的 范围中。此范围用于将允许的 Web 来源添加到访问令牌 allowed-origins 声明中。
microprofile-jwt
此范围处理 MicroProfile/JWT Auth 规范中定义的声明。此范围为 upn 声明定义用户属性映射器，以及 groups 声明的域角色映射器。这些映射程序可以更改，因此不同的属性可用于创建 MicroProfile/JWT 特定声明。
offline_access
当客户端需要获取离线令牌时，可使用此范围。有关离线令牌的更多详细信息，请参阅 离线令牌部分和 OpenID Connect 规格。
- 配置集
- address
- 电话
客户端范围 配置文件、电子邮件、地址和 电话 在 OpenID Connect 规格中定义。这些范围没有定义任何角色范围映射，但它们定义了协议映射程序。这些映射程序与 OpenID Connect 规范中定义的声明对应。
例如，当您打开 电话 客户端范围并打开 Mappers 选项卡时，您将看到与范围 电话 规格中定义的协议映射器对应的协议映射程序。
客户端范围映射器
当 电话 客户端范围链接到客户端时，客户端会自动继承 手机 客户端范围中定义的所有协议映射程序。为此客户端发布的访问令牌包含有关用户的电话号码信息，假定用户有定义的电话号码。
内置客户端范围包含规格中定义的协议映射器。您可以自由编辑客户端范围，并创建、更新或删除任何协议映射程序或角色范围映射。
12.6.3. 将客户端范围链接到客户端
客户端范围和客户端之间的链接在客户端的 Client Scopes 选项卡中配置。客户端范围和客户端之间链接有两种方法。
- 默认客户端范围
- 此设置适用于 OpenID Connect 和 SAML 客户端。为客户端发出 OpenID Connect 令牌或 SAML 断言时应用默认客户端范围。客户端将继承客户端范围中定义的协议映射和角色范围映射。对于 OpenID Connect 协议，始终应用 Mappers 和 Role Scope Mappings，无论 OpenID Connect 授权请求中用于 scope 参数的值是什么。
- 可选的客户端范围
- 此设置仅适用于 OpenID Connect 客户端。为这个客户端发布令牌时会应用可选客户端范围，但仅在 OpenID Connect 授权请求中的 scope 参数请求时应用可选客户端范围。
12.6.3.1. Example
在本例中，假设客户端具有 配置文件，以及链接为默认客户端范围 的电子邮件，以及作为可选客户端范围链接的电话和 地址。客户端在发送请求到 OpenID Connect 授权端点时使用 scope 参数的值。
scope=openid phone
scope 参数包含字符串，范围值除以空格分开。值 openid 是所有 OpenID Connect 请求使用的 meta-value。令牌将包含来自默认客户端范围配置集和 电子邮件的 映射程序 和角色 范围映射，即 scope 参数请求的可选客户端范围。
12.6.4. 评估客户端范围
Mappers 选项卡包含协议映射程序，范围 选项卡包含为此客户端声明的角色范围映射。它们不包含从客户端范围继承的映射程序和范围映射。可以看到有效的协议映射程序（即客户端本身中定义的协议映射程序），以及从链接的客户端范围继承的有效角色范围映射，以及为客户端生成令牌时使用的有效角色范围映射。
流程
- 点客户端的 Client Scopes 选项卡。
- 打开选项卡 评估。
- 选择您要应用的可选客户端范围。
这还向您显示 scope 参数的值。此参数需要从应用程序发送到红帽构建的 Keycloak OpenID Connect 授权端点。
评估客户端范围
要从应用程序发送 scope 参数的自定义值，请参阅 用于 servlet 适配器或 javascript 适配器 部分的参数转发 部分，用于 javascript 适配器。
为特定用户生成所有示例，并为特定客户端发布，且指定的值为 scope 参数。示例包括所有声明和角色映射。
12.6.5. 客户端范围权限
向用户发布令牌时，只有在允许用户使用令牌时才应用客户端范围。
当客户端范围没有定义任何角色范围映射时，允许每个用户使用此客户端范围。但是，当客户端范围定义了角色范围映射时，用户必须至少是其中一个角色的成员。用户角色和客户端范围的角色之间必须有一个交集。复合角色被计算为评估这个交集。
如果用户不允许使用客户端范围，则在生成令牌时不使用协议映射程序或角色范围映射。客户端范围不会出现在 令牌的范围 值中。
12.6.6. 域默认客户端范围
使用 Realm Default Client Scopes 定义自动链接到新创建的客户端的客户端范围集合。
流程
- 点客户端的 Client Scopes 选项卡。
- 点 Default Client Scopes。
在这里，选择您要添加为 Default Client Scopes 的客户端范围到新创建的客户端和 Optional Client Scopes。
默认客户端范围
创建客户端时，如果需要，可以取消链接默认的客户端范围。这与删除 默认角色 类似。
12.6.7. 范围解释
- 客户端范围
- 客户端范围是红帽构建的 Keycloak 中的实体，这些 Keycloak 在域级别配置，并可链接到客户端。当请求发送到红帽构建的 Keycloak 授权端点时，客户端范围会根据名称引用，其范围是 scope 参数的值。如需了解更多详细信息，请参阅 客户端范围链接 部分。
- 角色范围映射
- 这位于客户端或客户端范围的 Scope 选项卡下。使用角色范围映射 来限制访问令牌中可以使用的角色。如需了解更多详细信息 ，请参阅角色范围映射部分。
