Documentation for JIRA 4.0. Documentation for other versions of JIRA is available too.

Skip to end of metadata
Go to start of metadata

Many organisations have an LDAP directory acting as a centralised database of system users. JIRA is able to authenticate users against their LDAP password.

On this page:

About JIRA's LDAP Integration

In JIRA, user management is handled by OSUser, a pluggable user management framework. OSUser is configured through the WEB-INF/classes/osuser.xml file.

Caveats

Only password-checking for LDAP users is done in JIRA

The main point to realise is that user profiles are still managed in JIRA (the OFBizProfileProvider in osuser.xml). Only the password lookup is done against LDAP, and only if the JIRA username coincides with a LDAP username.

If the username is not found in LDAP, then the local JIRA credentials will be used.

(Technically, this behaviour is due to credentials (password) checking being a separate operation to user-profile lookups. The profile can be loaded from the JIRA database, but the password looked up from LDAP. Furthermore, multiple credentials providers can be specified (here, LDAP and OSUser), and if one fails, the other will be used. This allows non-LDAP users to log in with their JIRA password.)

Not all LDAP users have JIRA access

Another effect of this implementation is that LDAP users do not automatically have access to JIRA. A JIRA account must be created for each user wishing to use JIRA. You can bulk-create users from LDAP with this LDAP user importer.

This is because each JIRA user has a set of groups (for example, 'jira-users') stored in their profile. Without an associated group, that user can do nothing; not even browse JIRA (they lack the 'use' permission).

Thus, for an LDAP user to be able to use JIRA, a JIRA administrator must create an account for them, and assign them to a group (typically 'jira-user'). The password in this JIRA account will be ignored, as the LDAP password will override it.

Planned Improvements

In future, we plan to more tightly integrate LDAP into JIRA, so that LDAP groups can be mapped to JIRA groups, and user management can be fully externalised (see Plans for JIRA's LDAP integration ). We'd like feedback as we go further with this; please see this issue report for current status, and add your use-case as a comment. Thanks!

Atlassian Crowd

Atlassian Crowd is Atlassian's single sign-on product. Crowd provides an interface for managing users and groups, and provides an OSUser implementation that allows JIRA to fully delegate users and groups to Crowd, and hence LDAP. Thus while we still plan to develop tighter JIRA-LDAP integration, purchasers of Crowd can achieve this right now by using Crowd as an intermediary. See Crowd's JIRA integration documentation for details.

Step 1. Configuring LDAP Integration

JIRA contains a configuration utility which lets you auto-generate a valid osuser.xml file. This can be accessed from Admin -> System -> LDAP:

Step 2. Disabling JIRA's Password Management

Once you have LDAP-based password checking working, you should go to Admin -> General Configuration, and turn on External password management (see Configuring JIRA documentation). This will disable the "change my password" links in the JIRA interface, ensuring that passwords are now only managed via LDAP.

Configuration Notes

LDAP over SSL

With plain LDAP, passwords may be passing over the network unencrypted, which (depending on your network security) may be a security problem. If you wish to connect to LDAP over SSL, see the Connecting to SSL services guide for details on how to import the SSL server's public key. In osuser.xml, you would need to use ldaps:// in the URL if you have port 636 dedicated to LDAP over SSL.

Multiple LDAP trees (eg. ActiveDirectory domains)

If you wish to authenticate users from multiple LDAP directories or different trees in the same directory, simply edit the OSUser file and add a LDAPCredentialsProvider section for each (see 'Configuring LDAP Integration' above). JIRA will query them in order, and the first one containing the requested user will be used for password checking. As soon as a user is found, the password is checked and no further processing is done (i.e. only one password will work).

If you have more than one LDAPCredentialsProvider it is a good idea to give each a unique providerName attribute for debugging purposes.

ActiveDirectory users note: a better approach to searching multiple trees is to set up an Active Directory Global Catalog. This is an AD instance which mirrors records in other instances. Searching the Global Catalog is thus equivalent to searching all mirrored LDAP directories. This is faster and more reliable than JIRA's LDAP fallback.

If you have a Global Catalog set up, it can be searched via LDAP on port 3268 (eg. ldap://adserver:3268) or 3269 for SSL (eg. ldaps://adserver:3269). See this guide for more information.

LDAP on Linux

See these notes on how to set up a LDAP directory on a Linux server for use with JIRA.

Debugging

Cannot create osuser.xml file via JIRA LDAP Configurer

To see exactly why the JIRA LDAP Configurer is failing, follow these steps:

  1. Log in as a user with the 'JIRA System Administrators' global permission.
  2. Bring up the administration page by clicking either the 'Administration' link on the top bar or the title of the Administration box on the dashboard.
  3. Under the 'System' sub-menu in the left-hand navigation column, click the 'Logging & Profiling' link.
  4. The 'Logging & Profiling' page will display. Click the 'Edit' link next to 'com.atlassian.jira.web.action.util.LDAPConfigurer'
  5. Change the logging level to 'DEBUG', then click 'Update'. This temporarily turns up logging for the JIRA LDAP Configurer.
  6. When you next try to submit your LDAP server details via the JIRA LDAP Configurer, you should see extra logs on stdout.

Cannot authenticate against LDAP password

If JIRA does not authenticate against the LDAP password, then something is probably wrong with your setup. First, ensure that the user you are trying to connect as has a JIRA account (see above). Make sure you have the LDAP connection details correct (basename, uid, username/password). These details are best discovered with the help of an LDAP browser such as Apache Directory Studio or JXplorer.

To see exactly why LDAP authentication is failing, follow these steps:

  1. Edit log4j.properties (instructions), and add the following lines:
    Restart JIRA to apply your change. This change will turn up logging for the LDAP authentication module.
  2. When next trying to log in, you should see extra logs on stdout. A successful authentication looks like this:
    This log was generated with the following to osuser.xml:
  3. If you have problems, try emulating the operations performed by the LDAP authentication provider. The LDAP authentication provider works by first doing an search for the specified username, searching from base searchBase, using query uidSearchName = username, authenticating using the principal and credentials properties if present, or doing an anonymous search otherwise. If an entry is found, it then tries to log in to LDAP using the specified matching username and specified password.
Icon

If you get an error message javax.naming.PartialResultException: Unprocessed Continuation Reference(s), try adding <property name="java.naming.referral">follow</property> to the LDAPCredentialsProvider section.