To access Couchbase Server, users must be authenticated. Authentication is a process for identifying who is attempting to access a system. Subsequent to successful authentication, authorization can be performed, whereby the user’s appropriate access-level is determined.

Authentication Overview

Couchbase-Server authentication relies on a username and a password, which must be passed into the system by the user (meaning, the administrator or application) that is attempting access. The specified username and password must match ones already defined: these must be accessible either on the Couchbase-Server cluster itself, or externally. External accessibility, which is available only with the Enterprise Edition of Couchbase Server, means either:

  • On a network-accessible directory-server, by means of the Lightweight Directory Access Protocol (LDAP).

  • By means of the Pluggable Authentication Modules (PAM) authentication-framework.

If a match is achieved, the user is thereby recognized, and so may be granted access. If no match is achieved, the user is denied access.

Client applications or systems can also pass credentials to Couchbase Server by means of x.509 certificates.

Users and Passwords

To access Couchbase Server, all users must authenticate. For additional security, applications can be designed to use passwords in hash-based challenge-response routines.

The Full Administrator username and password are established during initialization of Couchbase Server: see Create a Cluster for details.

Subsequently, additional users can be added to the cluster as local users, each with a unique password. Passwords can be changed by means of the password-reset tool, reset-admin-password; or by Couchbase Web Console, as described in Editing Users and Groups. For best practices for password-definition, and restrictions on username-design, see Usernames and Passwords.

Users can also be added to the cluster as external users, for whom no password need be specified; since the external user is to be authenticated externally.

Authentication for Administrators

When an administrator logs into Couchbase Web Console, if the console is running on the default port, http://localhost:8091, the specified username and password are passed in the clear, from the browser to the console.

Optionally, Couchbase Web Console can be configured for secure access, at https://localhost:18091; so that the username and password are passed in encrypted form. For information, see Manage Console Access.

Authentication for Applications

To pass credentials, applications must use one of four mechanisms provided by the Simple Authentication and Security Layer (SASL) framework. These are PLAIN, and three members of the Salted Challenge Response Authentication Mechanism family of hash functions; which are SCRAM-SHA1, SCRAM-SHA256, and SCRAM-SHA512. The SCRAM mechanisms allow applications to authenticate securely, by transmitting the password only in protected form. Drivers may need to be updated, to support SHA-based hash functions.

In ascending order of strength, the Couchbase password-authentication mechanisms are as follows:

  • PLAIN: The client sends the password in unencrypted form. All clients support this authentication-method. It is insecure, providing no defence against passwords being stolen in transmission.

  • SCRAM-SHA1: Uses a 160-bit key.

  • SCRAM-SHA256: One of a group of hash functions referred to as SHA2, SCRAM-SHA256 uses a 256-bit key.

  • SCRAM-SHA512: Another hash function from the SHA2 group, SCRAM-SHA512 uses a 512-bit key; and is the strongest supported authentication protocol.

During initial client-server negotiation, the strongest authentication protocol supported by both Couchbase Server and the application’s client OS is selected for use. For example, if the client supports only the PLAIN protocol, the PLAIN protocol is used; but if the client also supports the SCRAM-SHA1 protocol, then SCRAM-SHA1 is used.

A challenge-response method can be transmitted through both encrypted and unencrypted channels.

Note that the SCRAM challenge-response protocols authenticate only the process of password-validation. To secure the subsequent session, TLS should be used.

Certificate-Based Authentication

Couchbase Server supports the use of x.509 certificates, to authenticate clients. This ensures that only approved users, machines, or endpoints are authenticated.

Certificate-based authentication relies on a Certificate Authority (CA) to validate identities and issue certificates. The certificate includes information such as the name of the entity it identifies, an expiration date, the name of the CA that issued the certificate, and the digital signature of the issuing CA.

For a complete overview of Couchbase Server’s certificate-handling mechanisms, see Certificates. For practical steps required to set up client and server certificates, see Manage Certificates


Couchbase-Server features — including data, settings, and statistics — can be accessed only by users who have been assigned the appropriate privileges. Privileges include read, read-write, execute, and manage. Privileges are assigned by Full and Security Administrators, in correspondence with roles. When a user successfully authenticates, their assigned roles are examined, and access is granted or denied by Couchbase Server.

Roles can be assigned to a user in either or both of two ways:

  • Directly. The user is associated directly with one or more Couchbase-Server roles.

  • By Group. A Couchbase-Server user-group is defined, and roles are assigned to the user-group. The user is made a member of the user-group, and thereby inherits all the roles of the group. A user can be a member of any number of groups.

Note that by means of LDAP Group Support, the roles assigned to a Couchbase-Server user-group can be inherited by users not defined on Couchbase Server; as described in Authentication Domains, immediately below.

See Manage Users, Groups, and Roles, for details on creating users and groups, and assigning roles.

Authentication Domains

Couchbase Server assigns each user to 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. Mixed-version clusters do not support LDAP authentication: therefore, to use LDAP authentication with a given cluster, upgrade all cluster-nodes to the latest version of Enterprise Edition Couchbase Server.

Couchbase Server is designed to interoperate with OpenLDAP software, which can be downloaded from the 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.

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.