A newer version of this documentation is available.

View Latest

Password-Based Authentication

    To access Couchbase Server, administrators and applications must authenticate. Authentication is password-based. For additional security, applications can be designed to use passwords in hash-based challenge-response routines.

    Authentication for Administrators

    Administrator usernames and passwords, both required for authentication, are initially established during initialization of Couchbase Server: see Initialize the Cluster for details. Subsequently, passwords can be changed by means of the password-reset tool, reset-admin-password

    For best practices for password-definition, and restrictions on username-design, see Couchbase Passwords.

    When the Couchbase Web Console is running on the default port, http://localhost:8091, the administrator’s username and password are passed in the clear, from the administrator’s 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 Encryption On the Wire.

    Authentication for Applications

    Couchbase Server-features — including data, settings, and statistics — can be accessed only by users who have been assigned the appropriate privilege. Each privilage is either read or read-write. Privileges are assigned by Full Administrators, in the form of roles. When a user successfully authenticates, their assigned roles are examined, and access is granted or denied by Couchbase Server. See Authorization, for details on creating users and user-credentials, and on assigning roles.

    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.

    Password Authentication-Mechanisms

    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 tranmission.

    • 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.