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.
- When authenticating a client using x.509 certificates, Couchbase Server requests the client to present a client certificate during the handshake.
- When the client presents the certificate, the server checks for the validity of the certificate.
- If the certificate is valid and not expired, then it parses the certificate to obtain the user specified in the certificate.
- 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.
- 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.
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.
Using REST API
- 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
- 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
- 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
couchbase-cli ssl-manage <options>
|--set-client-auth-state||disable | enable | mandatory||Enable or disable the SSL client 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.|
- Create a user with authentication source (domain) 'Couchbase'.
- 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.
- X.509 Certificate Based Authentication will only work for data service.
- For Couchbase Server 5.0, X.509 Certificate-based Authentication support is only available in the Java Client.