You can connect your JIRA application to an LDAP directory for authentication, user and group management.
OverviewAn LDAP directory is a collection of data about users and groups. LDAP (Lightweight Directory Access Protocol) is an Internet protocol that web applications can use to look up information about those users and groups from the LDAP server.
We provide built-in connectors for the most popular LDAP directory servers:
- Microsoft Active Directory
- Apache Directory Server (ApacheDS)
- Apple Open Directory
- Fedora Directory Server
- Novell eDirectory
- OpenLDAP Using Posix Schema
- Posix Schema for LDAP
- Sun Directory Server Enterprise Edition (DSEE)
- A generic LDAP directory server
When to use this option: Connecting to an LDAP directory server is useful if your users and groups are stored in a corporate directory. When configuring the directory, you can choose to make it read only, read only with local groups, or read/write. If you choose read/write, any changes made to user and group information in the application will also update the LDAP directory.
Connecting to an LDAP Directory in JIRA
To connect JIRA to an LDAP directory:
- Log in as a user with the 'JIRA System Administrators' global permission.
- Choose > User Management > User Directories.
Keyboard shortcut: 'g' + 'g' + start typing 'directories'.
- Add a directory and select one of these types:
- 'Microsoft Active Directory' – This option provides a quick way to select AD, because it is the most popular LDAP directory type.
- 'LDAP' – You will be able to choose a specific LDAP directory type on the next screen.
- Enter the values for the settings, as described below.
- Save the directory settings.
- Define the directory order by clicking the blue up- and down-arrows next to each directory on the 'User Directories' screen. Here is a summary of how the directory order affects the processing:
- The order of the directories is the order in which they will be searched for users and groups.
- Changes to users and groups will be made only in the first directory where the application has permission to make changes.
- For this configuration, every time user logs in (i.e. first and subsequent times), the user's data in JIRA will be updated from the user's data in LDAP. This includes username, display name, email and group memberships. However for group memberships, only the following applies:
- direct groups only (i.e. not nested groups) are synchronised from LDAP.
- only groups that are already present in JIRA are synchronised, i.e. groups are not added/removed, and group hierarchies are not synchronised.
Enter a meaningful name to help you identify the LDAP directory server. Examples:
Select the type of LDAP directory that you will connect to. If you are adding a new LDAP connection, the value you select here will determine the default values for many of the options on the rest of screen. Examples:
The host name of your directory server. Examples:
The port on which your directory server is listening. Examples:
Check this if the connection to the directory server is an SSL (Secure Sockets Layer) connection. Note that you will need to configure an SSL certificate in order to use this setting.
The distinguished name of the user that the application will use when connecting to the directory server. Examples:
Ensure that this is an administrator user for the LDAP engine. For example, in Active Directory the user will need to be a member of the built-in Administrators group.
The password of the user specified above.
Note: Connecting to an LDAP server requires that this application log in to the server with the username and password configured here. As a result, this password cannot be one-way hashed - it must be recoverable in the context of this application. The password is currently stored in the database in plain text without obfuscation. To guarantee its security, you need to ensure that other processes do not have OS-level read permissions for this application's database or configuration files.
The root distinguished name (DN) to use when running queries against the directory server. Examples:
Additional User DN
This value is used in addition to the base DN when searching and loading users. If no value is supplied, the subtree search will start from the base DN. Example:
Additional Group DN
This value is used in addition to the base DN when searching and loading groups. If no value is supplied, the subtree search will start from the base DN. Example:
Note: You can only assign LDAP users to local groups when 'External Management User Management' is not selected.
LDAP users, groups and memberships are retrieved from your directory server and can only be modified via your directory server. You cannot modify LDAP users, groups or memberships via the application administration screens.
Read Only, with Local Groups
LDAP users, groups and memberships are retrieved from your directory server and can only be modified via your directory server. You cannot modify LDAP users, groups or memberships via the application administration screens. However, you can add groups to the internal directory and add LDAP users to those groups.
Note for Confluence users: Users from LDAP are added to groups maintained in Confluence's internal directory the first time they log in. This is only done once per user. There is a known issue with Read Only, with Local Groups in Confluence that may apply to you. See CONF-28621 - User Loses all Local Group Memberships If LDAP Sync is Unable to find the User, but the User appears again in subsequent syncs Open
LDAP users, groups and memberships are retrieved from your directory server. When you modify a user, group or membership via the application administration screens, the changes will be applied directly to your LDAP directory server. Please ensure that the LDAP user specified for the application has modification permissions on your LDAP directory server.
Adding Users to Groups Automatically
Default Group Memberships
Option available in Confluence 3.5 and later, and JIRA 4.3.3 and later. This field appears if you select the 'Read Only, with Local Groups' permission. If you would like users to be automatically added to a group or groups, enter the group name(s) here. To specify more than one group, separate the group names with commas.
Enable Nested Groups
Enable or disable support for nested groups. Some directory servers allow you to define a group as a member of another group. Groups in such a structure are called 'nested groups'. If you are using groups to manage permissions, you can create nested groups to allow inheritance of permissions from one group to its sub-groups.
|Manage User Status Locally||If true, you can activate and deactivate users in Crowd independent of their status in the directory server.|
|Filter out expired users||If true, user accounts marked as expired in ActiveDirectory will be automatically removed. For cached directories, the removal of a user will occur during the first synchronisation after the account's expiration date.|
Use Paged Results
Enable or disable the use of the LDAP control extension for simple paging of search results. If paging is enabled, the search will retrieve sets of data rather than all of the search results at once. Enter the desired page size – that is, the maximum number of search results to be returned per page when paged results are enabled. The default is 1000 results.
Choose whether to allow the directory server to redirect requests to other servers. This option uses the node referral (JNDI lookup
Naive DN Matching
If your directory server will always return a consistent string representation of a DN, you can enable naive DN matching. Using naive DN matching will result in a significant performance improvement, so we recommend enabling it where possible.
|Enable Incremental Synchronisation|
Enable incremental synchronisation if you only want changes since the last synchronisation to be queried when synchronising a directory.
Please be aware that when using this option, the user account configured for synchronisation must have read access to:
If at least one of these conditions is not met, you may end up with users who are added to (or deleted from) the Active Directory not being respectively added (or deleted) in the application.
This setting is only available if the directory type is set to "Microsoft Active Directory".
Synchronisation Interval (minutes)
Synchronisation is the process by which the application updates its internal store of user data to agree with the data on the directory server. The application will send a request to your directory server every x minutes, where 'x' is the number specified here. The default value is 60 minutes.
Read Timeout (seconds)
The time, in seconds, to wait for a response to be received. If there is no response within the specified time period, the read attempt will be aborted. A value of 0 (zero) means there is no limit. The default value is 120 seconds.
Search Timeout (seconds)
The time, in seconds, to wait for a response from a search operation. A value of 0 (zero) means there is no limit. The default value is 60 seconds.
Connection Timeout (seconds)
This setting affects two actions. The default value is 0.
User Schema Settings
User Object Class
This is the name of the class used for the LDAP user object. Example:
User Object Filter
The filter to use when searching user objects. Example:
User Name Attribute
The attribute field to use when loading the username. Examples:
NB: In Active Directory, the 'sAMAccountName' is the 'User Logon Name (pre-Windows 2000)' field. The User Logon Name field is referenced by 'cn'.
User Name RDN Attribute
The RDN (relative distinguished name) to use when loading the username. The DN for each LDAP entry is composed of two parts: the RDN and the location within the LDAP directory where the record resides. The RDN is the portion of your DN that is not related to the directory tree structure. Example:
User First Name Attribute
The attribute field to use when loading the user's first name. Example:
User Last Name Attribute
The attribute field to use when loading the user's last name. Example:
User Display Name Attribute
The attribute field to use when loading the user's full name. Example:
User Email Attribute
The attribute field to use when loading the user's email address. Example:
User Password Attribute
The attribute field to use when loading a user's password. Example:
|User Unique ID Attribute|
The attribute used as a unique immutable identifier for user objects. This is used to track username changes and is optional. If this attribute is not set (or is set to an invalid value), user renames will not be detected — they will be interpreted as a user deletion then a new user addition.
This should normally point to a UUID value. Standards-compliant LDAP servers will implement this as 'entryUUID' according to RFC 4530. This setting exists because it is known under different names on some servers, e.g. 'objectGUID' in Microsoft Active Directory.
Group Schema Settings
Group Object Class
This is the name of the class used for the LDAP group object. Examples:
Group Object Filter
The filter to use when searching group objects. Example:
Group Name Attribute
The attribute field to use when loading the group's name. Example:
Group Description Attribute
The attribute field to use when loading the group's description. Example:
Membership Schema Settings
Group Members Attribute
The attribute field to use when loading the group's members. Example:
User Membership Attribute
The attribute field to use when loading the user's groups. Example:
Use the User Membership Attribute, when finding the user's group membership
Check this if your directory server supports the group membership attribute on the user. (By default, this is the '
Use the User Membership Attribute, when finding the members of a group
Check this if your directory server supports the user membership attribute on the group. (By default, this is the '
Diagrams of Some Possible Configurations
Diagram above: JIRA connecting to an LDAP directory.
Diagram above: JIRA connecting to an LDAP directory with permissions set to read only and local groups.
- Configuring the Internal Directory
- Connecting to an LDAP Directory
- Connecting to an Internal Directory with LDAP Authentication
- Connecting to Crowd or Another JIRA Server for User Management
- Managing Multiple Directories
- Synchronising Data from External Directories
- Managing Nested Groups
- Diagrams of Possible Configurations for User Management
- User Management Limitations and Recommendations
- Allowing Other Applications to Connect to JIRA for User Management
- Migrating Users between User Directories