13.4. OIDC 令牌和 SAML 断言映射
接收 ID 令牌、访问令牌或 SAML 断言的应用程序可能需要不同的角色和用户元数据。
您可以使用红帽构建的 Keycloak 来实现：
- 硬编码角色、声明和自定义属性。
- 将用户元数据拉取到令牌或断言中。
- 重命名角色。
您可以在管理控制台的 Mappers 选项卡中执行这些操作。
Mappers 标签页
新客户端没有内置映射程序，但可以从客户端范围继承某些映射程序。如需了解更多详细信息，请参阅 客户端范围部分。
协议映射程序将项目（如电子邮件地址）映射到身份和访问令牌中的特定声明。映射器的功能应该从其名称中自我解释。您可以通过单击 Add Builtin 来添加预配置的映射程序。
每个映射程序都有一组通用的设置。根据映射器类型，提供额外的设置。单击映射程序旁边的 Edit，以访问配置屏幕，以调整这些设置。
映射器配置
可以通过将鼠标悬停在工具提示上查看各个选项的详细信息。
您可以使用大多数 OIDC 映射程序来控制声明的放置位置。您可以通过调整 Add to ID 令牌和 Add to access token 开关，从 id 和访问令牌 中包含或排除声明。
您可以添加映射器类型，如下所示：
流程
- 转至 映射程序 选项卡。
单击 Configure a new mapper。
添加映射程序
- 从列表中选择 Mapper Type。
13.4.1. 优先级顺序
映射器实施具有 优先级顺序。优先级顺序 不是映射器的配置属性。它是映射器的 concrete 实现的属性。
Mappers 按照映射器列表的顺序排序。令牌或断言的更改会按照先应用最低的顺序应用。因此，依赖于其他实现的实现会按照必要顺序进行处理。
例如，要计算令牌中包含的角色：
- 解决基于这些角色的受众。
- 处理使用令牌中已可用的角色和受众的 JavaScript 脚本。
13.4.2. OIDC 用户会话备注映射程序
用户会话详情使用映射程序定义，当您在客户端上使用或启用功能时，会自动包含。单击 Add builtin 以包括会话详细信息。
模拟用户会话提供以下详情：
- IMPERSONATOR_ID ：模拟用户的 ID。
- IMPERSONATOR_USERNAME: 模拟用户的用户名。
服务帐户会话提供以下详情：
- clientId ：服务帐户的客户端 ID。
- client_id ：服务帐户的客户端 ID。
- clientAddress ：服务帐户验证设备的远程主机 IP。
- clientHost ：服务帐户验证设备的远程主机名称。
13.4.3. script mapper
通过运行用户定义的 JavaScript 代码，使用 Script Mapper 将声明映射到令牌。有关将脚本部署到服务器的详情，请参阅 JavaScript 提供程序。
当脚本部署时，您应该能够从可用映射器列表中选择部署的脚本。
13.4.4. 对主题标识符映射器
默认情况下，主题声明 sub 默认在默认客户端范围 basic 中映射 Subject (sub) 协议映射器。
要使用协议映射器（如 Pairwise 主题标识符 ）使用适当的主题标识符，您可以从 基本 客户端范围中删除 Subject (sub) 协议映射器。但是，在对 主题标识符映射器之前执行 Subject (sub) 协议映射程序 并不严格要求，因此对值将覆盖 Subject 映射器添加的值。这是因为 Subject mapper 的优先级。因此，删除内置 Subject (sub) 映射器的唯一优点是，通过避免使用协议映射器（可能没有任何效果）来节省一些性能。
13.4.5. 使用轻量级访问令牌
红帽构建的 Keycloak 中的访问令牌包含敏感信息，包括个人 Identifiable 信息(PII)。因此，如果资源服务器不想向客户端等第三方实体披露此类信息，红帽构建的 Keycloak 支持从访问令牌中删除 PII 的轻量级访问令牌。另外，当资源服务器从访问令牌中删除了 PII 时，它可以通过将访问令牌发送到红帽构建的 Keycloak 令牌内省端点来获取 PII。
- 无法从轻量级访问令牌中删除的信息
-
协议映射程序可以控制哪些信息被放入访问令牌中，轻量级访问令牌使用协议映射程序。因此，无法从轻量级访问中删除以下信息。
exp,iat,jtis 是,typ,azp,sid,范围,cnf - 在红帽构建的 Keycloak 中使用轻量级访问令牌
-
通过将
use-lightweight-access-tokenexecutor 应用到客户端，客户端可以接收轻量级访问令牌而不是访问令牌。???轻量级访问令牌包含一个由协议映射程序控制的声明，其设置为Add to lightweight access token(default OFF)为 ON。另外，通过打开其在协议映射器的Add to token 内省功能，客户端可以通过将访问令牌发送到红帽构建的 Keycloak 令牌内省端点来获取声明。 - 内省端点
-
在某些情况下，使用 HTTP 标头
Accept: application/jwt而不是Accept: application/json触发令牌内省端点可能很有用，这对轻量级访问令牌特别有用。请参阅 安全 应用程序部分的 Token Introspection 端点 的详细信息。
