Documentation for JIRA 6.4 (This documentation includes the project navigation sidebar). Not using this? See below:
(JIRA 6.4 without sidebar documentation | JIRA 6.3.x documentation | JIRA Cloud documentation | earlier versions of JIRA)

Skip to end of metadata
Go to start of metadata

You can connect your JIRA application to an LDAP directory for authentication, user and group management.

Overview

An 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
  • OpenDS
  • OpenLDAP
  • 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.

On this page:

Connecting to an LDAP Directory in JIRA

To connect JIRA to an LDAP directory:

  1. Log in as a user with the 'JIRA System Administrators' global permission.
  2. Choose > User Management > User Directories.
    (tick)Keyboard shortcut: 'g' + 'g' + start typing 'directories'.
  3. 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.
  4. Enter the values for the settings, as described below.
  5. Save the directory settings.
  6. 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 details see Managing Multiple Directories.

Notes:

  • 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.

Server Settings

Setting

Description

Name

Enter a meaningful name to help you identify the LDAP directory server. Examples:

  • Example Company Staff Directory
  • Example Company Corporate LDAP

Directory Type

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:

  • Microsoft Active Directory
  • OpenDS
  • And more.

Hostname

The host name of your directory server. Examples:

  • ad.example.com
  • ldap.example.com
  • opends.example.com

Port

The port on which your directory server is listening. Examples:

  • 389
  • 10389
  • 636 (for example, for SSL)

Use SSL

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.

Username

The distinguished name of the user that the application will use when connecting to the directory server. Examples:

  • cn=administrator,cn=users,dc=ad,dc=example,dc=com
  • cn=user,dc=domain,dc=name
  • user@domain.name

(info) 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.

Password

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.

Schema Settings

Setting

Description

Base DN

The root distinguished name (DN) to use when running queries against the directory server. Examples:

  • o=example,c=com
  • cn=users,dc=ad,dc=example,dc=com
  • For Microsoft Active Directory, specify the base DN in the following format: dc=domain1,dc=local. You will need to replace the domain1 and local for your specific configuration. Microsoft Server provides a tool called ldp.exe which is useful for finding out and configuring the the LDAP structure of your server.

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:

  • ou=Users

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:

  • ou=Groups

Permission Settings

Note: You can only assign LDAP users to local groups when 'External Management User Management' is not selected.

Setting

Description

Read Only

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.

(info) 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

Read/Write

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

Setting

Description

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.
In Confluence 3.5 to Confluence 3.5.1: Each time a user logs in, their group memberships will be checked. If the user does not belong to the specified group(s), their username will be added to the group(s). If a group does not yet exist, it will be added locally.
In Confluence 3.5.2 and later, and JIRA 4.3.3 and later: The first time a user logs in, their group memberships will be checked. If the user does not belong to the specified group(s), their username will be added to the group(s). If a group does not yet exist, it will be added locally. On subsequent logins, the username will not be added automatically to any groups. This change in behaviour allows users to be removed from automatically-added groups. In Confluence 3.5 and 3.5.1, they would be re-added upon next login.

Please note that there is no validation of the group names. If you mis-type the group name, authorisation failures will result – users will not be able to access the applications or functionality based on the intended group name.

Examples:

  • confluence-users
  • confluence-users,jira-users,jira-developers

Advanced Settings

Setting

Description

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 LocallyIf true, you can activate and deactivate users in Crowd independent of their status in the directory server.
Filter out expired usersIf 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.

Follow Referrals

Choose whether to allow the directory server to redirect requests to other servers. This option uses the node referral (JNDI lookup java.naming.referral) configuration setting. It is generally needed for Active Directory servers configured without proper DNS, to prevent a 'javax.naming.PartialResultException: Unprocessed Continuation Reference(s)' error.

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.

This setting determines how your application will compare DNs to determine if they are equal.

  • If this checkbox is selected, the application will do a direct, case-insensitive, string comparison. This is the default and recommended setting for Active Directory, because Active Directory guarantees the format of DNs.
  • If this checkbox is not selected, the application will parse the DN and then check the parsed version.
