Connect to external user directories


Hipchat Data Center has read-only access to external user directories you connect it to, and caches a copy of the profile information locally. (Hipchat does not store user passwords.) The data in these external directories overrides the data in Hipchat Data Center's internal directory.

You can add the following types of directory servers and directory managers:

You can add as many external LDAP user directories as you need. Note that you can also change the order of the directories. This determines which directory Hipchat Data Center searches first when looking for user information. See Managing multiple authentication systems.

Email addresses in directories

Email addresses are unique identifiers in Hipchat Data Center. For best results:

  • Avoid duplicate email addresses and usernames across user directories.
    If you're connecting to more than one user directory, email addresses (and usernames) should be unique across all directories.
  • Remember that emails and usernames are not case-sensitive. For example, and are considered the same address and a duplicate. When in doubt, use all lowercase.

Change user directories in Hipchat Data Center

You can change how your user directories are configured, change their order, and disable and enable them from the Hipchat Data Center admin UI.

  1. Browse to the fully qualified domain name you've configured for your server, for example
  2. Log into the Hipchat Data Center web user interface (UI) using your administrator email and password. 

  3. Choose User management > External directory.

Enabling, disabling, and removing directories

You can enable or disable an external directory at any time (as long as it is not the source of your user account). When you disable a directory, the directory's configuration details are saved, but Hipchat no longer recognizes the users and groups that were sourced from that directory.

If you want to remove a directory, you must first disable it. Removing a directory removes its details from the database, and deactivates the users in the directory. (The users are retained to save the chat history.)

When you remove a directory, the directory's users are deactivated in Hipchat Data Center. Hipchat Data Center reassigns private rooms that were owned by deactivated users to the Hipchat Data Center group owner. If you enable the directory again, you'll need to reassign the private rooms to the users and invite them to any private rooms they were members of.

Limitations when removing and disabling directories

You cannot remove the internal directory. This prevents you from removing or disabling the group Owner, who is always stored in the internal directory.

You cannot edit, disable, or remove the directory your user account belongs to, regardless of which directory type your account is sourced from. This prevents administrators from locking themselves out of the application.

tip/resting Created with Sketch.

The best way to edit external directory configurations is to log in as a user from Hipchat Data Center's internal directory, which cannot be removed. (This means that users in the Hipchat internal directory cannot be locked out accidentally.)

We recommend that you keep the Hipchat team Owner active in your internal directory, and use this account for troubleshooting problems with user directories.

Managing multiple authentication systems

When you connect Hipchat Data Center to multiple directory servers, you need to define the order in which Hipchat Data Center searches the directories for users.

Avoid duplicate usernames and email addresses across directories.

If you're connecting to more than one user directory, usernames and email addresses must be unique across all directories. For example, having the email address,, in two directories can cause confusion, especially if you swap the order of the directories. Changing the directory order can change the user that a given email address refers to.


You can change the order of your directories as defined to Hipchat Data Center. Log in to the Hipchat Data Center admin UI, and click User management > External directory. From that page, click the blue up and down arrows next to each directory. Hipchat Data Center searches the directories in the order you specify, with the top being the first directory searched.

The directory order can significantly impact user login time if the same user exists in multiple directories. When such a user attempts logs in, Hipchat Data Center searches the directories in the order specified, and validates the user login attempt against the first occurrence of the user.

Considerations when changing the directory order

Avoid duplicate usernames and email addresses whenever possible, as they can cause confusion and login trouble. For example, if the email address  is in two directories with two different passwords, and you change the order of the directories, the user associated with that address won't know which password to use. Changing the directory order can also change the user details that an email address refers to.

If a user with the same username exists in two directories, reordering the directories can change the directory that the current user comes from. You can use this behavior to create a copy of the existing configuration, move it to the top, then remove the old one. However, leaving multiple directories with duplicate usernames is not supported.

Troubleshooting and logs

The following Hipchat Data Center log files are related to user directories:

/var/log/hipchat/coral.logManages REST API calls that are used during authentication of a user
/var/log/hipchat/atlassian-crowd.logContains records of connections to external directories, synchronization events of the directories and their users, and user authentication
  • Contains full process outputs (ps) at one-hour intervals
  • Useful for verifying if a service was up during authentication

To learn more about all the logs used in Hipchat, and how to produce a log bundle for Support, see Troubleshooting Hipchat Data Center.

Last modified on Nov 30, 2017

Was this helpful?

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