Authentication
To access Couchbase Server, administrators and applications must be authenticated. Authentication is a process for identifying a user who is attempting to access a system.
Passing Credentials
Couchbase-Server authentication relies on credentials, which must be passed into the system by the user who is attempting access. Credentials can be entered manually, or passed into the system by an application. The credentials passed must match ones already stored and accessible by the system: 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.
To access Couchbase Server, administrators authenticate by means of a username and password. These credentials can be validated by Couchbase Server itself: alternatively if the Enterprise Edition of Couchbase Server for Linux is used, validation can be performed either on a network-accessible directory-server, by means of the Lightweight Directory Access Protocol (LDAP); or by means of the Pluggable Authentication Modules (PAM) authentication-framework.
Client applications or systems can also pass credentials to Couchbase Server, by means of x.509 certificates.
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.
Administrator usernames and passwords, both required for authentication, are initially established during initialization of Couchbase Server: see Create a Cluster for details. Subsequently, passwords can be changed by means of the password-reset tool, cli:cbcli/couchbase-cli-reset-admin-password.adoc.
For best practices for password-definition, and restrictions on username-design, see Usernames and 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 Manage Console Access.
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 Manage Users and Roles, 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 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. This authentication mechanism can be used by the Couchbase SDK to access the Data, Query, and Search Services.
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
Externally Based Authentication
Couchbase Server assigns users to different authentication domains:
-
Local: Contains users defined locally. This includes:
-
The Full Administrator for Couchbase Server.
-
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.
-
Locally Defined Users, which are explicitly created by a Couchbase Server administrator; and each feature a username and password unique within the Local domain.
-
-
External: Contains users defined externally; either by means of LDAP or PAM. Passwords are defined and stored remotely. Note that External usernames do not clash with Local usernames.
When a user attempts to authenticate, Couchbase Server always looks up their credentials in the same order: which is Local first, and External second.
External authentication can be performed by means either of LDAP or PAM.
LDAP-Based Authentication
Couchbase administrators can be set up to authenticate by means of LDAP.
This requires that each administrator be added as a user on an LDAP server, and their LDAP credentials mapped to Couchbase Server.
Additionally, it requires that the saslauthd library, which handles authentication-requests on behalf of Couchbase Server, be configured to handle LDAP authentication.
LDAP authentication is currently available only for the Enterprise Edition of Couchbase Server, and only on the Linux platform. Note also that 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 openldap.org website.
LDAP Benefits
Authenticating with LDAP provides the benefits of:
-
Centralized identity management. Multiple administrators can be defined, each with either read-only or full, read-write permissions.
-
Centralized security policy-management. All administrative accounts can be consistently protected: for example, through the enforcement of password strength-levels, password-rotation, and auto-lockout.
-
Simplified compliance. The activities of each administrator can be identified, tracked, and comprehensively audited.
Architecture
The LDAP authentication-architecture used by Couchbase Server is as follows:
As the illustration shows, the administrator enters a username and password at the login prompt provided by Couchbase Web Console.
This is checked against a local admin password file.
If the saslauthd library has been configured for LDAP, the credentials are then checked against an LDAP directory service: if the credentials are validated, authentication succeeds.
For details on configuring the saslauthd library, see Configure saslauthd.
PAM-Based Authentication
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.
PAM Benefits
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/shadowdirectory, 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.