Connect to an LDAP Directory
You can connect Hipchat Data Center to an LDAP directory for authentication and user management. This is useful if your users and groups are already stored in a corporate directory, as you won't need to do additional user management work. Hipchat Data Center will periodically synchronize the user data, including username, display name, and email, from LDAP.
Supported directories
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
On this page:
Connecting to an LDAP Directory in Hipchat Data Center
To connect Hipchat Data Center to an LDAP directory:
- Browse to your server's fully qualified domain name, for example https://hipchat.yourcompany.com/.
- Log into the Hipchat Data Center web user interface (UI) using your administrator email and password.
- Go to User management > External directory.
- 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.
- Enter the values for the settings (the settings and which values to provide are described further down this page).
- Save the directory settings.
- If you have more than one directory configured, use the arrows to set the directory order. Directories are searched in order for users and groups. To learn more see Manage multiple authentication systems.
LDAP directory size considerations
If you are using Microsoft Active Directory or an external LDAP directory service, a background synchronization task copies the user and group details into a cache in the Hipchat application database. This cache is updated periodically. The time this process takes can vary depending on how many users, groups, and group memberships you chose to sync, as well as other factors such as network latency and database performance.
This synchronization task doesn't run if you're using an internal directory that is connected to an LDAP instance for authentication-only, or if your LDAP directories are configured with 'Authentication Only, Copy User On First Login', so these limitations do not apply.
If you're running a Hipchat Data Center deployment with a more than 5000 users, 1000 groups, or more than 20 groups per user, we recommend that you use LDAP filters to reduce the number of users and groups visible to the synchronization task.
Reduce the number of users synchronized from LDAP to Hipchat Data Center
If you connected Hipchat Data Center to an LDAP directory for authentication and user management, you may want Hipchat Data Center to synchronize a subset of users from LDAP, rather than all users. There are two reasons to make this change:
- Improve performance. If you have performance issues during the synchronization process, you might be able to improve this by synchronizing only a subset of the LDAP accounts. See this knowledge base article for more information: Performance issues with large LDAP repository in Jira server.
- Reduce your user count. If you have more people in your LDAP directory than use Hipchat Data Center, and you have a limited number of seats on your Hipchat license, you can synchronize only the subset of the directory that contains Hipchat users.
How you filter your LDAP synchronization depends on how you initially set up your LDAP directory.
- If all of your Hipchat users are in one part of the LDAP directory, and non-users are in another, you can specify which part of the directory Hipchat Data Center synchronizes.
- If you have both Hipchat users and non-Hipchat users in the same part of the LDAP directory, you will need to define an LDAP filter to synchronize the relevant users.
Synchronizing against Base DN and Additional User DN
If all of your Hipchat are users in one organizational unit in LDAP, and your non-Hipchat users are in a different organizational unit, you can tell Hipchat Data Center to only synchronize users against a particular DN (distinguished name) to exclude the non-users.
- Browse to your server's fully qualified domain name, for example https://hipchat.yourcompany.com/.
- Log into the Hipchat Data Center web user interface (UI) using your administrator email and password.
- Click User management then click the External directory tab. (If necessary, click to select the directory you want to filter.)
- Locate the LDAP Schema section.
- Update the Base DN field, and optionally the Additional User DN, to query against the directory server as desired.
For example, all of your Hipchat users are in the hipchat-users organizational unit (OU) only for your company at mycompany.example.com, your configuration would look like this:
- Base DN —
dc=mycompany,dc=example,dc=com - Additional User DN —
ou=hipchat-users
- Base DN —
Active Directory/LDAP Group objects do not currently affect Hipchat Data Center. Filtering for or against groups won't change the user list in Hipchat Data Center. See Filtering for groups to learn how to work around this limitation.
Define an LDAP filter
If you have both Hipchat users and non-Hipchat users in the same node of the LDAP tree, you will need to define an LDAP filter to synchronize the relevant users.
- Browse to your server's fully qualified domain name, for example https://hipchat.yourcompany.com/.
- Log into the Hipchat Data Center web user interface (UI) using your administrator email and password.
- Click User management then click the External directory tab. (If necessary, click to select the directory you want to filter.)
- Locate the User Schema Settings and click to expand the section if necessary.
- Enter your LDAP filter statement in the User Object Filter field.
Simple LDAP filter example
The syntax for LDAP filters is complex, and the query you use depends on the type of LDAP directory you have and how it's set up.
As an example, if only LDAP users who are in your team's office in the state of Delaware will use Hipchat, and the users who work in Delaware are identified by "st=DE" in their user attribute list, you can set the User Object Filter = (&(objectCategory=inetorgperson)(st=DE) ) to only synchronize those users.
Reduce LDAP scope by filtering for groups
Active Directory/LDAP group objects are not currently supported in Hipchat Data Center. Filtering for or against groups won't change the user list in Hipchat Data Center.
To work around this limitation, set a user object filter to check for the memberOf attribute (or a similar attribute). See the following example:
(&(objectclass=user)(sAMAAccountName=*)(|(memberOf=nested-group1)(memberOf=nested-group2)(memberOf=nested-group3)(memberOf=Parent group)))
LDAP settings fields
Server settings
Setting | Description |
|---|---|
Name | Enter a meaningful name to help you identify the LDAP directory server. Examples:
|
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:
|
Hostname | The host name of your directory server. Examples:
|
Port | The port on which your directory server is listening. Examples:
|
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 to use this setting. |
Username | The distinguished name of the user that the application will use when connecting to the directory server. Examples:
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. |
Password | 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
Setting | Description |
|---|---|
Base DN | The root distinguished name (DN) to use when running queries against the directory server. Examples:
|
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:
|
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:
|
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 a huge directory structure, could cause performance issues for login and operations that rely on login to be performed.
Permission settings
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 | Not applicable to Hipchat Data Center. |
| Read/Write | Not applicable to Hipchat Data Center. |
Advanced settings
Setting | Description |
|---|---|
Enable Nested Groups | Not applicable to Hipchat Data Center. |
| Manage User Status Locally | If 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 retrieves 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 |
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.
|
| Enable Incremental Synchronization |
Enable incremental synchronization if you only want changes since the last synchronization to be queried when synchronizing a directory. When using this option, the user account configured for synchronization must have read access to:
If one or more of these conditions is not met, you can end up with users who are added to (or deleted from) the Active Directory not being correctly added (or deleted) in the Hipchat application. |
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 sends 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.
|
This setting is only available if the directory type is set to "Microsoft Active Directory".
User schema settings
Setting | Description |
|---|---|
User Object Class | This is the name of the class used for the LDAP user object. Example:
|
User Object Filter | The filter to use when searching user objects. Example:
You can have a maximum of 4,000 characters in this field. Ensure your LDAP filters are concise. |
User Name Attribute | The attribute field to use when loading the username. Examples:
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:
|
User First Name Attribute | The attribute field to use when loading the user's first name. Example:
|
User Last Name Attribute | The attribute field to use when loading the user's last name. Example:
|
User Display Name Attribute | The attribute field to use when loading the user's full name. Example:
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:
The user will not be synchronized if this attribute is empty. Always use the attribute that contains the user email (example: |
User Password Attribute | The attribute field to use when loading a user's password. Example:
|
| 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
Group schema settings are not used in Hipchat Data Center.
Membership schema settings
The User Member Attribute is the only Membership schema setting relevant to Hipchat Data Center. All other Membership schema settings are not relevant.
| Setting | Description |
|---|---|
| User Member Attribute | Because Hipchat Data Center 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. Example:
|
Recommendations for connecting to LDAP
The following limitations and recommendations should be considered when connecting to an LDAP user directory.
Redundant LDAP is not supported
The LDAP connections do not support the configuration of two or more LDAP servers for redundancy (automated failover if one of the servers goes down).
Specific notes about connecting to Active Directory
When the application synchronizes with Active Directory (AD), the synchronization task requests only the changes from the LDAP server rather than the entire user base. This optimizes the synchronization process and gives much faster performance on the second and subsequent requests.
On the other hand, this synchronization method results in a few limitations:
- Externally moving objects out of scope or renaming objects causes problems in AD. Moving objects out of scope in AD results in an inconsistent cache. We recommend that you do not use the external LDAP directory interface in Hipchat to move objects out of the scope of the sub-tree, as defined on the application's directory configuration screen. If you do need to make structural changes to your LDAP directory, manually synchronize the directory cache after you have made the changes to ensure cache consistency.
- Synchronizing between AD servers is not supported. Microsoft Active Directory does not replicate the
uSNChangedattribute across instances. For that reason, we do not support connecting to different AD servers for synchronization. You can still define multiple different directories, each pointing to its own AD server. - Synchronizing with AD servers behind a load balancer is not supported. As with synchronizing between two different AD servers, Microsoft Active Directory does not replicate the
uSNChangedattribute across instances. For that reason, we do not support connecting to different AD servers even when they are load balanced. You will need to select one server (preferably one that is local) to synchronize with instead of using the load balancer. - You must restart the Hipchat application after restoring AD from backup. On restoring from backup of an AD server, the
uSNChangedtimestamps are reverted to the backup time. To avoid synchronization inconsistencies, flush the Hipchat directory cache after a Active Directory restore operation. - Obtaining AD object deletions may require administrator access. Active Directory stores deleted objects in a special container called
cn=Deleted Objects. By default, to access this container you need to connect as an administrator and so, for the synchronization task to be aware of deletions, you must use administrator credentials. Alternatively, you can change the permissions for thecn=Deleted Objectscontainer so that a non-admin can access it. See the related Microsoft KB Article for more information. - The User DN used to connect to AD must be able to see the uSNChanged attribute. The synchronization task relies on the
uSNChangedattribute to detect changes, and so must be in the appropriate AD security groups to see this attribute for all LDAP objects in the subtree.