JIRA 4.0 : Integrating JIRA with LDAP
This page last changed on Oct 01, 2009 by alui.
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 IntegrationIn JIRA, user management is handled by OSUser, a pluggable user management framework. OSUser is configured through the WEB-INF/classes/osuser.xml file. CaveatsOnly password-checking for LDAP users is done in JIRAThe 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 accessAnother 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 ImprovementsIn 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 CrowdAtlassian 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 IntegrationJIRA 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 ManagementOnce 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 NotesLDAP over SSLWith 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 LinuxSee these notes on how to set up a LDAP directory on a Linux server for use with JIRA. DebuggingCannot create osuser.xml file via JIRA LDAP ConfigurerTo see exactly why the JIRA LDAP Configurer is failing, follow these steps:
Cannot authenticate against LDAP passwordIf 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:
|
![]() |
Document generated by Confluence on Oct 06, 2009 00:25 |