Keycloak集成SAML IdP时，如何将NameID值映射到用户属性

核心思路 #

由于你的属性是嵌入在SAML断言的<saml2:NameID>节点中（而非标准<saml2:Attribute>节点），默认的Attribute Importer无法直接解析这类内容。需要通过两步映射实现：先捕获完整的NameID值，再用脚本拆分键值对并映射到用户属性。

步骤1：添加NameID映射器捕获完整值 #

1. 进入Keycloak后台，找到目标SAML身份提供商（IdP）的配置页面，切换到「Mappers」标签页
2. 点击「Create」，选择NameID类型，配置如下：
   • Name：自定义名称（如Capture X509 NameID）
   • Mapper Type：NameID
   • NameID Policy Format：选择urn:oasis:names:tc:SAML:1.1:nameid-format:X509SubjectName
   • User Attribute Name：填写临时存储用的属性名（如x509_full_nameid）
3. 保存该映射器

步骤2：添加脚本映射器拆分并映射属性 #

1. 同样在IdP的「Mappers」页面，点击「Create」，选择Script Mapper类型
2. 配置参数：
   • Name：自定义名称（如Parse X509 NameID Attributes）
   • Mapper Type：Script Mapper
   • Script Type：选择Attribute Importer Script
3. 粘贴以下脚本（可根据需求调整映射规则）：

// 获取临时存储的完整X509 NameID字符串
const fullNameId = user.getAttribute('x509_full_nameid');
if (fullNameId) {
    // 拆分逗号分隔的键值对，去除多余空格
    const attributePairs = fullNameId.split(',').map(item => item.trim());
    attributePairs.forEach(pair => {
        const [key, value] = pair.split('=', 2);
        if (key && value) {
            // 根据键名映射到对应用户属性/内置字段
            switch(key.toUpperCase()) {
                case 'SERIALNUMBER':
                    user.setAttribute('serialNumber', value);
                    break;
                case 'GIVENNAME':
                    user.setFirstName(value); // 映射到Keycloak内置名字字段
                    break;
                case 'SURNAME':
                    user.setLastName(value); // 映射到Keycloak内置姓氏字段
                    break;
                case 'CN':
                    user.setAttribute('commonName', value);
                    break;
                case 'C':
                    user.setAttribute('country', value);
                    break;
                case 'T':
                    user.setAttribute('personType', value);
                    break;
                // 可添加更多键的映射规则
            }
        }
    });
}

4. 保存映射器

关键说明 #

• 你之前尝试的Attribute Importer仅能解析SAML断言中的标准<saml2:Attribute>节点，无法读取NameID内的内容，因此无效。
• 脚本中可直接将属性映射到Keycloak内置字段（如firstName/lastName）或自定义用户属性，按需调整即可。
• 测试时可开启Keycloak的org.keycloak.broker.saml调试日志，验证NameID捕获和脚本执行情况。

内容的提问来源于stack exchange，提问作者Jack L.