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

Understanding Authentication

      +
      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 Options

      Couchbase-Server authentication typically 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, Usernames, and Passwords

      To access Couchbase Server, all users and applications must authenticate. This is typically achieved by means of a username and password.

      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 is at that time assigned a unique username, and 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.

      Usernames and Passwords 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.

      Usernames and Passwords 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

      Authorization

      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.

      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; which are local and external. The local domain contains users defined locally, on Couchbase Server. The external domain contains users defined externally, either on an LDAP server, or on Linux systems that are accessed by means of PAM. For a complete overview, see Authentication Domains.