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

LDAP schema

LDAP permission

Advanced settings

User schema settings

Group schema settings

Membership schema settings