Certificate-Based Authentication

Certificate-Based Authentication

With the growing threat to security from rogue users and/or machines, password-based authentication is no longer a reliable method of authenticating users. Couchbase now supports the use of x.509 certificates to authenticate clients which ensures that only approved users (or machines or endpoints) are authenticated. Note that this authentication mechanism is available only for the data service.

Certificate based authentication provides an additional layer of security. It 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, the digital signature of the issuing CA, and so on. This information serves as an introduction for users who know and trust the CA but don’t know the entity identified by the certificate. All software that supports certificates maintain a collection of trusted CA certificates which help them determine which certificate issuers can be trusted. In cases where the CA is a part of a hierarchy, the software can verify that the certificate is signed by the same root CA.

  1. When authenticating a client using x.509 certificates, Couchbase Server requests the client to present a client certificate during the handshake.
  2. When the client presents the certificate, the server checks for the validity of the certificate.
  3. If the certificate is valid and not expired, then it parses the certificate to obtain the user specified in the certificate.
  4. The server then verifies the user and the roles assigned to the user. If the user has appropriate roles, then it authenticates the user and completes the handshake.
  5. If any of the checks fail, the handshake is not completed.


  • x.509 certificate is the official standard for public key certificates and SSL/TLS relies on this standard. You must use valid x.509 certificates generated and signed by the same root certificate authority (CA).
  • The x.509 certificates must be in PEM format.
Note: Your prior knowledge of TLS/SSL, PKI certificates including X.509 certificates, and Certificate Authorities (CAs) is assumed for this topic and describing them is beyond the scope of this document.

Enabling x.509 Certificate Based Authentication on the Server

You can enable certificate based authentication on the server using REST API or CLI.

This authentication mechanism is available only for the data service and can be used with SDK/clients as well. For query and other services, use the other supported authentication mechanisms.


  1. Enable x.509 certificate authentication on the server. You must set this parameter once per cluster.
    curl -X POST  --data-binary "state=enable" http://Administrator:password@localhost:8091/settings/clientCertAuth
  2. Specify the path of the certificate to use to parse for the user on the server.
    curl -X POST  --data-binary "path=subject.cn" http://Administrator:password@localhost:8091/settings/clientCertAuth
  3. Specify the prefix and delimiter in that path expression.
    curl -X POST  --data-binary "delimiter=" http://Administrator:password@localhost:8091/settings/clientCertAuth
    curl -X POST  --data-binary "prefix=" http://Administrator:password@localhost:8091/settings/clientCertAuth    

Using CLI

Use the following couchbase-cli command:
couchbase-cli ssl-manage <options>
Options Value Description
--set-client-auth-state disable | enable | mandatory Enable or disable the SSL client certificate authentication.
  • disable: Disables client based certificate authentication. This is the default value.
  • enable: When enabled, if the client presents a certificate, then that certificate is used to authenticate. If authentication fails, then access is denied. However, if the client does not present a certificate, the certificate based authentication will be bypassed.
  • mandatory: The client must present a valid certificate in order to gain access to Couchbase buckets. If using XDCR, do not use the mandatory state for X.509 Certificate Authentication.
--set-client-auth-path subject.cn | san.uri | san.dnsname | san.name Set SSL client certificate type value.
--set-client-auth-prefix set_client_auth_prefix Set SSL client certificate prefix value.
--set-client-auth-delimiter set_client_auth_delimiter Set SSL client certificate delimiter value.
--client-auth   Show SSL client certificate authentication value.
After setting up the server side for client authentication, you should also assign the users to some roles on the server side. To do so:
  1. Create a user with authentication source (domain) 'Couchbase'.
  2. Ensure that this user is an internally managed user with a strong password. While the password is not used as part of the certificate based authentication, it is required if the user is trying to access the resources through the web console.

For information on assigning roles to users, see Creating and Managing Users with the UI.


Note the following limitations to the feature in the current release:
  • X.509 Certificate Based Authentication will only work for data service.
  • For Couchbase Server 5.0 Beta 2, X.509 Certificate-based Authentication support is only available in the Java Client.