Keycloak如何配置Identity Provider返回空值时默认填充姓名属性

完全可以通过内置的Identity Provider Mapper规则实现需求，配置完成后IDP返回空值时会自动填充默认值，不会触发信息补全表单弹出，不需要开发自定义扩展。

标准配置流程（Keycloak 18+ 版本适用） #

1. 进入对应Realm的管理控制台，左侧菜单栏选择「Identity Providers」，点击需要配置的身份源（如Google连接），切换到「Mappers」配置页
2. 分别创建First name、Last name的映射规则，配置逻辑如下：

• 处理Last name自动填充：
  • 点击「Add mapper」，Mapper类型选择Last Name
  • Claim name填写身份源返回姓对应的字段标识，Google身份源对应字段为family_name
  • 在「Default value」输入框填入默认值Doe
  • Sync Mode保持默认inherit即可
• 处理First name默认值（按需配置）：
  • 新建Mapper，类型选择First Name
  • Claim name填写身份源返回名字对应的字段标识，Google身份源对应字段为given_name
  • 在「Default value」输入框填入你需要的First name默认值
  • Sync Mode保持默认inherit

Keycloak弹出信息补全表单的核心触发条件，是用户必填基础属性（First name、Last name属于默认必填项）在身份同步流程结束后仍为空。上述配置的Mapper会在IDP返回对应字段为null/空字符串时自动写入默认值，同步完成后所有必填字段均有有效值，自然不会弹出补全表单。如果IDP返回了有效的字段值，Mapper会优先使用IDP返回的内容，不会强制覆盖成默认值。

低版本兼容方案（Keycloak 18以下版本） #

如果当前使用的版本Mapper配置中没有默认值输入项，可以选择Script Mapper类型，通过简单脚本实现空值判断填充，以Last name配置为例：

• 新建Mapper时类型选择Script Mapper
• 在脚本编辑区填入以下逻辑：

// 提取IDP返回的姓字段，空值时填充Doe
const familyName = identityProviderContext.getToken().getOtherClaims().get("family_name");
if (familyName == null || familyName.trim().length === 0) {
    user.setLastName("Doe");
} else {
    user.setLastName(familyName);
}

• First name的脚本逻辑完全一致，替换对应字段名、默认值即可。

验证注意事项 #

• 配置完成后建议使用无痕窗口测试：选择一个未在当前Keycloak实例绑定过、Last name为空的Google账号走登录流程，确认不会跳转信息补全页，登录成功后查看用户详情，确认Last name字段已自动填充为Doe
• 如果之前测试过对应用户登录，需要先在「Users」菜单中删除该用户的IDP绑定关系，否则会走存量用户更新逻辑，无法验证首次导入时的字段填充效果
• 不要直接使用Hardcoded类型的Mapper硬编码姓名字段，该类型Mapper会无视IDP返回的所有值，强制把字段设为固定值，不符合正常场景下优先使用IDP返回值的需求

内容的提问来源于stack exchange，提问作者thathashd