Enable Incremental Synchronisation

Enable incremental synchronisation if you only want changes since the last synchronisation to be queried when synchronising a directory.

(warning) Please be aware that when using this option, the user account configured for synchronisation must have read access to:

  • The uSNChanged attribute of all users and groups in the directory that need to be synchronised.
  • The objects and attributes in the Active Directory deleted objects container (see Microsoft's Knowledge Base Article No. 892806 for details).

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.

  • The time to wait when getting a connection from the connection pool. A value of 0 (zero) means there is no limit, so wait indefinitely.
  • The time, in seconds, to wait when opening new server connections. A value of 0 (zero) means that the TCP network timeout will be used, which may be several minutes.

User Schema Settings

Setting

Description

User Object Class

This is the name of the class used for the LDAP user object. Example:

  • user

User Object Filter

The filter to use when searching user objects. Example:

  • (&(objectCategory=Person)(sAMAccountName=*))

More examples can be found here and here.

User Name Attribute

The attribute field to use when loading the username. Examples:

  • cn
  • sAMAccountName

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:

  • cn

User First Name Attribute

The attribute field to use when loading the user's first name. Example:

  • givenName

User Last Name Attribute

The attribute field to use when loading the user's last name. Example:

  • sn

User Display Name Attribute

The attribute field to use when loading the user's full name. Example:

  • displayName

User Email Attribute

The attribute field to use when loading the user's email address. Example:

  • mail

User Password Attribute

The attribute field to use when loading a user's password. Example:

  • unicodePwd
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

Setting

Description

Group Object Class

This is the name of the class used for the LDAP group object. Examples:

  • groupOfUniqueNames
  • group

Group Object Filter

The filter to use when searching group objects. Example:

  • (&(objectClass=group)(cn=*))

Group Name Attribute

The attribute field to use when loading the group's name. Example:

  • cn

Group Description Attribute

The attribute field to use when loading the group's description. Example:

  • description

Membership Schema Settings

Setting

Description

Group Members Attribute

The attribute field to use when loading the group's members. Example:

  • member

User Membership Attribute

The attribute field to use when loading the user's groups. Example:

  • memberOf

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 'memberOf' attribute.)

  • If this checkbox is selected, your application will use the group membership attribute on the user when retrieving the list of groups to which a given user belongs. This will result in a more efficient retrieval.
  • If this checkbox is not selected, your application will use the members attribute on the group ('member' by default) for the search.
  • If the Enable Nested Groups checkbox is seleced, your application will ignore the Use the User Membership Attribute option and will use the members attribute on the group for the search.

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 'member' attribute.)

  • If this checkbox is selected, your application will use the group membership attribute on the user when retrieving the members of a given group. This will result in a more efficient search.
  • If this checkbox is not selected, your application will use the members attribute on the group ('member' by default) for the search.

Diagrams of Some Possible Configurations

Gliffy-JIRA-To-LDAP

Diagram above: JIRA connecting to an LDAP directory.

Gliffy-JIRA-To-LDAP-RO-Local-Groups

Diagram above: JIRA connecting to an LDAP directory with permissions set to read only and local groups.

RELATED TOPICS

Configuring User Directories

