Configuring User Directories
A user directory is a place where you store information about users and groups. User information includes the person's full name, username, password, email address and other personal information. Group information includes the name of the group, the users that belong to the group, and possibly groups that belong to other groups.
The internal directory stores user information in the HipChat Server database. You can also connect to external user directories, and to Atlassian Crowd and JIRA applications as directory managers.
Email addresses are mandatory. If directory users don't have their email addresses specified, they will be skipped during synchronization. In HipChat, the directory users' full names must be in the format of First Last, otherwise they will not successfully synchronize to the server.
Group memberships in HipChat Server
There is no group structure within HipChat Server. You can use your user directory's groups to filter the users you import into the HipChat Server database. When HipChat Server imports your groups, it flattens the groups' hierarchy.
On this page:
Configuring user directories in HipChat Server
To configure your user directories:
- Browse to the fully qualified domain name you've configured for your server, for example https://hipchat.yourcompany.com.
Log into the HipChat Server web user interface (UI) using your administrator email and password.
- Choose Server admin > Directory.
Understanding HipChat Server's internal directory
The internal directory stores user information in the HipChat Server database.
The internal directory is enabled by default at installation. When you create the first administrator during the setup procedure, that administrator's username and other details are stored in the internal directory.
Diagram above: HipChat Server using its internal directory for user management.
Connecting to a directory
If needed, you can configure one or more additional user directories. This is useful if you want to grant access to users and groups that are stored in a corporate directory or other directory server. When you have additional user directories, 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:
- Microsoft Active Directory. See Connecting to an LDAP Directory.
- Various other LDAP directory servers. See Connecting to an LDAP Directory.
- Atlassian Crowd or JIRA applications. See Connecting to Crowd or JIRA Applications for User Management.
You can add as many external 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.
Updating directories
Limitations when Editing Directories
You cannot edit, disable or remove the directory your user 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 removes their administration permissions.
This limitation applies to all directory types. For example:
- You cannot disable the internal directory if your user is an internal user.
- You cannot disable or remove an LDAP or a Crowd directory if your user 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 behaviour 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 below that you always keep an administrator account active in the internal directory.
Recommendations
The recommended way to edit directory configurations is to log in as an internal user when making changes to external directory configuration.
We recommend that you keep either an administrator or system administrator user 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 recognise the users and groups in that directory.
You have to disable a directory before you can remove it. Removing a directory will remove the details from the database.
Screenshot: Configuring user directories
