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