A newer version of this documentation is available.

View Latest


    RBAC requires that users pass appropriate credentials to Couchbase Server in order to access cluster-resources. The SDK provides enhanced support for the passing of credentials.

    RBAC and the SDK

    Couchbase Server 5.0 Enterprise Edition introduces Role-Based Access Control. This ensures that cluster-resources can only be accessed by users with appropriate privileges. Privileges are grouped in Couchbase-defined sets; and each set is associated with a specific role. Users can each be assigned one or more roles, and are thereby granted the privileges associated with each role.

    In order to access cluster-resources, programs, including those supported by the Couchbase SDK, must authenticate with Couchbase Server, and so be identified as existing users, each associated with one or more roles. Authentication requires the passing of credentials; which consist of a username and (in most cases) a password. Users may be defined either locally to Couchbase Server, or externally (for example, by means of an LDAP server).

    Once authentication has succeeded, an authorization process checks the roles associated with the identified user. If role-associated privileges correspond to the level of resource-access requested by the user, access is duly granted; otherwise, it is denied.

    Authenticating with Legacy SDK Versions

    For versions of Couchbase Server 5.0 and beyond, Role-Based Access Control (RBAC) is applied to all cluster-resources. Under RBAC, bucket-passwords are no longer used: instead, a username and user-password must be specified.

    All pre-RBAC versions of the SDK can continue to be used with Couchbase Server 5.0 and beyond: the pre-RBAC authentication procedure need not change. However, when passed:

    • The value formerly interpreted as a bucket-name is now interpreted as a username. The username must correspond to a user defined on the cluster that is being accessed.

    • The value formerly interpreted as a bucket-password is now interpreted as the password of the defined user.

    Note that on Couchbase Server 5.0 and beyond, the only buckets that can be accessed without a user-password are those that were created on legacy versions of the server; were not originally created with a bucket-password; and continue to be available on 5.0 and beyond, following the required upgrade process. See Upgrading to RBAC for information on server-upgrade to 5.0, and how this affects access to legacy buckets.

    On Couchbase Server 5.0 and beyond, for any bucket to be accessed successfully, the defined user attempting access must have been assigned appropriate roles. See Manage Users and Roles for information on user-management.

    Passing Credentials

    The most recent versions of the SDK are RBAC-enabled, and provide enhanced support for authentication. Code examples for C can be found in Getting Started with the SDK, and also as part of the Sample Code provided to demonstrate user management.

    Upgrading to RBAC-Enabled SDK-Versions

    The last pre-RBAC version of the C SDK was 2.7.3. The first RBAC-enabled version was 2.7.4. See the SDK Release Notes for more information.

    With the most recent versions of the SDK, the legacy authentication interface and the new, optimized authentication interface can both be used: each supports access to buckets on Couchbase Servers whose version is either 5.0 and beyond, or pre-5.0.

    Further Information on RBAC

    All aspects of the Couchbase RBAC system are covered in the section Authorization. Specifically, for information on:

    Certificate-Based Authentication

    Couchbase Server supports the use of X.509 certificates to authenticate clients. This allows authenticated users to access specific resources by means of the data service, in Couchbase Server 5.1 and up, and all other services in more recent releases of Couchbase Data Platform.

    The process relies on a certificate authority, for the issuing of certificates that validate identities. A certificate includes information such as the name of the entity it identifies, an expiration date, the name of the authority that issued the certificate, and the digital signature of the authority. A client attempting to access Couchbase Server can present a certificate to the server, allowing the server to check the validity of the certificate. If the certificate is valid, the user under whose identity the client is running, and the roles assigned that user, are verified. If the assigned roles are appropriate for the level of access requested to the specified resource, access is granted.

    The C SDK has supported working with X.509 certificates since 2.8.4. Version 2.8.5 of libcouchbase added the ability for the SSL trust store to be kept in a separate file. The trust store has to be specified with option truststorepath=…, otherwise the library will expect it to be stored with the certificate in certpath=, and the trust store and certificate concatenated in the certpath.

    This shell script will generate the client certificate - you will need to ensure that you have OpenSSL installed on your system:

    export CB_ROOT=/opt/couchbase
    export TOPDIR=SSLCA
    export ROOT_DIR=rootdir
    export CLIENT_DIR=clientdir
    export INT_DIR=intdir
    export ROOT_CA=ca
    export INTERMEDIATE=int
    export CLIENT=client
    export CHAIN=chain
    export ADMINCRED=Administrator:password
    export ip=
    export USERNAME=testuser
    cd ${TOPDIR}
    mkdir -p ${CLIENT_DIR}
    cd ${CLIENT_DIR}
    openssl genrsa -out ${CLIENT}.key 2048
    openssl req -new -key ${CLIENT}.key -out ${CLIENT}.csr -subj "/CN=${USERNAME}/OU=None/O=None/L=None/S=None/C=US"
    openssl x509 -req -in ${CLIENT}.csr -CA ../${INT_DIR}/${INTERMEDIATE}.pem \
      -CAkey ../${INT_DIR}/${INTERMEDIATE}.key -CAcreateserial \
      -CAserial ../${INT_DIR}/intermediateCA.srl -out ${CLIENT}.pem -days 365
    cat ./${CLIENT}.pem ../${INT_DIR}/${INTERMEDIATE}.pem ../${ROOT_DIR}/${ROOT_CA}.pem > ./${CHAIN}.pem

    Which is then used by passing ${CLIENT_DIR}/${CHAIN}.pem as the certpath option, and ${CLIENT_DIR}/${CLIENT}.key as keypath in the connection string (and don’t forget couchbases or https in the schema). For example:


    When necessary the root certificate, along with all intermediates, might be supplied with a separate connection string option truststorepath, and in this case concatenation (the last step in certification generation) is not necessary, and the client certificate could be specified as is. See full example at https://github.com/couchbaselabs/devguide-examples/blob/master/c/connecting-cert-auth.c.

    The Go platform requires extra care at the certificate generation stage. If the certificate generated does not directly match the host, then the SAN (Subject Alternative Name) Field should supply the appropriate names: gocb may fail to authenticate if it can’t verify the hostname is valid for the certificate. Other platforms - Java and .NET, with OpenSSL based implementations - are by default less strict on verification of hostnames.