A newer version of this documentation is available.

View Latest

Password-Based Authentication

In Couchbase clients can verify their identity by providing a secret predetermined value either by sending their password to the server through encrypted channels or by using a hash-based challenge-response method.

Authentication for Administrators

Passwords for the Full Administrators are set up during the initial installation of Couchbase Server. See Step 5: Configure serverfor details.

Check also the Security Best Practices for setting Couchbase passwords.

Resetting the Administrative Password

The administrative password can be reset using the password reset tool: cbreset_password

Authentication for Applications

Applications authenticate themselves with buckets using the SASL password.

Authentication at the bucket level takes place over the CRAM-MD5 protocol and involves a single challenge-and-response cycle initiated by Couchbase Server.

In the challenge sequence, the server sends a string in the format of a Message ID (email header value including angle brackets). The Message ID includes an arbitrary string of random digits, a timestamp, and the server’s fully qualified domain name.

Access control is configured using the Couchbase Web Console at Data Buckets  Create New Data Bucket and is set for two ports:

admin access control
Standard port

The standard port is the TCP port 11211, which requires SASL authentication. Enter the password that complies with the best practices rules.

Dedicated port

The dedicated port supports ASCII protocol and doesn’t need authentication. You only need to enter the port number.

Password Authentication Methods

For password authentication, Couchbase clients use a challenge-response protocol to negotiate with the server. In these authentication methods, the server asks for a password and also the a predetermined secret value the value that depends on the password through a hash function.

During an initial client-server negotiation, a password authentication protocol is chosen depending on the strongest common protocol supported by the server and client OS platform. For example, if a client supports only the PLAIN protocol, and the server supports both PLAIN and CRAM-MD5, then the PLAIN protocol is chosen and used during the client-server negotiation.

A challenge-response method can be transmitted either through encrypted or unencrypted channels. Hash-based challenge-response protocols typically only authenticate the authentication step and not the rest of the session. Using hash-based challenge-response protocols along with TLS will provide a secure session between the client and server.

Challenge-Response Methods in Couchbase

Authentication requires that clients provide a proof of identity to access the database. Couchbase provides three types of authentication mechanisms based on challenge-response method:

PLAIN authentication

The most straightforward authentication mechanism is PLAIN, where the client simply sends the password unencrypted to the server. All clients support the PLAIN mechanism, however, when this method is used anyone listening on the network can steal the password. For that reason, and some others, other mechanisms have been implemented.

CRAM-MD5 authentication

CRAM-MD5 is a password-based authentication mechanism, which utilizes an MD5 cryptographic hash algorithm to protect the password during the authentication exchange.

SCRAM-SHA* authentication

SCRAM is short for Salted Challenge Response Authentication Mechanism. This mechanism proves to the server that the user knows a secret derived from the user’s password and proves to the client that the server knows a secret derived from the user’s password.

Couchbase offers the SHA-1 hash function for SCRAM in compliance with the SCRAM RFC. Since the SCRAM protocol requires that SHA1 be always supported, it is usually the weakest link compared to stronger SHA hashes such as SHA2. As a security best practice, use SCRAM along with TLS to harden your client-server authentication. On SuSe, the SCRAM protocol only supports SHA1 hash.

You must upgrade all drivers used by applications that will connect to upgraded database to a version that supports SCRAM-SHA. The minimum driver versions that support SCRAM-SHA are:

Table 1. Driver requirements for SCRAM-SHA authentication
Couchbase Client Version Description


2.2.5 and higher

Supports SCRAM through setting the system property com.couchbase.scramEnabled to true.

SCRAM support for other clients will be announced in upcoming client release cycles.