Documentation for JIRA 6.4 EAP. Not using this? See below:
(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 delegated authentication. This means that JIRA will have an internal directory that uses LDAP for authentication only. There is an option to create users in the internal directory automatically when they attempt to log in, as described in the settings section.

Overview

An internal directory with LDAP authentication offers the features of an internal directory while allowing you to store and check users' passwords in LDAP only. Note that the 'internal directory with LDAP authentication' is separate from the default 'internal directory'. On LDAP, all that the application does is to check the password. The LDAP connection is read only. Every user in the internal directory with LDAP authentication must map to a user on LDAP, otherwise they cannot log in.

When to use this option: Choose this option if you want to set up a user and group configuration within your application that suits your needs, while checking your users' passwords against the corporate LDAP directory. This option also helps to avoid the performance issues that may result from downloading large numbers of groups from LDAP.

On this page:

 

Connecting JIRA to an Internal Directory with LDAP Authentication

To connect to an internal directory but check logins via LDAP:

  1. Log in as a user with the 'JIRA Administrators' global permission.
  2. Choose > User Management > User Directories.
    (tick) Keyboard shortcut: 'g' + 'g' + start typing 'directories'.
  3. Add a directory and select type 'Internal with LDAP Authentication'.
  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. We recommend that the 'Internal Directory with LDAP Authentication' is at the top of the list. 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.
  7. Add your users and groups in JIRA. See Managing Users and Managing Groups.

Server Settings

Note: The option to select a directory type is available only in JIRA 4.3.3 and later.

Setting

Description

Name

A descriptive name that will help you to identify the directory. Examples:

  • Internal directory with LDAP Authentication
  • Corporate LDAP for Authentication Only

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 some 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 box 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

Password

The password of the user specified above.

Copying Users on First Login

Note: The option to copy users on first login is available only in JIRA 4.3.3 and later. It currently copies the data across whenever a user logs in, as per the bug  JRA-27541 - Delegated LDAP copy user on first login problem Resolved .

Setting

Description

Copy User on Login

This option affects what will happen when a user attempts to log in. If this box is checked, the user will be created automatically in the internal directory that is using LDAP for authentication when the user first logs in and their details will be synchronised on each subsequent log in. If this box is not checked, the user's login will fail if the user wasn't already manually created in the directory.

If you check this box the following additional fields will appear on the screen, which are described in more detail below:

  • Default Group Memberships
  • Synchronise Group Memberships
  • User Schema Settings (described in a separate section below)

Default Group Memberships

This field appears if you check the Copy User on Login box. 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. 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 to the internal directory that is using LDAP for authentication.

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
  • bamboo-users,jira-users,jira-developers

Synchronise Group Memberships

This field appears if you select the Copy User on Login checkbox. If this box is checked, group memberships specified on your LDAP server will be synchronised with the internal directory each time the user logs in.

If you check this box the following additional fields will appear on the screen, both described in more detail below:

  • Group Schema Settings (described in a separate section below)
  • Membership Schema Settings (described in a separate section below)

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.

User Name Attribute

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

  • cn
  • sAMAccountName

User Schema Settings (Used when Copying Users on First Login)

Note: The user schema settings are available only in JIRA 4.3.3 and later.

Setting

Description

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

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=*))

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

Group Schema Settings (Used when enabling Synchronise Group Memberships)

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

Diagrams of Possible Configurations

Gliffy-JIRA-LDAP-Auth-Only

Diagram above: JIRA connecting to an LDAP directory for authentication only.

Gliffy-JIRA-LDAP-Copy-On-First-Login

Diagram above: JIRA connecting to an LDAP directory for authentication only, with each user copied to the internal directory when they first log in to JIRA.

RELATED TOPICS

Configuring User Directories

