Keycloak 22.0.3升级后无法通过Admin API在LDAP中创建用户

问题现象 #

• 升级Keycloak至22.0.3并配置LDAP连接后，Admin API执行获取用户、角色、组操作均正常
• 创建用户操作失败，返回错误：

  { "errorMessage": "Could not create user" }
  

• 后台日志抛出根本错误：

  javax.naming.directory.InvalidAttributeValueException: [LDAP: error code 21 - 00000057: LdapErr: DSID-0C0910E6, comment: Error in attribute conversion operation, data 0, v3839]; remaining name 'cn=username,OU=User,OU=company,DC=domain,DC=at'
  

排查与解决步骤 #

1. 检查用户名的字符与长度限制 #

• 确认创建的用户名是否包含AD禁止的字符（如/ \ [ ] : ; | = , + * ? < >或空格）
• 验证AD对cn/sAMAccountName的长度限制：通常sAMAccountName最大20字符，cn最大64字符

2. 核对Keycloak LDAP属性映射 #

• 进入Keycloak控制台，导航到用户 Federation > 你的LDAP提供商 > Mappers
  • 确认username对应的LDAP属性是否正确（AD中建议映射到sAMAccountName而非cn，前者是登录名，后者是显示名）
  • 检查所有必填属性（如mail、givenName、sn）的映射关系，确保传入值符合AD属性要求

3. 验证AD属性约束 #

• 部分AD属性有隐性规则，比如userPrincipalName必须符合用户名@域名格式，若Keycloak自动生成的格式不符合会触发报错
• 通过AD属性编辑器查看目标用户OU下的属性模板，确认每个必填属性的允许值范围

4. 开启LDAP调试日志定位请求内容 #

• 在Keycloak配置文件中开启LDAP调试日志，查看实际发送给AD的请求细节：

  <!-- standalone.xml 示例配置 -->
  <logger category="org.keycloak.storage.ldap">
      <level name="DEBUG"/>
  </logger>
  <logger category="javax.naming">
      <level name="DEBUG"/>
  </logger>
  

• 通过日志对比Keycloak发送的属性值与AD的要求差异

5. 手动测试LDAP创建用户 #

• 使用LDAP客户端（如Apache Directory Studio、ldapmodify）执行手动创建请求，排除Keycloak的问题：

  dn: cn=testuser,OU=User,OU=company,DC=domain,DC=at
  objectClass: top
  objectClass: person
  objectClass: organizationalPerson
  objectClass: user
  cn: testuser
  sAMAccountName: testuser
  givenName: Test
  sn: User
  userPrincipalName: testuser@domain.at
  

• 若手动创建失败，说明是AD配置问题；若成功，则需调整Keycloak的属性映射或请求格式

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