Connecting to an external directory

When you connect external user directories to Hipchat Server, Hipchat Server has read-only permission to the data in these directories. The data in these directories overrides the data in Hipchat Server's internal directory.

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

On this page:

You can add as many external LDAP user directories as you need. Note that you can define the order of the directories. This determines which directory Hipchat Server will search first, when looking for user information. See Managing Multiple Directories.  

Configuring user directories in Hipchat Server

To configure your user directories:

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

  3. Choose Group admin > Authentication.

Updating directories

Limitations when editing directories

You cannot edit, disable, or remove the directory your user account belongs to. This precaution is designed to prevent administrators from locking themselves out of the application by changing the directory configuration in a way that prevents them logging in or removing their administration permissions.

This limitation applies to all directory types. For example:

  • You cannot disable the internal directory if your user account is in the internal directory.
  • You cannot disable or remove an LDAP or a Crowd directory if your user account comes from that directory.

In some situations, reordering the directories will change the directory that the current user comes from, if a user with the same username happens to exist in both. This behavior can be used in some cases to create a copy of the existing configuration, move it to the top, then remove the old one. Note, however, that duplicate usernames are not a supported configuration.

You cannot remove the internal directory. This precaution aligns with the recommendation that you always keep the group owner active in the internal directory.


The recommended way to edit external directory configurations is to log in as a user from Hipchat Server's internal directory.

We recommend that you keep the Hipchat group owner active in your internal directory for troubleshooting problems with your user directories.


Enabling, Disabling and Removing Directories

You can enable or disable a directory at any time. If you disable a directory, your configuration details will remain but the application will not recognize the users and groups in that directory.

You have to disable a directory before you can remove it. Removing a directory removes its details from the database and deactivates the users in the directory. 

Screenshot: Configuring user directories

How removing directories affects users

When you remove a directory, the directory's users are deactivated in Hipchat Server. Hipchat Server reassigns private rooms that were owned by deactivated users to the Hipchat Server 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.

Last modified on Nov 30, 2017

Was this helpful?

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