Troubleshooting LDAP User Management
範囲
This page describes troubleshooting LDAP user management configurations and setup in JIRA Software. Note other specific documents:
ページ | 説明 |
---|---|
Troubleshooting User Management Upgrade Issues | Describes user management issues encountered during an upgrade to JIRA 4.3.x or later. |
LDAP ディレクトリへの接続 | Atlassian'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.
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.
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.
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.
トラブルシューティング
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:
- Server Connectivity: the application is able to communicate with the LDAP/AD server.
- Uses Hostname and Port.
- 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.
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
Linux
Common LDAP Errors
These are a list of errors returned from Directory Studio and Embedded Crowd that can help identify configuration issues with the LDAP/AD server.
エラー | Possible 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 ( | The port number specified for the LDAP/AD server is incorrect or a firewall/network configuration is blocking the connection. |
Unknown Host: ldap-host | The LDAP/AD server name/IP specified is incorrect. |
| 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 3 | The 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 4 | The 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 34 | The DN is most likely incorrect - confirm this by checking it against Directory Studio or using dsquery if using Active Directory. |
LDAP: error code 48 | The Authentication Method in the Authentication tab of the connector properties is incorrect. |
LDAP: error code 32 | LDAP_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:
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. |
NoSuchAttributeException | This 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. |
AuthenticationException | Could 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
問題 | Possible Cause(s) | Possible Fix |
---|---|---|
| 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:
|
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.
| 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:
|
Users and Groups are imported, however Users aren't automatically added to the Groups they belong to. | The Membership Schema Settings may be 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:
|
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
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,
- Highlight the user or group in Apache Directory Studio.
- Right-click on the user or group.
- Choose Export -> LDIF Export.
Screenshot: Generating an LDIF export of a user in Apache Directory Studio
関連トピック
Creating a Connection to your LDAP Directory
Using Apache Directory Studio for LDAP Configuration