# Stash Latest (2.12) : Delegating Stash authentication to an LDAP directory

Created and last modified by pwatson on Mar 04, 2014

You can configure Stash to use an LDAP directory for delegated user authentication while still using the internal Stash directory for user and group management.

There is an option to automatically create a user account in Stash's internal directory when the user attempts to log in, as described in the Copy users on login section below.

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

To connect Stash to an LDAP directory for delegated authentication:

1. Log in to Stash as a user with 'Admin' permission.
2. Go to the Stash administration area and click User Directories (under 'Accounts').
3. Click Add Directory and select Internal with LDAP Authentication 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 for 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.

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 individual accounts when granting permissions. However, be careful not to add more users to those groups that your Stash license allows. If the license limit is exceeded, your developers will not be able to push commits to repositories, and Stash will display a warning banner. See this FAQ.

On this page:

## Server settings

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 login

The settings described in the table below relate to when a user attempts to authenticate with Stash. This authentication attempt can occur either:

- when using the Stash login screen.
- when issuing a Git clone or push command at the command line, for a repository managed by Stash.

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

Alternatively, you can move the delegated authentication directory to the top of the User Directories list and create the user manually (go to Administration > Users > Create user). Using this manual method you must currently create a junk password when creating users: there is an improvement request to address this. Please log in and vote for STASH-3424 - Disable "Change password" field from admin and user page when delegated authentication is used Open

## 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.
User Name Attribute | The attribute field to use when loading the username. Examples: `cn` `sAMAccountName`

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

## User schema settings

Note: this section is only visible when Copy User on Login is enabled.

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

Note: this section is only visible when both Copy User on Login and Synchronise Group Memberships are enabled.

Setting | Description
--- | ---
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`
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

Note: this section is only visible when both Copy User on Login and Synchronise Group Memberships are enabled.

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 box if your directory server supports the group membership attribute on the user. (By default, this is the 'memberOf' attribute.) If this box is checked, 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 box is not checked, your application will use the members attribute on the group ('member' by default) for the search.