Please use the form below to provide your feedback. Because your feedback is valuable to us, the information you submit in this form is recorded in our issue tracking system (JIRA), which is publicly available. You can track the status of your feedback using the ticket number displayed in the dialog once you submit the form.

A newer version of this documentation is available.

View Latest

Authentication Domains

      +
      To access Couchbase Server, users must be authenticated: this can occur in either the local or the external authentication domain.

      Understanding Authentication Domains

      Couchbase Server authenticates each user by means of one of two authentication domains. The domains are:

      • Local: Contains users defined locally. This includes:

        • The Full Administrator for Couchbase Server.

        • Locally Defined Users, which are explicitly created by a Couchbase Server administrator; and each feature a username and password unique within the Local domain.

        • Internal Components within Couchbase Server that support core functionality (for example, indexing, searching, and replicating), and run with full administrative privileges.

        • Generated Users, which are created by Couchbase Server as part of the upgrade process from pre-5.0 to 5.0 and post-5.0 versions; each in correspondence with a legacy bucket. Each Generated User is assigned a username that is identical to the bucket-name; and either a password that is identical to the bucket’s pre-5.0 password, or no password, if the bucket did not feature a password. Generated Users are created to ensure that legacy applications can continue to access legacy buckets after upgrade to 5.0 or post-5.0, with the same username-password combination being used for authentication.

      • External: Contains either or both of the following:

        • Users that are explicitly registered on Couchbase Server as external; as supported either by LDAP or PAM. Usernames and passwords are defined and stored remotely; with the usernames also stored on Couchbase Server. Note that external usernames do not clash with local usernames.

        • Users that are not defined or registered on Couchbase Server in any way, and are defined entirely on LDAP. In this case, Native LDAP Support must have been used to configure Couchbase Server’s access to LDAP, with LDAP Group Support enabled. If one or more of the user’s LDAP Groups has been mapped to a corresponding Couchbase-Server user-group, the user can be authenticated on the LDAP server, and then be granted the roles assigned to each of the user-groups to which a mapping has been made.

      When a user attempts to authenticate, Couchbase Server always looks up their credentials in the same order: which is Local first, and External second.

      LDAP-Based Authentication

      LDAP-based authentication must be set up in one of the following ways;

      • Native LDAP Support. For Couchbase Server Enterprise Edition 6.5+, this is the recommended way of setting up LDAP for external authentication. It provides support for encrypted communication, and for LDAP groups.

      • LDAP Support Based on saslauthd. saslauthd is maintained for support of legacy LDAP authentication, as established on pre-6.5 versions of Couchbase Server. (Note that saslauthd also provides support of legacy PAM-based authentication.) Migration to Native LDAP is recommended, so that LDAP Group Support becomes available.

      Note that either Native LDAP Support or saslauthd must be selected for the cluster. The two cannot be used simultaneously.

      Native LDAP Support

      Native LDAP Support is available only for the Enterprise Edition of Couchbase Server. Note that it can only be used when all nodes in the cluster have been upgraded to a version equal to or later than Couchbase Server Enterprise Edition 6.5.

      Couchbase Server is designed to interoperate with OpenLDAP software, which can be downloaded from the openldap.org website. Couchbase Server also supports Active Directory.

      Native LDAP Benefits

      Authenticating with Native LDAP provides the benefits of:

      • Centralized identity and security-policy management, on the LDAP server.

      • LDAP groups, which are recognized by Couchbase Server. These provide simplified user-administration, allowing Couchbase Server-privileges to be assigned by group, rather than just by user. See LDAP Groups, below.

      • Cross-platform support. Native LDAP authentication can be used for clusters running on any Couchbase-Server supported operating system. (This contrasts with saslauthd, which runs only on Linux.)

      Couchbase Server allows Native LDAP to be configured by means of the UI; or by means of the setting-ldap CLI command.

      LDAP Groups

      LDAP allows users to be members of LDAP Groups. When a user authenticates with LDAP, a list of the user’s LDAP groups is returned to Couchbase Server. If an LDAP group has previously been mapped to a Couchbase-Server group, the user inherits the roles assigned to the Couchbase-Server group. Note that LDAP Groups thus allow users not registered on Couchbase Server — even as external — to be authorized.

      Native LDAP Authentication and Authorization Sequence

      In cases where the specified username does not match against the list of locally defined users, if Native LDAP Support has been configured, Couchbase Server attempts to authenticate and authorize the user by means of LDAP. First, the authentication sequence is performed:

      1. If LDAP User Authentication has been enabled, Couchbase Server calculates an LDAP Distinguished Name (DN) for the user, whereby the user can be authenticated on the LDAP server. This makes use of the user-specified password and a template or query, which has been preconfigured: for examples of how to configure templates and queries, see User Authentication Enablement.

      2. Couchbase Server contacts the LDAP server, and attempts to authenticate the user, using the DN that has been calculated, and the user-specified password.

      3. Couchbase Server receives confirmation from the LDAP server either that authentication has succeeded (meaning that the user exists, and has submitted the correct password), or that it has failed. If authentication has failed, the authentication-process is thereby concluded, the user is not granted access to Couchbase Server, and no further action is taken.

      If authentication has succeeded, the authentication-process is thereby concluded; and Couchbase Server next proceeds to determine whether and in what ways the user is authorized on Couchbase Server.

      1. Couchbase Server checks whether an external user, with the specified username, has previously been added to Couchbase Server. If such an external user is located, Couchbase Server determines which roles have been assigned to the user: first, it checks for roles that have been directly assigned to the user; and secondly, it checks for roles assigned to the user by means of group membership. (For information on granting roles to users directly and by means of groups, see Manage Users, Groups, and Roles.) The user is granted the privileges that correspond to each of their assigned roles.

      2. If LDAP Group Support has been enabled, Couchbase Server again contacts the LDAP server: this time, in order to retrieve a list of the LDAP groups of which the user is a member. Note that this step is performed irrespective of whether the user has been determined to be an external user on Couchbase Server. See Group Authorization Enablement, for detailed information on configuring LDAP Group Support.

      3. Couchbase Server determines whether one or more of the user’s LDAP groups have been mapped to existing Couchbase-Server user-groups. Wherever a mapping exists, the user is granted (in addition to whatever privileges they may have already been granted as an external user) the privileges that correspond to all roles assigned to the Couchbase-Server user-group. (For information on mapping LDAP groups to Couchbase-Server user-groups, see Map LDAP Groups to Couchbase-Server Roles.)

        If any granted privilege supports the user’s intended action, the action is permitted; otherwise, the action is prohibited.

      For detailed, step-by-step accounts of how to configure these procedures, see Configure LDAP.

      LDAP: Users and Applications

      LDAP provides a convenient way of managing authentication and authorization for human users. However, LDAP may be less appropriate for the authentication and authorization of application identities. This is because:

      • Couchbase Server must access the LDAP server for initial authentication; thereby adding a potentially undesirable latency to the application’s establishment of a full connection with Couchbase Server.

      • If the LDAP server is unavailable, the application cannot be authenticated or authorized. In such circumstances, Couchbase Server, even though it may itself still be available, cannot grant data-access to the application.

      Therefore, to avoid both latency and risk of unavailability, applications should authenticate and authorize with Couchbase Server locally.

      saslauthd, LDAP, and PAM

      saslauthd is maintained for support of legacy LDAP and PAM-based authentication, as established on pre-6.5 versions of Couchbase Server. Migration to Native LDAP is recommended, so that LDAP Group Support becomes available. The overall migration procedure is provided as part of the saslauthd documentation, in Migrating from saslauthd to Native LDAP.

      saslauthd and LDAP

      LDAP authentication based on saslauthd is only available for the Enterprise Edition of Couchbase Server, and only on the Linux platform. It provides the benefits of centralized identity and security-policy management, and of simplified compliance. It does not support LDAP groups.

      For LDAP authentication, Native LDAP , rather than saslauthd, is recommended for Couchbase Server Enterprise Edition 6.5+.

      For details on configuring saslauthd to support external authentication by LDAP, see Configure saslauthd.

      saslauthd and PAM

      Pluggable Authentication Modules (PAM) provide an authentication framework that allows multiple, low-level authentication schemes to be used by a single API. The Enterprise Edition of Couchbase Server, running on Linux, supports administrator-authentication through PAM’s Linux password-module.

      Used with the Enterprise Edition of Couchbase Server, the PAM Linux password-module provides:

      • External authentication: Administrator-accounts defined on Linux systems, in the /etc/shadow directory, can be accessed for authentication-purposes by Couchbase Server.

      • Password policy-management: Linux password-management can be used across different Couchbase Server-nodes; to synchronize, maintain, and expire administrator-passwords.

      Note that use of the PAM Linux password-module requires all cluster-nodes to be Linux-based, running the Enterprise Edition of Couchbase Server, version 4.6 or above. Additionally, the saslauthd library version must be 2.1.x or above.

      For details on configuring saslauthd to support external authentication by PAM, see Configure saslauthd.