24 Comments

  1. Anonymous

    For the "Follow Referrals" description: "It is generally needed for Active Directory servers configured without proper DNS, to prevent a 'javax.naming.PartialResultException: Unprocessed Continuation Reference(s)' error."

    ...gives the impression that encountering referrals is a "problem" or configuration error.  Referrals can also be encountered when the domain controller being connected to cannot answer the query and has to refer the client to a different dc that can.  This is common if an enterprise contains multiple domains (say, one for a USA office and one for UK) among other scenarios.  If set incorrectly, the AD query may given incomplete or no results when results really do exist, but the referral wasn't followed...

    1. Anonymous

      Yeah. This problem is a bitch to me and it usually takes me 3 times to authenticate successfully. Any real fix, than a workaround?

    2. Anonymous

      I have also seen it produce "ConnectionTimeoutException"s, apparently because the referral sent was wrong and led to a timeout.

  2. Anonymous

    If mail attribute value is empty, imported users have empty email. I want to append email suffix with imporing operation.

    How can I append suffix to imported users?

  3. If I configure a LDAP, does it mean that *all* users in LDAP will have access to JIRA ? If so, this will increase the number of licences we need!

    What I basically need is a way to declare that some (not all) users in LDAP are Jira-authorized, to avoid to reenter their password, name,...

    Our LDAP contains approx 350 accounts, less than 40 need to connect to JIRA 

    1. They don't become a Jira user until they attempt to sign in, so all those extra LDAP users won't count against your license if they don't sign in. I don't know how to lock them out without using groups and Crowd, but I'm still new to Atlassian products.

  4. Anonymous

    Hi,

    i´m trying to import user from Active Directory  in JIRA. But I onlyneed the  users, that are in specific group (for Example "Jira").

    How can I configurate this with LDAP user directory? If I add filter "cn=Jira" by Additional Group DN, I have filter by group, but still get users from all groups.

    If I try to use Additional User DN: memberOf=cn=Jira, I get error by synchronizing.

    Pleses help.

    Dimitrij

  5. In section "Adding Users to Groups Automatically" is stated, that: "On subsequent logins, the username will not be added automatically to any groups". 

    How can I add users belonging to newly added AD group? 

  6. Anonymous

    Hi, 

    I have a LDAP-Server which works with posixGroups where the membership is defined like 

    memberUid: doe

    doe is the uid of the user. But JIRA want the full DN, like this:

    memberUid: uid=doe,ou=users,o=company

    Is there a way to bring JIRA running with only the uid and not the full path?

  7. Anonymous

    To limit what users can access JIRA, you can add an addition filter to the User Object Filter (User Schema Settings) something like this:

    (&(objectCategory=Person)(sAMAccountName=*)(memberOf=cn=jira-users,ou=Jira,ou=Groups,dc=example,dc=com))

     

    Then only users that are part of the jira-users group will appear in the Users list and able to login.

    1. This suggestion worked for my AD - JIRA system to allow us to filter and limit a subset users from a much larger total set of users. 

  8. Hi everybody,

    I have question regarding LDAP integration from JIRA.

    I have Users who are in an OU=Users, and other Users who are in an OU=Staff (they are all part of the same LDAP, but their only common parent is the Root of the LDAP). Is it possible to write a query to filter Users by their OU? I've managed to write one with for the ObjectCategory and the ObjectClass, but how can I achieve the same for the OU?

    For now, I had to add 2 User Directories from JIRA and point to the same AD but with a different OU path...not sure it is the best solution...

    Thanks,

  9. Anonymous

    We've managed to set up authenticating against AD, but you must give a username and password to authenticate. This is a problem, because whilst at the moment we do have some of these 'pseudo-users', within the foreseeable future we'll lose these, because AD will be administrated on a global scale.

    AD allows you to authenticate with your own username and password (the one you fill i when you login), so why does JIRA require you to set it up with one of those 'pseudo-users'?

  10. Anonymous

    I want to get other properties of LDAP like the company, department, etc. I use Active Directory. Is this possible?

  11. Anonymous

    Hi, my LDAP groups are defined by a member field on the groups (actual name: uniquemember), but there is no MemberOf field on users. From the documentation I understand that by not checking the "Use the User Membership Attribute: " box, everything should work OK and tha JIRA will not try to find a memberOf field.

    But the LDAP tests seem to still use it (and I cannot left the user's group membership field empty, it is mandatory) , and thus fail with a: (XXX is the value of my fields "Additional Group DN,Base DN")

    Test get user's memberships. : Failed

    org.springframework.ldap.InvalidNameException: XXX: [LDAP: error code 34 - Invalid DN Syntax]; nested exception is javax.naming.InvalidNameException: XXX: [LDAP: error code 34 - Invalid DN Syntax]; remaining name 'X'

    For more information regarding LDAP error codes see Troubleshooting LDAP Error Codes.

    (Using Atlassian JIRA v5.2.11)

    So my question: can JIRA use LDAPs where the membership information is only encoded in the groups record, not the users, and how?

     

  12. Hello,

    We are having an issue configuring LDAP user directory. When we test the connection using a domain admin account the connection passes through no problem. When using a regular domain user we have authentication errors when testing the connection. Has anyone run into this problem? Please help if you have.

  13. Hello,

    We have recently migrated the JIRA from 4.1.1 to 5.2.10 and ever since we are facing the authentication time out errors. sometimes users are not seeing any errors and it would just times out and get them back to the login screen and we are able to access the JIRA using the internal accounts but not with any AD accounts during this time.

     

    we have kept the same configurations while migrating the application, no changes to our AD servers on topology or configuration wise. we never had this issue before migration. we can not replicate this problem in JIRA QA where it has the same configuration as production. 

    since we have multiple domain servers, if we switch to a different peer AD Directory the problem is resolving but its coming back again in 1-2 weeks of time and when it happens again we are switching the AD directory back to the original then the problem is going away but nevertheless to say the problem is re-occurring.

     

    is any one faced the same issue? appreciate your responses.

     

     

  14. LDAP Online Training

      Click Here For Enquiry

    Introduction

     

    LDAP - Overview

     
    • A brief History of LDAP
    • LDAP Overview
    • LDAP vs. Database
    • LDAP Usage Summary
    • LDAP Data (Object) Model
    • Object Tree Structure
    • Attributes
    • Object Classes
    • Describing the Tree and Adding Data
    • Navigating the Tree (DNs and RDNs)
    • LDAP Replication and Referrals
    • Referrals
    • Replication
  15. New LDAP configuration is a complete BS thing. Even Sys Admins are not able to provide all input.....

  16. This page could use some editing. It shows two rows:

    Use the User Membership Attribute, when finding the user's group membership

     

    Use the User Membership Attribute, when finding the members of a group

    But I only see the first one in the Delegated LDAP configuration for JIRA 6.2.

  17. We have installed A/D and it works however, when any of the users send a email to create a ticket it does not associate their email with their A/D Account.  So upon sending a new email I can either have the reporter the default reporter or create a new account.  E.G.  user john with email john@company.com sends an email to jira@company.com to create an issue.  JIRA does not make john the reporter it will either create a new account id john@company.com or assign it to the default user.  This is a real pain and could really help to have a solution.

  18. Can anyone help me reduce this user query to less than 255 characters? I have almost exactly the same query working in Confluence, but when I try to set this up in JIRA I am hitting a length constraint in the directory_attribute table. Confluence is limited to 4000, whereas JIRA is 255! Atlassian are aware of this (JRA-28805)

    My query is as follows:

    (&(objectCategory=user)(|(memberOf=CN=jira-administrators,OU=Atlassian JIRA,DC=ABC,DC=XYZ)(memberOf=CN=jira-reminder,OU=Atlassian JIRA,DC=ABC,DC=XYZ)(memberOf=CN=jira-system-administrators,OU=Atlassian JIRA,DC=ABC,DC=XYZ)(memberOf=CN=jira-users-internal,OU=Atlassian JIRA,DC=ABC,DC=XYZ)))

    Everything I have tried to reduce the length of this, is causing the query not to work, including dropping the OU and DC, and adding wildcards.

  19. Matthew, this is not really the place to get support, but rather to comment on the page contents. I would recommend Atlassian Answers. Having said that, why not have jira-users-internal group include all members of jira-administrators, jira-reminder, jira-system-administrators, so you only need to query jira-users-internal. Or make jira-users a super-group. 

  20. Thanks Kevin. My post was a last attempt/plea for help as my support request and Atlassian Answers post were not progressing quickly enough. I shall try what you have suggested - thank you for your quick response.