LDAP Configuration Guide
What is LDAP
LDAP is the Lightweight Directory Access Protocol. It's a hierarchical organization of Users, Groups, and Organisational Units - which are containers for users and groups. Every object has it's own unique path to it's place in the directory - called a Distinguished Name, or DN. For example, we might have the following DNs for a user and a group:
cn=John Doe,ou=Users,dc=example,dc=local cn=Finance,ou=Users,dc=example,dc=local
That means that an object with the common name "John Doe" is inside the Users container, and belongs to the domain
example.local. When defining an LDAP directory in Atlassian applications, we specify the Base DN - the section of the directory where the application will commence searching for Users and Groups. In order for your users to be found in an application, they must be located underneath the base DN.
Using the examples above, our User and Group are both located in the Organisational Unit called Users, so we could safely set our Base DN to:
Both the group and user would be available in our application.
How strict should my base DN be?
A more strict Base DN will bring in fewer User and Groups from the directory. For example,
ou=Users,dc=example,dc=local is more strict than
dc=example,dc=local ; as it will only bring in objects that are under the Organisation Unit Users.
You should consider the number of users your application is licensed for; as well as where those users are located in the directory.
When should I use a user or group DN?
The user or group DN is added onto the base DN, and will be used as the starting place to look for users and groups. This is helpful when your users are located at a different location to the groups they're a part of. For example, consider the following:
- Base DN:
- Group DN:
- User DN:
This means your application will start looking for users at
ou=Users,dc=example,dc=local, and will look for groups at
When should I use a user or group filter?
A user or group filter ensures that users or groups matching the respective filter will be included, while those that do not match the filter will be excluded. The type of your directory will determine what fields are available for use in a filter. For example, Microsoft Active Directory supports the
memberOf attribute - which allows a filter to work on user membership.
It's important to ensure that user or group filters are used correctly. Incorrect usage can give incorrect results - such as too many users or groups; too few users or groups; or none at all.
- A user filter tests that users brought in match the filter
- In some directory configurations, a user filter can be used to test the memberships of users - but note that will only affect users brought into the application, not the groups - you must still use a group filter.
- A group filter tests that groups brought in match the filter
See our guide to writing LDAP filters for more information on constructing a user or group filter.
Active Directory: When should I disable "Follow Referrals"?
This only applies to applications connecting to Microsoft Active Directory.
By default, "Follow Referrals" is turned on. There are two scenarios where the option is used. When "Follow Referrals" is enabled, requests to objects that include the Domain Component (such as
dc=example,dc=local) will cause a DNS request to be made to
Scenario One: DNS Resolution
If this DNS name cannot be resolved by your application, then the lookup will fail. Ideally, the DNS resolution should not fail; however, in some cases it may be desirable to disable "Follow Referrals" instead of adjusting the DNS resolution.
Scenario Two: Cross domain memberships
Memberships to groups can be contained in another domain. For example, the user Joe in the domain
foo.acme.local might be a member of the
atlassian-applications group in
bar.acme.local. When your application queries the
foo.acme.local domain controller about Joe's memberships, the membership of
bar.acme.local will be returned if "Follow Referrals" is enabled.
In some configurations, "Follow Referrals" may degrade performance during user authentication or synchronization - particularly if there is latency between the two domain controllers (or the root domain controller of the forest; which is also part of the transaction). For more information on how cross-domain requests work, please see this Microsoft TechNet article.
Active Directory: How do I configure my directory to be writable from my Atlassian Applications?
You must configure your Domain Controller with an SSL certificate, and then import that SSL certificate to the trust store of your application. You must import the certificate into the application's trust store, so the application knows to trust the SSL certificate presented by your Domain Controller.
If you are using a self-signed certificate, untick the "Secure SSL" box to disable security checks on the certificate itself. You can then select port 636 (or the LDAPS port for your server) to make a secure connection without checking the validity of the SSL certificate.
Note about Windows Server 2012
The bind account simply requires administrator privilege to be able to write to Active Directory. An SSL certificate was not required in testing. The groups that grant these rights are
Schema Admins, and
Enterprise Admins. If your bind account is a member of one of these groups, you may not require an SSL connection to Active Directory.