Data Center 3.1
Versions

Troubleshooting LDAP User Management

Troubleshooting

On this page

Related content

  • No related content found

Still need help?

The Atlassian Community is here for you.

Ask the community

Scope

This page describes troubleshooting LDAP user management configurations and setup in JIRA Software. Note other specific documents:

PageDescription
Troubleshooting User Management Upgrade Issues Describes user management issues encountered during an upgrade to JIRA 4.3.x or later.
Connecting to an LDAP DirectoryAtlassian's primary documentation on LDAP Directory configuration.

 

About Apache Directory Studio

Apache Directory Studio is an open source project of the Apache Software Foundation. It includes an LDAP browser/editor, a schema browser, an LDIF editor, a DSML editor and more. It is a highly useful tool for troubleshooting integration problems with JIRA Software and Confluence. It is an Eclipse RCP application that is cross-platform or run within Eclipse itself as a plugin. For more information on Eclipse, please refer to the Wikipedia article on Eclipse Software.

We recommend using it for testing as a method of isolating where the problem with an integration exists. It allows you to test if an application other than JIRA Software or Confluence can connect to the LDAP/AD server. If a successful connection cannot be established it can indicate problems on the side of the directory, if it can connect it can indicate problems with the configuration of JIRA Software or Confluence.

On this page:

Installation and Set Up

It is recommended to install Directory Studio on a computer other than the server that hosts the LDAP/AD server (a local workstation is usually best). Directory Studio is able to connect to the directory using the LDAP protocol and display the contents of the directory using its built-in browser. To establish the connection, please refer to the Create connection section in the Directory Studio user guide.

(minus) If Directory Studio is unable to initiate a connection it can indicate there is a problem with the LDAP/AD server connection. Refer to the troubleshooting section below.

Browsing the Directory

Using the Browser functionality in Directory Studio you can navigate through the Directory tree to see where users and groups are stored. It will also allow you to identify how data is stored within the directory, including the names of attributes and specific values.

Expand to see an example

This is a comparison between the Active Directory and Apache Directory Studio. Below is Active Directory:

And this is how it would look in Directory Studio:

As can be seen from the above example, Directory Studio is very useful for identifying which attributes to use when setting the Schema Settings and User Schema Settings as described in Connecting to an LDAP Directory as it shows the names and values of the attributes in an clear, readable format.

Directory Attributes

LDAP uses a schema (DIT) to define how it stores data. These are much like a database - an attribute holds a value just like a field within a table.

Expand to see a list of common directory attributes

Common attributes:

Attribute DescriptionAttribute Value
DITDirectory Information Tree
DCDomain Controller
DNDistinguished Name
CNCommon Name
SNSurname
OUOrganizational Unit
UIDUnique ID

Example of an LDAP/AD tree for the Administrator user:

  • Domain Controller: ad01,crowd,atlassian,com
    • Common Name: Users
      • Common Name: Administrator

Distinguished Name: CN=Administrator,CN=Users,DC=ad01,DC=crowd,DC=atlassian,DC=com

Go to DN

The Go to DN is essentially a search option that allows you to find an LDAP element easily. It can be accessed through the context menu in the LDAP Browser (right click). It is useful for quickly finding Distinguished Names that would relate to configuration settings, such as Base DN, Additional User DN or Additional Group DN.

Expand to see an example

Troubleshooting

Prior to troubleshooting, please ensure that you have verified the following credentials of the LDAP/AD server with your System Administrator. If they are not correct, you will not be able to successfully connect or bind to the LDAP/AD server.

  • Server Hostname (or IP).
  • Server Port.
  • Bind Username (DN).

  • Bind Password.

 A successful connection requires the following two steps:

  1. Server Connectivity: the application is able to communicate with the LDAP/AD server.
    • Uses Hostname and Port.
  2. LDAP/AD Bind: the application is able to log into the directory.
    • Uses Bind Username & Password.

Identify Active Directory DNs

If using Active Directory, the dsquery command can be executed on the command-line to identify DNs to particular objects, as per this Dsquery Windows Server article. Please refer to the examples below for further information.

Expand to see an example of how to locate the full DNs

Access the command line and execute the following to identify the DN for a user:

C:\>dsquery user -name Administrator
"CN=Administrator,CN=Users,DC=sydney,DC=atlassian,DC=com"

In the above example, this breaks down to:

  • Domain Controller: sydney,atlassian,com
    • Common Name: Users
      • Common Name: Administrator

