Connecting to an Internal Directory with LDAP Authentication

You can connect your Confluence application to an LDAP directory for delegated authentication. This means that Confluence will have an internal directory that uses LDAP for authentication only. There is an option to create users in the internal directory automatically when they attempt to log in, as described in the settings section.

Overview

An internal directory with LDAP authentication offers the features of an internal directory while allowing you to store and check users' passwords in LDAP only. Note that the 'internal directory with LDAP authentication' is separate from the default 'internal directory'. On LDAP, all that the application does is to check the password. The LDAP connection is read only. Every user in the internal directory with LDAP authentication must map to a user on LDAP, otherwise they cannot log in.

When to use this option: Choose this option if you want to set up a user and group configuration within your application that suits your needs, while checking your users' passwords against the corporate LDAP directory. This option also helps to avoid the performance issues that may result from downloading large numbers of groups from LDAP.

On this page:

Related pages:

Configuring User Directories

Connecting Confluence to an Internal Directory with LDAP Authentication

To connect to an internal directory but check logins via LDAP:

  1. Select Administration , then select General Configuration
  2. Click 'User Directories' in the left-hand panel.
  3. Add a directory and select type 'Internal with LDAP Authentication'.
  4. Enter the values for the settings, as described below.
  5. Save the directory settings.
  6. If you want LDAP users to be used in place of existing internal users, move the 'Internal with LDAP Authentication' directory to the top of the list. You can define the directory order by clicking the blue up- and down-arrows next to each directory on the 'User Directories' screen. Here is a summary of how the directory order affects the processing:
    • Changes to users and groups will be made only in the first directory where the application has permission to make changes.
    • The order of the directories is the order in which they will be searched for users and groups (by default Confluence aggregates group membership from all directories, so the order does not impact membership itself).
    For details see Managing Multiple Directories.
  7. Add your users and groups in Confluence. See Add and Invite Users and Managing Site-Wide Permissions and Groups .

Server Settings

Setting

Description

Name

A descriptive name that will help you to identify the directory. Examples:

  • Internal directory with LDAP Authentication
  • Corporate LDAP for Authentication Only

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 some of the options on the rest of screen. Examples:

  • Microsoft Active Directory
  • OpenDS
  • And more.

Hostname

The host name of your directory server. Examples:

  • ad.example.com
  • ldap.example.com
  • opends.example.com

Port

The port on which your directory server is listening. Examples:

  • 389
  • 10389
  • 636 (for example, for SSL)

Use SSL

Check this box if the connection to the directory server is an SSL (Secure Sockets Layer) connection. Note that you will need to configure an SSL certificate in order to use this setting.

Username

The distinguished name of the user that the application will use when connecting to the directory server. Examples:

  • cn=administrator,cn=users,dc=ad,dc=example,dc=com
  • cn=user,dc=domain,dc=name
  • user@domain.name

Password

The password of the user specified above.

Copying Users on Login

Setting

Description

Copy User on Login

This option affects what will happen when a user attempts to log in. If this box is checked, the user will be created automatically in the internal directory that is using LDAP for authentication when the user first logs in and their details will be synchronized on each subsequent log in. If this box is not checked, the user's login will fail if the user wasn't already manually created in the directory.

If you check this box the following additional fields will appear on the screen, which are described in more detail below:

  • Default Group Memberships
  • Synchronize Group Memberships
  • User Schema Settings (described in a separate section below)

Update User attributes on Login

Whenever your users authenticate to the application, their attributes will be automatically updated from the LDAP server into the application. After you select this option, you won't be able to modify or delete your users directly in the application.

  • If you need to modify a user, do it on the LDAP server; it will be updated in the application after authenticating.
  • If you need to delete a user, do it on the LDAP server, but also in the application. If you delete the user only on the LDAP server, it will be rejected from logging in to the application, but it won't be set as inactive, which will affect your license. You'll need to disable the Update User attributes on Login option to delete the user, and then enable it again.

Default Group Memberships

This field appears if you check the Copy User on Login box. If you would like users to be automatically added to a group or groups, enter the group name(s) here. To specify more than one group, separate the group names with commas. Each time a user logs in, their group memberships will be checked. If the user does not belong to the specified group(s), their username will be added to the group(s). If a group does not yet exist, it will be added to the internal directory that is using LDAP for authentication.

