Configure LDAP | Couchbase Docs (original) (raw)

To configure LDAP, access the Security panel, by means of the entry in the left-hand navigation bar:

securityTab

This brings up the Security screen. Note the options at the upper right:

ldapAndGroupsTabs

The LDAP tab allows an LDAP server to be specified for external authentication. The ADD GROUP tab allows definition of Couchbase-Server user-groups; which are to be associated with LDAP groups, and which can be assigned Couchbase-Server roles. The ADD USER tab allows individual users to be added, and allows their authentication optionally to be specified as external.

To perform LDAP configuration, left-click on the LDAP tab, at the upper right of the Security screen:

leftClickOnLdapTab

This brings up the LDAP Configuration dialog:

configureLDAP2

The dialog presents two main panels. The vertically scrollable right panel features help text, for LDAP Host Configuration, User Authentication, and Group Authorization. The left panel features options whereby LDAP can be configured.

The fields of the left panel are presented in three principal areas, each corresponding to a key aspect of LDAP configuration:

Each of these areas is described below.

LDAP Host Configuration

The upper area of the left panel of the LDAP Configuration dialog displays the following fields:

Once all appropriate settings have been made to LDAP Host(s), Encryption, Certificate, and Contact LDAP host fields, optionally, the Check Network Settings button can be left-clicked on. This tests whether a specified LDAP host can be accessed by the specified means. If no such access is possible, an error is displayed on the dialog.

User Authentication Enablement

When you turn on the Enable LDAP user authentication toggle, several fields appear that let you enable LDAP authentication.

configureLdapEnableLdapUserAuthField

When enabled, Couchbase Server authenticates users who are not local users with the configured LDAP Hosts.

You have three options for how Couchbase Server maps the username in an authentication attempt to an LDAP Distinguished Names (DN). These options are explained in the following sections.

Template

The default option is Template. Enter a username-to-DN mapping template string into the Template text field. Directly providing the mapping avoids requiring the LDAP server itself provide the mapping itself. The field shows the format for the template string as placeholder text.

The username supplied to Couchbase Server by the user who’s attempting to authenticate replaces the %u in the template. For example, if the template is cn=%u,dc=example,dc=com and the user logs in as exampleUser, the template maps the user to the DN cn=exampleUser,dc=example,dc=com.

Selecting LDAP Search displays the following:

ldapQuery

You use the three fields to define an LDAP search operation to get the user’s DN from LDAP server.

Advanced Query

The Advanced Query option lets you supply a list of regular expressions that Couchbase Server tests against the username. For each regular expression you also supply a replacement string that Couchbase Server uses to insert portions of the username into a DN or LDAP query. When you select the Advanced Query option, a Template text edit box appears for you to enter your list.

ldapAdvancedQuery

You enter your regular expressions and replacement strings as a JSON list. The list contains objects, each of which must have a match key containing the regular expression. The object must also contain either a substitution key that defines a DN string or a ldapQuery key that defines an LDAP query. In either case, these strings should contain back references to capture expressions in the regular expression to extract parts of the username.

For example, the following template has two regular expressions. The first attempts to extract the address and domain name from an email address. If this regular expression matches, Couchbase Server uses the address as the user ID and the domain name as the organization unit in a DN. The second regular expression captures the entire username and passes that as an LDAP query in the people organizational unit.

[
{
    "match": "([^@]+)@(.+)\\.com",
    "substitution": "cn={0},ou={1},dc=example,dc=com"
},
{
    "match": "(.*)",
    "ldapQuery": "ou=people,dc=example,dc=com??one?(uid={0})"
}
]

| | Always double any backslashes (\) that you use to escape special characters in your regular expressions because JSON also interprets backslash escapes. | | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |

Couchbase Server attempts to match the regular expressions against the username supplied by the user who’s attempting to authenticate. If a regular expression matches the username, Couchbase Server applies any captured portions of the regular expression to the back references in the replacement string. Then it attempts to authenticate the user with LDAP using the DN or LDAP query.

If the authentication fails, Couchbase Server returns an authentication error. It does not attempt match any further regular expressions in the list. This behavior makes the order of the regular expressions in the list important. Always place more specific regular expressions before general ones. In the previous example, the regular expression to matching an email address comes before the general catch all regular expression that matches any username.

The Save LDAP Configuration button has no effect if your template contains invalid JSON or an invalid regular expression. Errors in the replacement strings only appear when you try to authenticate a user. Use the Test User Authentication section to verify that your regular expressions and replacement strings work the way you intend.

Testing User Authentication

Test User Authentication, when opened, provides options for testing the authentication of specific users:

testUserAuth

Enter the username and password for the user, and left-click Test User Authentication. Couchbase Server maps the specified username to an LDAP DN, and performs authentication on the LDAP server. Notifications confirming success or failure duly appear on the dialog.

In the area immediately below that used for User Authentication Enablement, fields for enabling LDAP Group Support can be made visible by means of the Enable LDAP group authorization & sync switch. Enablement means that when a user has been authenticated by the LDAP Hosts(s), Couchbase Server retrieves the LDAP group membership information for that user, in order to authorize them. In each case where an LDAP group has been mapped to a Couchbase-Server user-group, the user is granted the privileges corresponding to the roles assigned that user-group.

Switch on, to enable. This expands the dialog vertically, as follows:

configureLDAPgroupsPanel