The following can then be used to identify the DN for any groups:

C:\>dsquery group -name jira-administrators
"CN=jira-administrators,OU=Groups,DC=sydney,DC=atlassian,DC=com"

In the above example, this breaks down to:

  • Domain Controller: sydney,atlassian,com
    • Organizational Unit: Groups
      • Common Name: jira-administrators

Using the the above results, when entering the configuration for an Active Directory Connector in JIRA Software, the following DNs would be used:

ConfigurationParameter
Base DN
DC=sydney,DC=atlassian,DC=com
Additional User DN
CN=Users
Additional Group DN 
OU=Groups

The above settings would synchronize all users in CN=Users,DC=sydney,DC=atlassian,DC=com and all groups in OU=Groups,DC=sydney,DC=atlassian,DC=com.

Testing the LDAP/AD Server Connectivity

If any of the below tests fail it indicates there is most likely a problem with the LDAP/AD Server or the port/IP is not correct. Troubleshooting those problems is outside of the scope of this document.

Testing the LDAP/AD Bind is done through Directory Studio.

Windows

Expand to see Windows instructions

Test that the server is reachable by pinging it.

C:\>ping -n 1 ldap-host
Pinging ldap-host.example.com [192.168.1.100] with 32 bytes of data:
Reply from 192.168.1.100: bytes=32 time=4ms TTL=127
Ping statistics for 172.20.4.167:
    Packets: Sent = 1, Received = 1, Lost = 0 (0% loss),
Approximate round trip times in milli-seconds:
    Minimum = 4ms, Maximum = 4ms, Average = 4ms

Check that the port is open (typically 389). A successful connection to the port indicates it is open. If a successful connection is made, the screen will go blank. If not, the below message will be generated. To exit telnet, use CTRL+C.

C:\>telnet ldap-host 389
Connecting To ldap-host...Could not open connection to the host, on port 389: Connect failed

Linux

Expand to see Linux instructions

Test that the server is reachable by pinging it.

$ ping -c1 ldap-host
PING ldap-host (192.168.1.100): 56 data bytes
64 bytes from 192.168.1.100: icmp_seq=0 ttl=127 time=0.521 ms
 
--- crowd-ad1 ping statistics ---
1 packets transmitted, 1 packets received, 0.0% packet loss
round-trip min/avg/max/stddev = 0.521/0.521/0.521/0.000 ms

Check that the port is open (typically 389). A successful connection to the port indicates it is open. To exit telnet, use CTRL+C.

$ telnet ldap-host 389
Trying 192.168.1.100...
Connected to crowd-ad1.
Escape character is '^]'.

Common LDAP Errors

Expand to see an example error from Directory Studio

 

These are a list of errors returned from Directory Studio and Embedded Crowd that can help identify configuration issues with the LDAP/AD server.

ErrorPossible Cause(s)
simple bind failed: ldap-host:389

This is a very general error, and it means something went wrong when trying to bind to LDAP/AD. Check to see if the LDAP/AD server name and/or port number you have specified is incorrect or an incorrect DN was specified as the administrator username.

It could also indicate the Encryption method was specified incorrectly in the Network Parameter tab of the connector properties in Directory Studio.

Connection refused (ldap-host:389)
No connection

The port number specified for the LDAP/AD server is incorrect or a firewall/network configuration is blocking the connection.

Unknown Host: ldap-host
No connection

The LDAP/AD server name/IP specified is incorrect.
  • LDAP: error code 2
  • InvalidSearchFilterException