26 Comments

  1. There is no "Advanced Settings" > "Follow Referrals" so my configuration is failing.

    In earlier version, I was able to configure that in osuser.xml

    Any work around, without adding LDAP Directory? LDAP Directory wont work for me, as we don't have jira-user group in LDAP server.

    1. I have raised JRA-23969 to look into "Follow Referrals" for LDAP Authentication Directories.

      LDAP Directory wont work for me, as we don't have jira-user group in LDAP server.

      Firstly, you can change the Global Permissions for who can log in to be a different group.
      See Admin > Global Settings > Global Permissions

      Secondly, you could set up an LDAP directory as "Read-Only with Local Groups".
      This means that it will use the groups and memberships defined in the LDAP server, but you can also create "Local Groups" (ie that live in JIRA only) that you can configure the LDAP users to belong to.
      See the Permission Settings section in Connecting to an LDAP Directory.

      1. Thanks Mark. A user interface to add those advanced features to LDAP Delegated Authentication will be great.

        At my test instance, I added manually to the LDAP_Attribute table, and that worked.

  2. Anonymous

    after the configuration, I had to restart the JIRA server in order to able to login using the user created.

    not sure if anyone else had to do this.

    Eddie

  3. Anonymous

    How can I configure the delegating directory to perform a LDAP bind as the logging in user in order to authenticate, rather than logging in as a superuser and retrieving the hashed password?

  4. I got the "Internal Directory with LDAP Authentication" working with an instance of Zimbra LDAP server, which isn't one of the specific choices in the drop-down list. Here's what worked for me:

    Generic Directory Server
    Hostname: ldap.example.com
    Username: uid=zimbra,cn=admins,cn=zimbra
    Password: secret
    Default Group Memberships: jira-users

    Base DN: dc=example,dc=com
    User Name Attribute: uid

    Additional User DN: ou=people
    User Object Class: zimbraAccount
    User Object Filter: (uid=*)
    User Name RDN Attribute: cn
    User First Name Attribute: givenName
    User Last Name Attribute: sn
    User Display Name Attribute: displayName
    User Email Attribute: mail

    I also found LDAPManager (https://sourceforge.net/projects/ldapmanager) for OSX useful for debugging what attributes were present in the LDAP server.

    1. Anonymous

      Thank you Matt for this. You saved lot of my time.

       

      Cheers,

      1. You're welcome. It saved me time too when I googled for it recently and found that I'd already documented it here! 

        1. Absolute life saver, googled for this quite a bit, asked in atlassian IRC, asked on answers.... nothing.  But went through my google results again and boom saw this down on the comments.  THIS REALLY REALLY needs to be added to the atlassian wiki someplace.

  5. We should include instructions for enabling debugging. One of our customers spent way too long trying to get internal LDAP integration to work, and he could only move forward by figuring out how to turn on advanced debugging.

    He did via the com.atlassian.crowd.directory log4j.props control being set to DEBUG.

  6. A note to all - the username and password is mandatory even though they are not in the setupscreen in JIRA User Directory Admin. You can't authorize without logging in first (no anonymous login).

    1. Thank you, this information really helped me.  Without a username / password, the LDAP login simply fails with no indication why (at least in the default logs).  Another tip - ask your domain admin to give you a service account that doesn't require regular password changes.  

    2. JIRA allows anonymous bind to LDAP.

      There was a bug in v4.3 that broke this but it was fixed in v4.3.1:

      JRA-23819 - LDAP anonymous bind is not allowed in JIRA v4.3 Resolved

      It could be that your LDAP administrator does not allow anon bind at the LDAP server?
      Otherwise if you really think it doesn't work you should raise a bug.

       

  7. I do not have the "User Directories" option at all within 'Administration' > 'Users' . Has anyone else experienced this?

    With JIRA 4.1.2 I just created an osuser.xml file under WEB-INF/classes ....perhaps this will also work for 5.0, but it would still be good to find out why I cannot graphically access the 'User Directories' option.

    1. Anonymous

      Hi. I have actually the same issue "Kristian Ashton" has.

      I have an issue, that when i create a user it gives me a list of  3 "JIRA Delegated Authentication Directory", when i selected the wrong one (by try and error) a user wasnt able to authenticate.

      I recently migrated JIRA 4.2 to v5.2#812-sha1:c4fbab6.
      My osuser.xml has a definition of 2 external LDAP servers (not 3).

      Regarding Documentation, i even tried on filesystem to find the mentioned option. Nowhere any signs of the administration option "'Administration' > 'Users".

      What are we doing wrong?

    2. In order to see the User Directories page, you will need to be

      • On JIRA v4.3 or later
      • Using JIRA "On Premises"
        JIRA "On Demand" customers don't get this option.
      • A "System Administrator", not just an "Administrator"
  8. I have it set up to sync users and groups with the ldap directory in our JIRA testing environment. Now I am not able to add those users to the groups that were originally made in the internal JIRA directory. Is it supposed to be like this?

     

    We are wanting to sync our groups in LDAP with our production JIRA instance, however, we have many groups already in JIRA that users are members of and we would like to keep these groups and add the ldap groups. Users in the ldap can't even log in because they are not a member of groups jira-users and we can't add them.

    1. It sounds like you are currently using a "Full LDAP" user directory, not an "Internal Directory with LDAP Authentication".
      You actually want to be looking at the Connecting to an LDAP Directory documentation page. 

      We are wanting to sync our groups in LDAP with our production JIRA instance, however, we have many groups already in JIRA that users are members of and we would like to keep these groups and add the ldap groups.

      It sounds like you want to set the "local groups" flag to on. See "Read Only, with Local Groups" in the page I linked above under the Permission Settings section.

      Users in the ldap can't even log in because they are not a member of groups jira-users and we can't add them.

      Once you have local groups set up as above, then you will be able to manually add users to the jira-users group.
      Or see the "Adding Users to Groups Automatically" section for a way to make all users belong to this group by default.

       

      Alternatively, you can switch to an "Internal Directory with LDAP Authentication" as documented on this page.
      The main difference between these two LDAP directory types is that the "full LDAP" will download all the users from the LDAP server, whereas the "Internal Directory with LDAP Authentication" will wait until a user is added manually by the admin, or it can also be configured to download a single user upon successful login.
      The secondary difference is that full LDAP will periodically update all user details, whereas Internal with LDAP Auth will let the admin manually change details and/or update only individual users upon login.
      See the following sections in this page for more details:  

      • Copy User on Login
      • Synchronise Group Memberships
      • Default Group Memberships

       

      Finally, if you are still confused, you can contact https://support.atlassian.com/

      1. Well we are currently synching ldap with local groups, but we are wanting to also sync our LDAP groups. So we want the local groups that our ldap users are in as well as the groups they are part of in the LDAP.

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

    1. It sounds to me like the AD server that JIRA is connecting to is suffering performance issues, as when you switch to the other node it works fine until that node goes slow.

      If you are using "Internal Directory with LDAP Authentication" then I doubt that this is related to the JIRA upgrade.
      If you are using the "Active Directory" (aka "full LDAP") directory type, then it is possible that JIRA's LDAP synchronisation is causing the load on the AD server, or it could be something else. Consider trying incremental synch instead of full synch if this is the case.

      I would contact your AD administrator and see if they know about the intermittent performance issues, and if you need more help from the JIRA end create a support ticket on https://support.atlassian.com/.

       

  10. there is no Copy User on Login option (anymore?!) in JIRA 6.1 .. or am I blind?

    or is it hidden in some cases?

    1. I started up JIRA 6.1.3 and the option is available for me both in create and edit.

      If you still see this problem, I suggest that you raise a support ticket.

    2. dough .. thx to Support it pointed out that it was my mistake looking for the wrong connector ... I was not aware of that you can't switch the connector type afterwards and even there ARE different connectors in the same "Directory Type" selection from "Add Directory" in the admin panel. It's someway confusing that you can both configure for the same directory types and also "Microsoft Active Directory" is just a shortcut for the LDAP Directory Connector while this "internal directory connector" can be configured to work with AD but is NOT the same!

      ^ misleading header "Directory Type" while you technically select between different connectors and you are able to setup AD via 3 of those options but only 2 differs each other

  11. 6.2 "Internal with LDAP Authentication" is broken.

    I tried every variant of generic/openldap server available and none of them had the ability to set either the ldap.user.filter or ldap.user.objectclass settings in the cwd_directory_attribute table.

    In the end I had to manually edit the database and restart the server so that it would actually find the user accounts in the LDAP server.