Please note that there is no validation of the group names. If you mis-type the group name, authorization failures will result – users will not be able to access the applications or functionality based on the intended group name.

Examples:

  • confluence-users
  • bamboo-users,jira-administrators,jira-core-users

Synchronize Group Memberships

This field appears if you select the Copy User on Login checkbox. If this box is checked, group memberships specified on your LDAP server will be synchronized with the internal directory each time the user logs in.

If you check this box the following additional fields will appear on the screen, both described in more detail below:

  • Group Schema Settings (described in a separate section below)
  • Membership Schema Settings (described in a separate section below)

Note: 'Copy Users on Login' must be enabled if you want to be able to change usernames.

Schema Settings

Setting

Description

Base DN

The root distinguished name (DN) to use when running queries against the directory server. Examples:

  • o=example,c=com
  • cn=users,dc=ad,dc=example,dc=com
  • For Microsoft Active Directory, specify the base DN in the following format: dc=domain1,dc=local. You will need to replace the domain1 and local for your specific configuration. Microsoft Server provides a tool called ldp.exe which is useful for finding out and configuring the the LDAP structure of your server.

User Name Attribute

The attribute field to use when loading the username. Examples:

  • cn
  • sAMAccountName

Advanced Settings

Setting

Description

Enable Nested GroupsEnable or disable support for nested groups.
Some directory servers allow you to define a group as a member of another group. Groups in such a structure are called nested groups. Nested groups simplify permissions by allowing sub-groups to inherit permissions from a parent group.

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 will retrieve 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 java.naming.referral) configuration setting. It is generally needed for Active Directory servers configured without proper DNS, to prevent a 'javax.naming.PartialResultException: Unprocessed Continuation Reference(s)' error.

User Schema Settings

Note: this section is only visible when Copy User on Login is enabled.

Setting

Description

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:

  • ou=Users

User Object Class

This is the name of the class used for the LDAP user object. Example:

  • user

User Object Filter

The filter to use when searching user objects. Example:

  • (&(objectCategory=Person)(sAMAccountName=*))

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:

  • cn

User First Name Attribute

The attribute field to use when loading the user's first name. Example:

  • givenName

User Last Name Attribute

The attribute field to use when loading the user's last name. Example:

  • sn

User Display Name Attribute

The attribute field to use when loading the user's full name. Example:

  • displayName

User Email Attribute

The attribute field to use when loading the user's email address. Example:

  • mail

Group Schema Settings

Note: this section is only visible when both Copy User on Login and Synchronize Group Memberships are enabled.

Setting

Description

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:

  • ou=Groups

Group Object Class

This is the name of the class used for the LDAP group object. Examples:

  • groupOfUniqueNames
  • group

Group Object Filter

The filter to use when searching group objects. Example:

  • (objectCategory=Group)

Group Name Attribute

The attribute field to use when loading the group's name. Example:

  • cn

Group Description Attribute

The attribute field to use when loading the group's description. Example:

  • description

Membership Schema Settings

Note: this section is only visible when both Copy User on Login and Synchronize Group Memberships are enabled.

Setting

Description

Group Members Attribute

The attribute field to use when loading the group's members. Example:

  • member

User Membership Attribute

The attribute field to use when loading the user's groups. Example:

  • memberOf

Use the User Membership Attribute, when finding the user's group membership

Check this box if your directory server supports the group membership attribute on the user. (By default, this is the 'memberOf' attribute.)

  • If this box is checked, your application will use the group membership attribute on the user when retrieving the members of a given group. This will result in a more efficient retrieval.
  • If this box is not checked, your application will use the members attribute on the group ('member' by default) for the search.

Diagrams of Possible Configurations

Gliffy-Confluence-LDAP-Auth-Only

Diagram above: Confluence connecting to an LDAP directory for authentication only.

Gliffy-Confluence-LDAP-Copy-On-First-Login

Diagram above: Confluence connecting to an LDAP directory for authentication only, with each user synchronized with the internal directory that is using LDAP authentication when they log in to Confluence.

Last modified on Feb 21, 2023

Was this helpful?

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