Connecting to an LDAP Directory

Still need help?

The Atlassian Community is here for you.

Ask the community

You can connect Hipchat Server to an LDAP directory for authentication and user management. Hipchat Server will periodically synchronize the user data, including username, display name, and email, from LDAP.


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.

Connecting to an LDAP Directory in Hipchat Server

To connect Hipchat Server to an LDAP directory:

  1. Browse to your server's fully qualified domain name, for example
  2. Log into the Hipchat Server web user interface (UI) using your administrator email and password. 
  3. Go to Group admin > Authentication.
  4. Choose Add Directory and and select either:
    • 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. (The settings and which values to provide are described further down this page.)
  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




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.


The host name of your directory server. Examples:



The port on which your directory server is listening. Examples:

  • 389
  • 10389
  • 636 (for example, for 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.


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

By default, all users can read the uSNChanged attribute; however, only administrators or users with relevant permissions can access the Deleted Objects container. The specific privileges required by the user to connect to LDAP are "Bind" and "Read" (user info, group info, group membership, update sequence number, deleted objects), which the user can obtain by being a member of the Active Directory's built-in administrators group.

Note that the incremental sync will fail silently if the Active Directory is accessed by a user without these privileges. This has been reported as CWD-3093.


The password of the user specified above.

Note: Connecting to an LDAP server requires that this application log in to the server with the username and password configured here. As a result, this password cannot be one-way hashed - it must be recoverable in the context of this application. The password is currently stored in the database in plain text without obfuscation. To guarantee its security, you need to ensure that other processes do not have OS-level read permissions for this application's database or configuration files.

Schema Settings



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

If no value is supplied for Additional User DN or Additional Group DN this will cause the subtree search to start from the base DN and, in case of huge directory structure, could cause performance issues for login and operations that rely on login to be performed.

Permission Settings



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

Not applicable to Hipchat Server.


Not applicable to Hipchat Server.

Advanced Settings



Secure SSLIf ticked, the SSL certificate of the LDAP server will be checked

Enable Nested Groups

Not applicable to Hipchat Server

Manage User Status LocallyIf true, you can activate and deactivate users in Crowd independent of their status in the directory server.

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 Synchronization

Enable incremental synchronization if you only want changes since the last synchronization to be queried when synchronizing a directory.

(warning) Please be aware that when using this option, the user account configured for synchronization must have read access to:

  • The uSNChanged attribute of all users and groups in the directory that need to be synchronized.
  • 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 the application.

This setting is only available if the directory type is set to "Microsoft Active Directory".

Synchronization Interval (minutes)

Synchronization 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



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

You can have a maximum of 4,000 characters in this field. Ensure your LDAP filters are concise.

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

This field cannot accept more than 50 characters from LDAP. Otherwise, the sync will skip the user. HCPUB-1763 - Getting issue details... STATUS is a feature request to increase the limit beyond 50 characters.

User Email Attribute

The attribute field to use when loading the user's email address. Example:

  • mail

The user will not be synchronized if this attribute is empty. Always use the attribute that contains the user email (example: userPrincipalName).

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

Note: Group schema settings are not relevant to Hipchat Server.

Membership Schema Settings

The User Member Attribute is the only Membership schema setting relevant to Hipchat Server. All other Membership schema settings are not relevant.

User Member Attribute

Because Hipchat Server doesn't filter by groups, use this attribute to identify which users are associated with groups. For more information, see the section on filtering for groups in Reduce the number of users synchronised from LDAP to Hipchat Server.



Diagram of Possible Configuration


Last modified on Feb 14, 2018

Was this helpful?

Provide feedback about this article
Powered by Confluence and Scroll Viewport.