Invalid search filter passed to the LDAP/AD server or the filter is malformed (e.g.: it's missing a open and closing of parenthesis).

Please refer to this LDAP Query Basics Microsoft TechNet article for further information on LDAP/AD queries.

LDAP: error code 3The application is timing out when waiting on a response from LDAP. Check the LDAP filters are correct, the LDAP engine is working correctly. The default timeout can be increased in the configuration.
LDAP: error code 4The Active Directory/LDAP Server that JIRA Software is synchronizing with has a limitation on the number of objects it can return with one query. Enable 'Use Paged Results'.
LDAP: error code 34The DN is most likely incorrect - confirm this by checking it against Directory Studio or using dsquery if using Active Directory.
LDAP: error code 48The Authentication Method in the Authentication tab of the connector properties is incorrect.
LDAP: error code 32LDAP_NO_SUCH_OBJECT  - Indicates the target object cannot be found. This code is not returned on following operations: Search operations that find the search base but cannot find any entries that match the search filter. Bind operations.

LDAP: error code 49

The Bind Username (DN) or Password is incorrect. This could also be caused by the following:

  • Pointed to non-user DN.
  • Pointed to a non-existent DN.
  • Pointed to an incorrect admin DN (might be using UID instead of CN).
  • Pointed to a non administrator user.
  • Pointed to a valid administrator user, however the password is incorrect.

A DN describes a path to the object in the database, so the CN may be correct however the OUs and DCs in the DN specified may be incorrect or in the wrong order.

NoSuchAttributeExceptionThis can be caused by providing a name for an attribute that is not correct or does not exist.
InvalidNameException

This can be caused by a bad prefix specified in the Settings tab on most LDAP/AD systems.

This could mean you did not specify a prefix at all, which means the LDAP/AD server did not receive a full DN from CPS or that you did not specify a correct prefix, such as CN instead of UID, which results in the LDAP/AD server not receiving a correct DN from CPS.

Can also be caused by a missing comma at the beginning of the suffix or an extra comma at the end of the suffix. This error could also mean the authentication type is incorrect. 

AuthenticationExceptionCould not authenticate the user trying to login. This can be the result of an incorrect username or password or an incorrect prefix and/or suffix specified in the Settings tab, depending on the type of LDAP/AD system. Could also mean the authentication type is incorrect. 

Common Configuration Problems

ProblemPossible Cause(s)Possible Fix
  • JIRA Software runs out of memory, experiences slow performance or high CPU load during User Directory sync.
  • Users are imported, however groups are not.
  • Groups are imported, however users are not.
The Schema Settings may be incorrect causing JIRA Software to attempt to import unnecessary or incorrect data from the LDAP/AD server.

Verify by browsing with Directory Studio (using 'Go to DN' is recommended) and ensure the following settings are correct within the Schema Settings in JIRA Software:

  • Base DN 
  • Additional User DN
  • Additional Group DN
User details (e.g.: Username, Email, Full Name, Password) are not correct after a successful sync.

The User Schema Settings may be incorrect or the value within the attributes is incorrect.

  • If this applies to only one user, it is likely the user details are incorrect.
  • If it applies to multiple, it is likely the JIRA Software configuration is incorrect.

Verify by browsing with Directory Studio (using 'Go to DN' is recommended) and ensure the following attributes are correct within the User Schema Settings in JIRA Software:

  • User Name
  • User First Name
  • User Last Name
  • User Display Name
  • User Email
Users and Groups are imported, however Users aren't automatically added to the Groups they belong to.

The Membership Schema Settings may be incorrect.

  • If this applies to only one user, it is likely the user details are incorrect.
  • If it applies to multiple, it is likely the JIRA Software configuration is incorrect.

 

Verify by browsing with Directory Studio (check with a sample user) and ensure the following attributes are correct within the Membership Schema Settings in JIRA Software:

  • Group Members Attribute 
  • User Membership Attribute
Unable to add/delete Users or make changes to their Groups, Project Roles or Edit them.The LDAP/AD User Directory is set to Read Only.

Verify the Permissions Settings are correct for the external User Directory.

If you want to make changes, Read/Write will need to be activated. If using Active Directory, please refer to this page on Configuring an SSL Certificate.

Providing Additional Information

Often when the above troubleshooting steps don't resolve the problem and in particularly complicated scenarios, further information will need to be provided so Atlassian can investigate further.

Generating an LDIF Export of a User or Group

Occasionally, Atlassian Crowd Support may request an LDIF export of a user or group. LDIF is the LDAP Data Interchange Format. You can export all or part of your LDAP directory to an LDIF file. This page shows you how to do that when using Apache Directory Studio.

LDAP browser Apache Directory Studio may convert the underlying value data automatically which could mask the real value. An LDIF will show the actual value that's being used.

To generate an LDIF export of a user or group,

  1. Highlight the user or group in Apache Directory Studio.
  2. Right-click on the user or group.
  3. Choose Export -> LDIF Export.

Screenshot: Generating an LDIF export of a user in Apache Directory Studio

RELATED TOPICS

Creating a Connection to your LDAP Directory
Using Apache Directory Studio for LDAP Configuration

Last modified on Jul 8, 2022

Was this helpful?

Yes
No
Provide feedback about this article

Related content

  • No related content found
Powered by Confluence and Scroll Viewport.