So far we have learned how to get users into our Confluence installation. This is very useful but what if your company has its own LDAP server or is already using some other Atlassian products, such as JIRA or Crowd?
Within Confluence we can configure one or more external user directories. A user directory is a place where you store information about users and groups, including some other user information. This information can be the person's full name, e-mail address, or department. When an external user directory is configured, Confluence will also use the directory to authenticate a user.
Confluence has support for the following external directories:
- Microsoft Active Directory
- Various LDAP directory servers including OpenLDAP, Apache Directory Server, and Novell eDirectory
- Atlassian Crowd
- Atlassian JIRA
You can add as many external directories as you need. Note that you can change the order of the directories, determining which directory will search first.
When you have more than one directory configured, the order of those directories is important and affects a couple of things within Confluence.
- Login: The directory order is significant during the authentication of the user, especially if the user exists in multiple directories. During login, the application will search the directories in the specified order, and will use the password of the first occurrence of the user to validate the login.
- Permissions: In the same way as the login mechanism, Confluence will look for group memberships only in the first directory where the username appears, based on the directory order.
For example:
- You have two directories: the employees directory and the customers directory
- The employee directory is first in the directory order
- A username
arthur.dentexists in both directories - The user
arthur.dentis a member of group G1 in the employees directory and group G2 in the customers directory - Based on directory order, the user
arthur.dentonly has permissions based on group G1, not G2
- Updating users and groups: If you update a user or group via Confluence's administration screen, the update will only be made in the first directory where Confluence has write permissions.
For example:
- You have two user directories: a read/write LDAP directory and the internal directory
- The LDAP directory is the first directory
- A username
arthur.dentexists in both directories - You update the e-mail address of the user
arthur.dentvia Confluence's Administration Console - The e-mail address will only be updated in the LDAP directory, not in the internal directory
When using external directories, there are a couple of limitations you should be aware of.
The first limitation you should be aware of depends on the read/write configuration of your external directory. If Confluence can't write to your external directory, or you don't want it to, you have to disable the built-in user management.
To disable management of users and groups within Confluence:
- Browse to the Administration Console (Administration | Confluence Admin).
- Choose Security Configuration in the left-hand menu.
- Click on Edit.
- Check the External user management checkbox.
- Click on Save.
If the built-in user management is disabled, users won't be able to:
- Signup
- Reset their password
- Update their profile
Also, administrators won't be able to:
- Add new users and groups
- Assign users to groups from Confluence
All these features are now delegated to the administration of your external user management and they have to be performed there.
It's not possible to edit, disable, or remove the directory your user belongs to. This precaution is to prevent administrators from locking themselves out of the Confluence, by changing the directory configuration in a way that prevents them from logging in or removing their administration permissions.
In some cases, reordering the directories will change the directory that you're currently using, if your user exists in both directories. This behavior can be used to make changes to existing directories.
Connecting to an LDAP directory server is useful if your users and groups are stored in a corporate directory. When configuring the LDAP directory in Confluence, you can choose to make it Read Only, Read Only with Local Groups, or Read/Write. In the last case, any changes you make to your users and groups in Confluence will reflect in your LDAP directory.
To connect Confluence to an LDAP directory, perform the following steps:
- Browse to the Administration Console (Administration | Confluence Admin).
- Choose User Directories in the left-hand menu.
- Click on Add Directory. Select one of these types and click on Next:
- Microsoft Active Directory: This option provides a quick way to add an AD directory, as it is one of the popular choices.
- LDAP: You will be able to choose a more specific LDAP directory type on the next screen.
- Enter the values for the required settings as described in the following table.
- Save the directory settings.
The following are the different settings required for setting up an external user directory:
|
Setting |
Description |
|---|---|
|
Name |
Enter a descriptive name that will help you identify the LDAP server. For example, |
|
Directory Type |
Select the type of LDAP server you will connect to. The value you select here will determine the default values for many options on the screen. |
|
Hostname |
The hostname of your directory server. |
|
Port |
The port on which your directory server is listening. For example, 389 (default LDAP port), 10398, or 636 (LDAP over SSL). |
|
Use SSL |
Check this checkbox if the connection to your LDAP server is an SSL connection. |
|
Username |
The distinguished name of the user that the application will use when connecting to the directory server. For example:
|
|
Password |
The password of the user specified. |
Note
The Read Only, with Local Groups option is a very powerful configuration and is in many cases the best setup. Users and groups can still be managed in your company's centralized user management system. But you as an administrator still have the option to create new groups and change memberships of those groups, giving you the control you need in Confluence without cluttering your LDAP server. ines
Atlassian Crowd is an application security framework that can handle the authentication and authorization for your web-based applications, which is not just restricted to Confluence or JIRA. With Crowd, it's possible to integrate multiple user directories into one directory and add support for single sign-on and centralized identity management.
Crowd is a very useful option if you have multiple web-based applications and multiple user directories you want to configure, especially if you want to add SSO to those applications as well.
Use the following steps to connect to Crowd:
- Go to your Crowd Administration Console and define Confluence as an application. More information about this step can be found at https://confluence.atlassian.com/x/rQcD.
- Browse to the Administration Console (Administration | Confluence Admin).
- Choose User Directories in the left-hand menu.
- Click on Add Directory and select the Atlassian Crowd option.
- Enter the value for the settings (explained in the following table).
- Save the directory settings.
If you are also running JIRA within your organization, it is possible to use JIRA as user management for Confluence. The advantage of this approach is that your user management system is not in multiple locations, but just in JIRA.
The method of connecting Confluence to JIRA changed in JIRA 4.3 and later. I will assume you will be using JIRA 4.3 or later for this exercise; if you are running an older version of JIRA, you will find more information online at https://confluence.atlassian.com/x/hg6zDQ.
To connect Confluence to JIRA 4.3 or later, perform the following steps:
- Go to your JIRA administration screen and define the Confluence application to JIRA, using the following steps:
- For JIRA 4.3.x, select Other Applications from the Users, Groups & Roles section of the Administration menu.
- For JIRA 4.4 or later, select Users | JIRA User Server in the administration mode.
- Click on Add Application.
- Enter the application name and password that Confluence will use when accessing JIRA.
- Enter the IP address or addresses of your Confluence server, for example,
192.168.10.42. - Save the new application.
- Set up Confluence to use a JIRA user directory, using the following steps:
- Browse to the Administration Console (Administration | Confluence Admin).
- Choose User Directories in the left-hand menu.
- Click on Add Directory and select the Atlassian JIRA option.
- Enter the value for the settings (explained in the following table).
- Save the directory settings.
- Make sure the Confluence groups are available in JIRA by performing the following steps:
- Add the confluence-users and confluence-administrators groups in JIRA.
- Add your own username as a member of both groups.
|
Settings |
Description |
|---|---|
|
Name |
A descriptive name of your JIRA server. For example:
|
|
Server URL |
The web address of your JIRA server. Examples:
|
|
Application Name |
The name to authenticate Confluence with JIRA. This is the application name you created when setting up JIRA for Confluence. |
|
Application Password |
The password for the configured application name. This must be the same as the password you have registered in JIRA for Confluence. |