客户端模板

## 客户端模板
使用 MaxId 在称为客户端作用域的实体中定义共享客户端配置。客户端范围为多个客户端配置协议映射器和角色范围映射。

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

要创建客户端范围，请执行以下步骤：

1. 单击菜单中的客户端范围。
   客户范围列表
   ![](/media/202309/2023-09-19_102328_766248.jpeg)
2. 单击创建。
3. 命名您的客户范围。
4. 单击“保存”。
客户端范围具有与常规客户端类似的选项卡。您可以定义协议映射器和角色范围映射。这些映射可以由其他客户端继承，并配置为从此客户端范围继承。

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

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

1. SAML 协议：role_list。此范围包含一个用于 SAML 断言中的角色列表的协议映射器。
2. OpenID Connect 协议：有多个可用的客户端范围：

- 角色
    此范围未在 OpenID Connect 规范中定义，并且不会自动添加到访问令牌中的范围声明中。此作用域具有映射器，用于将用户的角色添加到访问令牌，并为至少具有一个客户端角色的客户端添加受众。这些映射器在“受众”部分中有更详细的描述。

- 网络起源
    此范围也未在 OpenID Connect 规范中定义，也未添加到声明访问令牌的范围中。此范围用于将允许的 Web 来源添加到访问令牌allowed-origins声明中。

- 微轮廓-jwt
    此范围处理MicroProfile/JWT Auth 规范中定义的声明。此范围定义了upn声明的用户属性映射器和groups声明的领域角色映射器。可以更改这些映射器，以便可以使用不同的属性来创建 MicroProfile/JWT 特定声明。

- 离线访问
    此范围用于客户端需要获取离线令牌的情况。

- 轮廓
   - 电子邮件
   - 地址
   - 电话

客户范围**配置**文件、**电子邮件**、地址和**电话均在**OpenID Connect 规范中定义。这些作用域没有定义任何角色作用域映射，但它们确实定义了协议映射器。这些映射器对应于 OpenID Connect 规范中定义的声明。

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

客户端范围映射器

![](/media/202309/2023-09-19_102515_681455.jpeg)

当电话客户端作用域链接到客户端时，客户端会自动继承电话客户端作用域中定义的所有协议映射器。假设用户具有已定义的电话号码，为此客户端颁发的访问令牌包含有关用户的电话号码信息。

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

### 许可相关设置

客户端范围包含与许可页面相关的选项。如果在客户端上启用了“需要许可” ，则这些选项非常有用。

在许可页面上显示
如果启用在**许可页面**上显示，并且范围已添加到需要许可的客户端，则许可页面显示的文本中指定的文本将显示在许可页面上。当用户经过身份验证且用户从 MaxId 重定向到客户端之前，会显示此文本。如果禁用在许可页面上显示，则此客户端范围将不会显示在许可页面上。

许可页面显示的文本
当需要同意时将此客户端范围添加到客户端时，许可页面上显示的文本默认为客户端范围的名称。**可以通过**使用${var-name}字符串指定替换变量来自定义此文本的值。自定义值在主题的属性文件中配置。有关定制的更多信息，请参阅 服务器开发人员指南。

### 将客户端范围与客户端链接起来
客户端作用域和客户端之间的链接是在客户端的“客户端作用域”选项卡中配置的。可以使用两种方式来链接客户端范围和客户端。

**默认客户端范围**
此设置适用于 OpenID Connect 和 SAML 客户端。为客户端发出 OpenID Connect 令牌或 SAML 断言时，将应用默认客户端范围。客户端将继承在客户端范围上定义的协议映射器和角色范围映射。对于 OpenID Connect 协议，始终应用映射器和角色范围映射，无论 OpenID Connect 授权请求中的范围参数使用什么值。

**可选的客户范围**
此设置仅适用于 OpenID Connect 客户端。为该客户端颁发令牌时，会应用可选客户端范围，但仅当OpenID Connect 授权请求中的范围参数请求时才应用。

例子
对于此示例，假设客户将**个人资料和电子邮件**链接为默认客户范围，并将电话和地址链接为可选客户范围。客户端在向 OpenID Connect 授权端点发送请求时使用范围参数的值。

`scope=openid phone`

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

### 评估客户范围
“映射器”选项卡包含协议映射器，“范围”选项卡包含为此客户端声明的角色范围映射。它们不包含从客户端范围继承的映射器和范围映射。可以看到有效的协议映射器（即在客户端本身定义的协议映射器以及从链接的客户端范围继承的协议映射器）以及为客户端生成令牌时使用的有效角色范围映射。

程序
1. 单击客户端的“客户端范围”选项卡。
2. 打开子选项卡评估。
3. 选择您要应用的可选客户端范围。

这还将显示范围参数的值。该参数需要从应用程序发送到 MaxId OpenID Connect 授权端点。

评估客户范围

![](/media/202309/2023-09-19_105046_426552.jpeg)

所有示例都是为特定用户生成的，并为特定客户端发出的，并具有指定的范围参数值。这些示例包括使用的所有声明和角色映射。

### 客户端范围权限
向用户颁发令牌时，仅当允许用户使用客户端范围时才适用。

当客户端作用域未定义任何角色作用域映射时，每个用户都可以使用此客户端作用域。但是，当客户端作用域定义了角色作用域映射时，用户必须是至少其中一个角色的成员。用户角色和客户端范围的角色之间必须存在交集。评估这种交集时会考虑复合角色。

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

#### Realm 默认客户端范围
使用**领域默认客户端范围**来定义自动链接到新创建的客户端的客户端范围集。

程序
  1.单击客户端的“客户端范围”选项卡。
从这里，选择要添加为默认客户端范围到新创建的客户端和可选客户端范围的客户端范围。

默认客户端范围

![](/media/202309/2023-09-19_105206_231817.jpeg)
创建客户端时，您可以根据需要取消链接默认客户端范围。这类似于删除默认角色。

### 范围解释
**客户范围**
客户端范围是 MaxId 中在领域级别配置的实体，可以链接到客户端。当请求使用范围参数的相应值发送到 MaxId 授权端点时，客户端范围将通过其名称进行引用。有关更多详细信息，请参阅客户端范围链接部分。

**角色范围映射**
这可以在客户端或客户端范围的“范围”选项卡下找到。使用角色范围映射来限制可以在访问令牌中使用的角色。有关更多详细信息，请参阅角色范围映射部分。

**授权范围**
授权范围涵盖可以在应用程序中执行的操作。有关更多详细信息，请参阅授权服务指南。