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.

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 for Administrators

      Administrators log into Couchbase Server Web Console either by providing their username and password to the administrative UI, or by selecting the Single Sign-On option, at https://hostname:18091.

      Optionally, the unencrypted port, 8091 can be used: specified as http://hostname:8091. Note this is not recommended, as username and password are passed in the clear, from the browser to the console.

      The best practice for administrator-authentication is to use single sign-on, with a provider that is configured to require Multi-Factor Authentication (MFA). For more information about securing the network with encryption, see On-the-Wire Security. For more information about single sign-on, see SAML Authentication.

      Authentication for Applications

      The recommended method for application-authentication when connecting to Couchbase Server is to use x.509 certificate-based authentication. This ensures that only approved users, machines, or endpoints are authenticated, and provides what is known as mutual authentication.

      Mutual-TLS (mTLS) certificate-based authentication relies on a Certificate Authority (CA) to validate identities and issue certificates. When using this method, no sensitive credentials are shared over the network; and all communication between application and server is performed over an encrypted channel, to prevent eavesdropping and impersonation.

      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.

      Authentication with Username and Password

      In cases where x.509 certificate-based authentication cannot be used, a username and password combination must be provided in the application, to authenticate to Couchbase Server. When an application authenticates to the Data Service, one of four mechanisms provided by the Simple Authentication and Security Layer (SASL) framework are used. All other Couchbase services use HTTP Basic Authentication.

      It is strongly recommended to always deploy TLS network encryption and use the defined TLS ports when connecting an application to Couchbase Server.

      Data-Service Authentication with Username and Password

      During initial client-server negotiation with the Data Service, when utilizing TLS network encryption, the SASL PLAIN method is always used, with the credentials being secured inside the encrypted network connection. For cases where TLS network-encryption is not in use, the strongest authentication protocol supported by both Couchbase Server and the client application is selected for authentication. This is either PLAIN or one of the revisions of SCRAM-SHA challenge-response mechanisms for authenticating. In ascending order of strength, the Couchbase password-authentication mechanisms are as follows:

      • PLAIN: The client sends the password in plaintext-form.

      • SCRAM-SHA1: 160-bit credential.

      • SCRAM-SHA256: 256-bit credential.

      • SCRAM-SHA512: 512-bit credential.

      Instead of the client sending the password directly to Couchbase Server, SCRAM uses a challenge-response mechanism, to exchange derived cryptographic credentials using a combination of PBKDF2, HMAC and SHA, so that the application-credential is not exposed to eavesdroppers on the network. Note that other communication-data, including queries and database-values, are not encrypted with the SCRAM mechanism: therefore, the SCRAM mechanism should only be used where TLS network-encryption is not an option.

      Authenticating with Other Services, with Username and Password

      Application-authentication for all services other than the Data Service uses the HTTP Basic Authentication mechanism, with username and password. In consequence, it is essential that TLS network encryption always be deployed, so as to avoid credentials being sent over the network insecurely.

      Secure Credential Storage

      Locally managed user-account credentials are stored in Couchbase Server using both the Argon2ID and PBKDF2 algorithms.

      Argon2ID is a state of the art password hashing function, designed to be resistant to various password-cracking attacks: including both time-memory trade-off attacks, and side-channel attacks. PBKDF2 is another powerful password hashing function; and is required to allow SCRAM-SHA capabilities. By default, the PBKDF2 credentials are stored with 5,000 iterations: this can be configured with the POST settings/security/scramShaIterations REST API method and URI, with a higher specified number increasing the security of the credentials, with the trade-off of higher resource requirements when authentication is performed. Following guidance from NIST, it is recommended to disable SCRAM-SHA1 unless it is absolutely required.

      By design, the Argon2id hashing algorithm consumes more CPU and memory than the prior default SHA-1 hashing algorithm. If your server handles a high volume of authentications, using the Argon2id hashing algorithm can result in higher CPU and memory use.

      The various levels of SCRAM SHA can be disabled with POST /settings/security/scramSha1Enabled, POST /settings/security/scramSha256Enabled and POST /settings/security/scramSha512Enabled. For more information on the using the REST API to configure security settings, see Configure On-the-Wire Security.

      For cases that do not use SCRAM-SHA, such as those that implement TLS network encryption, it is recommended to disable all variations of SCRAM-SHA; as this will prevent the SCRAM-SHA PBKDF2 hashes from being generated, when Argon2ID provides stronger security for those credentials.

      Automatic Password Hash Migration

      You can select which algorithm Couchbase Server uses to hash locally stored passwords by setting passwordHashAlg using the /settings/security REST API. When you change the hash algorithm Couchbase Server uses, it does not update all of the stored passwords using the new algorithm. It cannot rehash the existing passwords as it does not have access to the original, unhashed password. Instead, existing passwords remain hashed using the previous hashing algorithm. Couchbase Server uses the newly-set hashing algorithm for passwords when you create new accounts or when an existing account changes its password. Users can authenticate using passwords hashed with any hashing algorithm Couchbase Server supports.

      You can enable Couchbase Server’s password hash migration feature that automatically rehashes user’s password when they authenticate. Couchbase Server is able to hash the user’s password with the currently enabled hashing algorithm because it has access to the unhashed password during authentication. This rehashing is transparent to users—​they do not have to change their password to have it hashed with the more new hashing algorithm.

      You enable automatic password hash by calling the /settings/security endpoint to set the allowHashMigrationDuringAuth setting to true. This setting has an effect only if the entire database cluster is running Couchbase Server 7.6 or later. See Configure On-the-Wire Security for more information.

      Versions of Couchbase Server prior to 7.6 defaulted to using SHA-1 hashing to store passwords for local accounts. This algorithm is obsolete and is no longer considered secure by security experts. After upgrading to 7.6 or later, Couchbase Server defaults to using the Argon2id algorithm to hash newly created passwords for new users and users who change their password. Because Argon2id provides better security, you should enable allowHashMigrationDuringAuth to allow Couchbase Server to migrate passwords from SHA-1 to Argon2id.

      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 on an LDAP server, a SAML IdP provider, or Linux systems that are accessed by means of PAM. For a complete overview, see Authentication Domains.

      In addition to a username and password requirement, SAML can require Two-Factor Authentication (TFA) such as a one-time code sent via text message or a code generated by an authentication module or app. SAML can also provide Single Sign On (SSO), where a user that has already authenticated with another application is automatically authenticated to use