Jira server fails to synchronize with LDAP server with Unable to find the username of the principal error
Platform notice: Server and Data Center only. This article only applies to Atlassian products on the Server and Data Center platforms.
Support for Server* products ended on February 15th 2024. If you are running a Server product, you can visit the Atlassian Server end of support announcement to review your migration options.
*Except Fisheye and Crucible
Symptoms
JIRA fails to synchronize with LDAP server.
The following appears in the atlassian-jira.log:
2013-01-28 03:15:59,598 QuartzWorker-0 ERROR ServiceRunner [atlassian.crowd.directory.DbCachingDirectoryPoller] Error occurred while refreshing the cache for directory [ 10000 ].
com.atlassian.crowd.exception.OperationFailedException: java.util.concurrent.ExecutionException: com.atlassian.crowd.exception.OperationFailedException: org.springframework.ldap.UncategorizedLdapException: Unable to find the username of the principal.
at com.atlassian.crowd.directory.ldap.cache.UsnChangedCacheRefresher.synchroniseAllUsers(UsnChangedCacheRefresher.java:266)
at com.atlassian.crowd.directory.ldap.cache.AbstractCacheRefresher.synchroniseAll(AbstractCacheRefresher.java:40)
at com.atlassian.crowd.directory.ldap.cache.UsnChangedCacheRefresher.synchroniseAll(UsnChangedCacheRefresher.java:223)
at com.atlassian.crowd.directory.DbCachingRemoteDirectory.synchroniseCache(DbCachingRemoteDirectory.java:619)
at com.atlassian.crowd.manager.directory.DirectorySynchroniserImpl.synchronise(DirectorySynchroniserImpl.java:63)
at com.atlassian.crowd.directory.DbCachingDirectoryPoller.pollChanges(DbCachingDirectoryPoller.java:50)
at com.atlassian.crowd.manager.directory.monitor.poller.DirectoryPollerJob.execute(DirectoryPollerJob.java:34)
at org.quartz.core.JobRunShell.run(JobRunShell.java:195)
at com.atlassian.multitenant.quartz.MultiTenantThreadPool$MultiTenantRunnable.run(MultiTenantThreadPool.java:72)
at org.quartz.simpl.SimpleThreadPool$WorkerThread.run(SimpleThreadPool.java:520)
Caused by: java.util.concurrent.ExecutionException: com.atlassian.crowd.exception.OperationFailedException: org.springframework.ldap.UncategorizedLdapException: Unable to find the username of the principal.Cause
The User Name Attribute (ldap.user.username) specified in JIRA's LDAP connector (User Schema Settings) is not applicable for all or some users found in the LDAP filter specified.
For example, the attribute field used on the user object would be sAMAccountName for Active Directory Servers and if the value for this attribute is empty it will fail to properly map during synchronization, causing the above exception.
Workaround
Exclude user objects with the missing User Name Attribute with a LDAP search filter. See more here on How to write LDAP search filters.
Resolution
Add the missing User Name Attribute to the objects that are causing the LDAP synchronization to fail.
Please see our Troubleshooting LDAP User Management documentation for further assistance with diagnosing LDAP problems.