# Stash Latest (2.12) : Connecting Stash to an existing LDAP directory

Created and last modified by pwatson on Apr 03, 2014

You can connect Stash to an existing LDAP user directory, so that your existing users and groups in an enterprise directory can be used in Stash. The LDAP directory is used for both user authentication and account management.

Stash is able to connect to the following LDAP directory servers:

- Microsoft Active Directory
- Apache Directory Server (ApacheDS) 1.0.x and 1.5.x
- Apple Open Directory (Read-Only)
- Fedora Directory Server (Read-Only Posix Schema)
- Novell eDirectory Server
- OpenDS
- OpenLDAP
- OpenLDAP (Read-Only Posix Schema)
- Generic Posix/RFC2307 Directory (Read-Only)
- Sun Directory Server Enterprise Edition (DSEE)
- Any generic LDAP directory server

See also this information about deleting users and groups in Stash.

##### On this page:

Icon

Connecting Atlassian Stash to your external directory is not sufficient to allow your users to log in to Stash. You must explicitly grant them access to Stash in the global permission screen.

We recommend that you use groups instead of invidual accounts when granting permissions.

## License considerations

When connecting Stash to an external directory, be careful not to allow access to Stash by more users than your Stash license allows. If the license limit is exceeded, your develope rs will not be able to push commits to repositories, and Stash will display a warning banner. See this FAQ.

## Synchronisation when Stash is first connected to the LDAP directory

When you first connect Stash to an existing LDAP directory, the Stash internal directory is synchronised with the LDAP directory. User information, including groups and group memberships, is copied across to the Stash directory.

When we performed internal testing of synchronisation with an Active Directory server on our local network with 10 000 users, 1000 groups and 200 000 memberships, we found that the initial synchronisation took about 5 minutes. Subsequent synchronisations with 100 modifications on the AD server took a couple of seconds to complete. See the option below.

Note that when Stash is connected to an LDAP directory, you cannot update user details in Stash. Updates must be done directly on the LDAP directory, perhaps using a LDAP browser tool such as Apache Directory Studio.

### Option - Use LDAP filters to restrict the number of users and groups that are synchronised

You can use LDAP filters to restrict the users and groups that are synchronised with the Stash internal directory. You may wish to do this in order to limit the users or groups that can access Stash, or if you are concerned that synchronisation performance may be poor.

For example, to limit synchronisation to just the groups named "stash_user" or "red_team", enter the following into the Group Object Filter field (see Group Schema Settings below):

    (&(objectClass=group)(|(cn=stash_user)(cn=red_team)))

For further discussion about filters, with examples, please see How to write LDAP search filters. Note that you need to know the names for the various containers, attributes and object classes in your particular directory tree, rather than simply copying these examples. You can discover these container names by using a tool such as Apache Directory Studio.

## Authentication when a user attempts to log in

When a user attempts to log in to Stash, once synchronisation has completed, Stash confirms that the user exists in it's internal directory and then passes the user's password to the LDAP directory for confirmation. If the password matches that stored for the user, LDAP passes a confirmation back to Stash, and Stash logs in the user. During the user's session, all authorisations (i.e. access to Stash resources such as repositories, pull requests and administration screens) are handled by Stash, based on permissions maintained by Stash in its internal directory.

## Connecting Stash

To connect Stash to an LDAP directory:

1. Log in as a user with 'Admin' permission.
2. In the Stash administration area, click User Directories (under 'Accounts').
3. Click Add Directory and select either Microsoft Active Directory or LDAP as the directory type.
4. Configure the directory settings, as described in the tables below.
5. Save the directory settings.
6. Define the directory order by clicking the arrows next to each directory on the 'User Directories' screen. The directory order has the following effects:
   - 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.

## 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`
Password | The password of the user specified above.

## LDAP schema

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`

## LDAP permission

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.

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

## Attachments:

LDAP_external (application/gliffy+json)
LDAP_external.png (image/png)
LDAP_external (application/gliffy+json)
LDAP_external.png (image/png)
LDAP_external (application/gliffy+json)
LDAP_external.png (image/png)
LDAP_external (application/gliffy+json)
LDAP_external.png (image/png)
LDAP_external (application/gliffy+json)
LDAP_external.png (image/png)
LDAP_external (application/gliffy+json)
LDAP_external.png (image/png)
LDAP_external (application/gliffy+json)
LDAP_external.png (image/png)
LDAP_external (application/gliffy+json)
LDAP_external.png (image/png)