切换至Keycloak后UserPrincipal.getName显示UUID而非LDAP uid问题咨询

这个问题在LDAP转Keycloak的迁移场景里非常普遍，核心原因是Keycloak默认用UUID作为用户的唯一标识（subject），而LDAP则是用uid作为用户名。下面是几个可行的解决方向：

1. 调整Keycloak客户端配置，让Principal返回原LDAP uid #

这是最直接的方案，不需要修改代码，只需要配置Keycloak的客户端适配器：

• 如果你用的是OIDC客户端（比如Spring Boot/Java EE应用），在客户端的配置文件（比如keycloak.json或者Spring Boot的application.properties）里添加/修改配置：

  # Spring Boot示例
  keycloak.principal-attribute=username
  

  或者在Keycloak控制台的客户端设置中，找到“Advanced”标签，在“Principal Attribute”字段填入username（这个字段对应同步过来的LDAP uid）。这样UserPrincipal.getName()就会返回用户的username，也就是原来的LDAP uid。
• 如果是SAML客户端，在Keycloak控制台的客户端SAML配置里，修改“Name ID Format”为合适的格式（比如urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified），然后设置“Name ID Template”为${username}，让SAML断言的NameID使用原uid。

2. 修改应用代码，获取正确的用户标识 #

如果不想动Keycloak配置，可以在代码里直接获取Keycloak用户的username属性：

// 从HttpServletRequest中获取Keycloak用户上下文
KeycloakPrincipal<KeycloakSecurityContext> kcPrincipal = 
    (KeycloakPrincipal<KeycloakSecurityContext>) request.getUserPrincipal();
// 获取同步过来的LDAP uid（对应Keycloak的username字段）
String originalUid = kcPrincipal.getKeycloakSecurityContext().getToken().getPreferredUsername();
// 或者直接获取username属性
String originalUid = kcPrincipal.getKeycloakSecurityContext().getToken().getUsername();

把原来调用UserPrincipal.getName()的地方替换成上面的逻辑即可。

3. 检查LDAP用户同步的属性映射 #

确保从LDAP同步到Keycloak时，uid已经正确映射到Keycloak的username字段：

• 登录Keycloak控制台，进入“User Federation”，找到你的LDAP提供商
• 切换到“Mappers”标签，检查是否存在一个LDAP Attribute Mapper，将LDAP的uid属性映射到Keycloak用户的username属性
• 如果没有，点击“Create”新建一个：设置Mapper Type为LDAP Attribute，LDAP Attribute填uid，User Model Attribute填username，保存后重新同步用户，这样Keycloak用户的username就会和原LDAP uid一致。

4. 自定义Keycloak的Principal生成逻辑（进阶方案） #

如果以上方案都不满足需求，可以通过Keycloak的SPI扩展自定义Principal的生成逻辑，比如编写一个自定义的OIDC/SAML适配器，让Principal的name返回指定的用户属性。不过这个方案需要开发Keycloak扩展，适合有定制化需求的场景。

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