The LDAP groups of which a user is a member can be searched for by means of either the User’s attributes or an LDAP Search, each of which is provided as a radio-button option. Selection of either reveals a corresponding set of fields, in which information can be added. These are as follows.

User’s Attributes

The User’s attributes radio-button is selected by default. This instructs Couchbase Server to assume that each LDAP user-record contains an attribute featuring the list of groups of which the user is a member. Couchbase Server therefore performs the following LDAP search: <userDN>?<attribute>?one.

The value of the specified attribute is treated as a list of groups. For example, if attribute is set in the User Attribute field to memberOf, Couchbase Server performs the following search for the specified user’s groups:uid=exampleUser,dc=example,dc=com?memberOf?one.

The Traverse nested groups checkbox, when checked, allows nested groups to be traversed by the search. Couchbase Server uses the same search to find groups of groups recursively (with each group’s DN being substituted for %D). If nested search is selected, %u cannot be used.

Note that use of nested groups may significantly increase load on the LDAP server; and should therefore only be used if essential.

Test Groups Query permits a query to be tested for a specific user. Left-click to open:

testGroupsQuery

To perform the search, add a username, and left-click on the Test Groups Query button. Notifications confirming success or failure appear on the dialog.

LDAP Search

When the LDAP Search radio-button is selected, the Query for Groups Using panel appears as follows:

ldapConfigurationLDAPquery

Selection of LDAP Search instructs Couchbase Server to perform an LDAP search operation, in order to retrieve a list of the user’s groups.Base is the search base DN.Filter is the search filter.Scope, accessed from a pulldown menu, can be base, one (the default), or sub.

When the search is conducted, %u is replaced with the specified username; and %D is replaced with the user’s DN. For example, Base might be specified as ou=groups,dc=example,dc=com, Filter as (member=%D), and Scope as one-level:

ldapQueryDetail

See the description provided above, inTraverse Nested Groups, for User Attribute Search

See the description provided above, in Test Groups Query, for User Attribute Search

Advanced Settings

It is strongly recommended that the Advanced Settings not be changed; except in unusual circumstances, and in accordance with expert advice. Inappropriate settings may seriously impair system responsiveness.

Left-click to open:

addLdapDialogAdvancedSettings

The advanced settings are as follows:

When all required data has been entered, left-click on the Save LDAP Configuration button, at the bottom right:

configureLDAPdialogSaveButton

Alternatively, left-click on Cancel to abandon the configuration procedure.

Clearing the Cache

The Clear Cache button is located at the lower left of the LDAP Configuration dialog:

clearLDAPcacheButton

Couchbase Server caches authentication responses and group-search results, thereby minimizing the number of requests to be made on the LDAP server. Each cached value is expired after a configured time-period (controlled by the Cache Time-to-Live ms value, provided in the Advanced Settings panel). Additionally, the Clear Cache button is provided, so that all currently cached values can be explicitly removed: each subsequent authentication or group request is, on its first instance following the removal, passed to the LDAP server; and the latest values established on the LDAP server are thereby retrieved.

Map LDAP Groups to Couchbase-Server Roles

To map an LDAP group to Couchbase-Server roles, create a Couchbase-Server user-group; associate the user-group with the LDAP group; and then assign roles to the user-group.

(Note that each Couchbase-Server user-group can be associated with at most one LDAP group — although if that LDAP group itself incorporates multiple additional LDAP groups by means of LDAP-group nesting, an indirect association with those LDAP groups occurs.)

Left-click on the ADD GROUP tab, at the upper right of the Users & Groups panel, on the Security screen:

addGroupTab3

This brings up the Add New Group dialog:

addNewGroupDialog

The fields are as follows:

With appropriate data added, the dialog might appear as follows:

addNewGroupDialogComplete

This creates a group named Admins, and assigns the Full Admin role to it, specifying as its LDAP-group mapping uid=cbadmins,ou=groups,dc=example,dc=com.

To save the group, left-click on the Save button, at the lower right.

addNewGroupSaveButton

Alternatively, left-click on Cancel to abandon group configuration.

Editing a Group Mapping

Once a group-mapping has been defined, it can be edited.

Access the Users & Groups panel of the Security screen. By default, this presents a users view, listing the currently defined users for the cluster. To display the groups view, left-click on the Groups tab, towards the upper right:

usersAndGroupsSelectGroups

This brings up the groups view, which shows currently defined user-groups for the cluster.

usersAndGroupsGroupsView

This confirms the existence of the user-group Admins.

Now, left-click on the row displayed for this group. The row expands vertically, and exposes additional controls:

expandedGroupRow

Left-click on the Edit button, at the lower right:

editGroupRowButton

This brings up the Edit Group Admins dialog:

editGroupAdmins

Within this dialog, the description, mapping, or roles for the group can be edited. For details of selecting roles within the Roles panel, see Manage Users, Groups, and Roles.

Note that if the Delete Group button is left-clicked on, the group is deleted. This means that all mappings between LDAP groups and the roles that were assigned to this group are also deleted.

Adding an Externally Authenticated User

Couchbase-Server users can be specified as externally authenticated, when they are added to the system. This allows roles to be assigned to them on the cluster; either directly, or by means of group-membership, or both. Additionally, if one or more LDAP group-mappings have been defined for LDAP groups of which the externally authenticated user is a member, the user is recognized as a member of the Couchbase-Server user-groups to which the mappings have been made, and is thereby assigned still more roles.