7.5. RoleMappingsProvider 元素

红帽 Keycloak 的构建包括 RoleMappingsProvider 实现，它使用 属性文件 执行角色映射。此提供程序由 基于 id 属性的-role-mapper 标识，由 org.keycloak.adapters.saml.PropertiesBasedRoleMapper 类实现。

此提供程序依赖于两个配置属性，它们可以用来指定要使用的 属性 文件的位置。首先，它会检查 properties.file.location 是否被设置，使用配置的值来查找文件系统中的 properties 文件。如果配置的文件不位于，则提供程序会抛出 RuntimeException。以下片段演示了使用 properties.file.configuration 选项从文件系统中 /opt/mappers/ 目录中加载 roles.properties 文件的 provider 示例：

    <RoleMappingsProvider id="properties-based-role-mapper">
        <Property name="properties.file.location" value="/opt/mappers/roles.properties"/>
    </RoleMappingsProvider>

    <RoleMappingsProvider id="properties-based-role-mapper">
        <Property name="properties.file.location" value="/opt/mappers/roles.properties"/>
    </RoleMappingsProvider>

如果没有设置 properties.file.location，则供应商会检查 properties.resource.location 属性，使用配置的值来从 WAR 资源中加载 properties 文件。如果这个配置属性也不存在，则供应商默认尝试从 /WEB-INF/role-mappings.properties 中加载文件。无法从资源加载文件将导致提供程序抛出 RuntimeException。以下片段演示了使用 properties.resource.location 从应用程序的 /WEB-INF/conf/ 目录中加载 roles.properties 文件的供应商示例：

    <RoleMappingsProvider id="properties-based-role-mapper">
        <Property name="properties.resource.location" value="/WEB-INF/conf/roles.properties"/>
    </RoleMappingsProvider>

    <RoleMappingsProvider id="properties-based-role-mapper">
        <Property name="properties.resource.location" value="/WEB-INF/conf/roles.properties"/>
    </RoleMappingsProvider>

属性文件 可以包含角色和主体作为键，以及以逗号分隔为值的零个或多个角色的列表。调用时，实施将迭代从断言提取和检查各个角色的一组角色（如果存在映射）。如果角色映射到空角色，它将被丢弃。如果它映射到一个或多个不同角色的集合，则会在结果集中设置这些角色。如果没有为角色找到映射，则会包含在结果集中。

处理角色后，实施将检查从断言中提取的主体是否包含条目 属性文件。如果存在主体的映射，则所有作为值列出的角色都会添加到结果集中。这允许将额外的角色分配给主体。

例如，假设供应商已使用以下属性文件配置：

roleA=roleX,roleY
roleB=

kc_user=roleZ

roleA=roleX,roleY
roleB=

kc_user=roleZ

如果从断言中提取了主体 kc_user，使用 roleA、roleB 和 roleC，则分配给主体的最终角色集合为 roleC、roleX、roleY 和 roleZ，因为 roleA 被映射到 roleX 和 roleY，roleB 被映射到空角色 - 因此被丢弃，因此 roleC 将用作 roleC，最后添加到 kc_user _user 主体。

注： 要在角色名称中使用空格进行映射，请对空间使用 unicode 替换。例如，传入的 'role A' 显示为：

role\u0020A=roleX,roleY

role\u0020A=roleX,roleY