Enable Client-Certificate Handling

Couchbase Server can be enabled to support certificate-based authentication by networked clients.

Certificate-Based Client Authentication

Couchbase clients can be authenticated by means of X.509 certificates, but only after client-certificate handling has been explicitly enabled. This can be accomplished with the UI, the CLI, or the REST API.

Enable Client-Certificate Handling with the UI

Proceed as follows:

  1. Access Couchbase Web Console, and left-click on the Security tab, in the vertical navigation-bar, at the left-hand side of the Dashboard:

    securityTabWithHandCursor

    This brings up the Security screen, which appears as follows:

    securityViewInitialNoUsers

    The initial, default view is for Users.

  2. To manage client certificate handling, left-click on the Client Certificate tab, on the upper, horizontal control bar:

    clientCertificateTab

    The Client Certificate options are now displayed:

    clientCertificateDisplay

  3. Specify whether certificates are enabled, and if so, whether manadatory. The Require Client Certificate panel provides three options, as radio buttons. These are:

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

      Note, if you are using XDCR, do not use the mandatory state.

  4. In order to identify the client-certificates that will be presented for authentication, specify one or more appropriate combinations of Path, Prefix, and Delimiter. For an explanation of these values, see Identity Encoding in Client Certificates.

  5. Left-click on the Save button, to save the settings.

Client certificates will now be handled in accordance with your specification.

Enable Client-Certificate Handling with the CLI

Use the couchbase-cli cli:cbcli/couchbase-cli-ssl-manage.adoc#couchbaseclisslmanage1.idm68744912 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.email

Set SSL client certificate type value. This field will be used to extract the user name from the certificate. Currently, only the fields specified in the values column are supported.

--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. The delimiter can either be a string or a character. The parsing of the certificate for the user name ends when the delimiter value is found.

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

Enable Client-Certificate Handling with the REST API

  1. Create a data file containing the payload for your certificate authentication settings. For example, cb-certauth-setting.json:

    {
	"state": "enable",
	"prefixes": [{
			"path": "san.uri",
			"prefix": "www.",
			"delimiter": "."
		},
		{
			"path": "san.email",
			"prefix": "couchbase.",
			"delimiter": "."
		}
	]
}

  2. Run the following command to enable x.509 certificate authentication on the server.

    curl -H "Content-Type: application/json" --data-binary @cb-certauth-setting.json http://Administrator:password@127.0.0.1:8091/settings/clientCertAuth

  3. To retrieve the client certificate authentication settings, run the following command:

    curl -X GET  Administrator:password@localhost:8091/settings/clientCertAuth

    This returns the following:

    {"state":"enable","prefixes":[{"delimiter":".","path":"san.uri","prefix":"www."},{"delimiter":".","path":"san.email","prefix":"couchbase."}]}

Client Certificates and Server Upgrade

On a cluster’s upgrade to the current version of Couchbase Server, the cluster will continue to return client-certificate authentication-settings in the format of the earlier version until the cluster is completely upgraded. Once the cluster has been upgraded, any existing client certificate authentication settings from earlier versions are automatically transformed into the new format.