This page last changed on Mar 09, 2011 by rosie@atlassian.com.

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.

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. 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. Select 'User Directories' from the 'Users, Groups & Roles' section of the 'Administration' menu.
  4. 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.
  5. Enter the values for the settings, as described below.
  6. Save the directory settings.
  7. 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.

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 Tick this check 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.

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

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

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.

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 ticked, 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 ticked, the application will parse the DN and then check the parsed version.
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=*))
User Name Attribute The attribute field to use when loading the username. Examples:
  • cn
  • 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
User Password Attribute The attribute field to use when loading a user's password. Example:
  • unicodePwd

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:
  • (objectCategory=Group)
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 Put a tick in the checkbox if your directory server supports the group membership attribute on the user. (By default, this is the 'memberOf' attribute.)
  • If this checkbox is ticked, 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 retrieval.
  • If this checkbox is not ticked, your application will use the members attribute on the group ('member' by default) for the search.
  • If the 'Enable Nested Groups' checkbox is ticked, your application will ignore the 'Use memberOf Attribute on the User' 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 Put a tick in the checkbox if your directory server supports the group membership attribute on the user. (By default, this is the 'memberOf' attribute.)
  • If this checkbox is ticked, 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 search.
  • If this checkbox is not ticked, your application will use the members attribute on the group ('member' by default) for the search.

Diagrams of Some Possible Configurations

Full Size
A Gliffy Diagram named: Gliffy-JIRA-To-LDAP

Diagram above: JIRA connecting to an LDAP directory.

Full Size
A Gliffy Diagram named: 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

Document generated by Confluence on Mar 27, 2011 18:31