Configure Client Certificates | Couchbase Docs (original) (raw)

The section contains two procedures for the creation of a client certificate and key, whereby authentication with Couchbase Server can be performed:

• Client Access: Root-Certificate Authorization shows how to create a client certificate that is authorized by a cluster’s root certificate. The procedure for creating a root certificate (and, based on the root certificate, the cluster’s individual per node certificates), is provided in Cluster Protection with Root and Node Certificates. The instructions on the current page assume that that procedure has already been followed: therefore, they duly make use of the previously created directory structure and files.
  Note that in Couchbase Server Version 7.1 and later, multiple root certificates can be uploaded into the cluster, some potentially to be used for client authentication only; and therefore not to be used for the signing of node certificates. Therefore, a client no longer needs to base its authority on a CA that is being used to protect the server: however, the CA it uses must be recognizable to the cluster; and as such, must be a root certificate uploaded into the cluster’s trust store. For an overview, see Using Multiple Root Certificaes.
• Client Access: Intermediate-Certificate Authorization shows how to create a client certificate that is authorized by an intermediate certificate; which derives its own authority from a root certificate; and which is used instead of the root for the signing of the client certificate. The procedure for creating a root, server-intermediate and per node certificates is provided in Cluster Protection with Root, Intermediate, and Node Certificates. The instructions on the current page assume that that procedure has already been followed: therefore, they duly make use of the previously created directory structure and files.

Both procedures additionally assume that the instance of Couchbase Server to be accessed by the client:

• Contains the sample bucket travel-sample: this is the bucket whose contents the client wishes to read and write. For information on sample buckets and how to install them, see Sample Buckets.
• Has a defined, locally authenticated user named clientuser, who has been assigned a role that permits reading and writing to the travel-sample bucket. For information on creating users and roles, see Manage Users and Roles.
• Has client-certificate handling configured as either enabled or mandatory. For details, see Enable Client-Certificate Handling.

Note that additional information on file-types can be found in the procedures for _server_-certificate generation; in Configure Server Certificates.

Proceed as follows:

1. Within the top-level directory created in Cluster Protection with Root and Node Certificates, create and access a new working directory.
   cd servercertfiles
   mkdir clientcertfiles
   cd clientcertfiles
2. Create an extensions file for the use of all clients.
   cat > client.ext <<EOF
   basicConstraints = CA:FALSE
   subjectKeyIdentifier = hash
   authorityKeyIdentifier = keyid,issuer:always
   extendedKeyUsage = clientAuth
   keyUsage = digitalSignature
   EOF
   This specifies a value of FALSE for CA, indicating that the client certificate will not have the ability to act as an authority for other certificates. Its extendedKeyUsage is specified as clientAuth, indicating that the certificate will be used for authenticating a client. It keyUsage is specified as digitalSignature, indicating that its public key is usable for data-origin authentication.
   This extensions file thus contains definitions judged appropriate for all clients. Further constraints can be added for individual clients, as necessary.
3. Create a client private key.
   openssl genrsa -out ./travel-sample.key 2048
   This creates the private key travel-sample.key.
4. Generate the client-certificate signing-request.
   openssl req -new -key ./travel-sample.key -out ./travel-sample.csr -subj "/CN=clientuser"
   The client’s private key, travel-sample.key is provided as input for the signing request. The Common Name provided as Subject for the certificate is specified as clientuser, which is the name of the server-defined user to be authenticated by the client. The output request-file, travel-sample.csr is saved in the current directory.
5. Optionally, customize a client extensions file, to identify a username to be authenticated.
   As described in Specifying Usernames for Client-Certificate Authentication, a client certificate should contain a username, against which authentication can be performed on Couchbase Server. The server’s default handling assumes that the Subject Common Name specifies the username. However, a Subject Alternative Name might be used; either in addition, or as an alternative.
   The following subjectAltName statement allows an email address to be specified as the basis for the username.
   cp ./client.ext ./client.ext.tmp
   echo "subjectAltName = email:john.smith@mail.com" \

   ./client.ext.tmp
   If this extension is not added, and Couchbase Server client-certificate handling is left at its default, the Common Name (which was specified as clientuser, when the client-certificate signing-request was generated) will continue to be used as the username.

6. Create the client certificate. In this example, the customized extensions file, client.ext.tmp, is used. However, if no email address or other Subject Alternative Name has been added, the generic client-extensions file, client.ext, can be used instead.
   openssl x509 -CA ../ca.pem -CAkey ../ca.key \
   -CAcreateserial -days 365 -req -in ./travel-sample.csr \
   -out ./travel-sample.pem -extfile ./client.ext.tmp
   The root certificate for the cluster, and its corresponding private key, ca.pem and ca.key are specified as inputs for certificate generation, so establishing the root certificate’s authority, within the client certificate. The output file, travel-sample.pem, is the client certificate, and is saved in clientcertfiles.
   The confirmatory output is as follows:
   Signature ok
   subject=/CN=clientuser
   Getting CA Private Key
   This concludes the process. The client can now use travel-sample.pem to authenticate itself as having the authority of ca.pem (which is shared by the server it intends to access); and provides the username of clientuser (which the server associates with a role appropriate for access to the travel-sample bucket). The client key, travel-sample.key, can be used for digital signing.
   A possible use case for the client certificate thus generated is described below, in Using Client and Server Certificates for Secure XDCR.

Client Access: Intermediate-Certificate Authorization

The following procedure demonstrates how an intermediate certificate, with the authority of the root certificate, can be created in order itself to sign client certificates. The procedure assumes that the server-equivalent procedure described in Cluster Protection with Root, Intermediate, and Node Certificates has already been followed; and that the resulting directory-structure is still available.

Proceed as follows:

1. Access the servercertfiles2/root directory, created in Cluster Protection with Root, Intermediate, and Node Certificates.
2. Create an encrypted private key and a certificate signing request, for an intermediate certificate that is to be used for signing client certificates.
   openssl req -new -sha256 -newkey rsa:2048 -keyout ../clients/int.key \
   -out reqs/client-signing.csr \
   -subj '/C=UA/O=MyCompany/OU=People/CN=ClientSigningCA'
   Since this specifies that an encrypted private key be created, prompts appear requesting entry of an appropriate pass phrase. Enter an appropriate phrase against the prompts.
   This new private key is named ../clients/int.key. The signing-request file is saved as reqs/client-signing.csr.
3. Create the intermediate certificate to be used for client-certificate signing.
   openssl x509 -CA ca.pem -CAkey ca.key -CAcreateserial -CAserial serial.srl \
   -days 3650 -req -in reqs/client-signing.csr -out issued/client-signing.pem \
   -extfile int.ext
   The root certificate and key for the cluster, ca.pem and ca.key, are specified as the authority for the intermediate certificate. Since ca.key is an encrypted key, a prompt appears, requesting that the appropriate pass phrase be entered: enter the appropriate phrase.
4. Save the intermediate certificate as the certificate-authority for the client certificate that is to be created.
   cp issued/client-signing.pem ../clients/int.pem
5. Within the ../clients directory, create an extension file for the client certificate:
   cd ../clients
   cat > client.ext <<EOF
   basicConstraints = CA:FALSE
   subjectKeyIdentifier = hash
   authorityKeyIdentifier = keyid,issuer:always
   extendedKeyUsage = clientAuth
   keyUsage = digitalSignature
   EOF
   The value of extendedKeyUsage is specified as clientAuth, indicating that the certificate will be used to authenticate a client. The value of keyUsage is specified as digitalSignature, indicating that the certificate may be used in the verifying of information-origin.
6. Create a private key for the client certificate.
   openssl genrsa -out private/clientuser.key 2048
7. Create a certificate signing request for the client certificate.
   openssl req -new -key private/clientuser.key -out reqs/clientuser.csr \
   -subj "/C=UA/O=MyCompany/OU=People/CN=clientuser"
   The signing request is based on the private key clientuser.key. The username associated with the certificate is specified as clientuser: this is the username to be recognized by Couchbase Server, and associated with specific roles.
8. Create the client certificate.
   openssl x509 -CA int.pem -CAkey int.key -CAcreateserial -CAserial serial.srl \
   -days 365 -req -in reqs/clientuser.csr \
   -out issued/clientuser.pem -extfile client.ext
   This creates the client certificate clientuser.pem, based on the signing request clientuser.csr, and signed with the authority of the intermediate certificate and key, int.pem and int.key. Since int.key is encrypted, a prompt appears, requesting entry of the appropriate pass phrase: enter the appropriate phrase against the prompt. The certificate is saved in the issued folder.
9. Check the validity of the client certificate. The following use of the openssl command verifies the relationship between the root certificate, the client-intermediate certificate, and the client certificate.
   openssl verify -trusted ../root/ca.pem -untrusted int.pem \
   issued/clientuser.pem
   If the certificate is valid, the following output is displayed:
   issued/clientuser.pem: OK
10. Concatenate the issued client certificate with the client-intermediate certificate, to establish the chain of authority.
    cat issued/clientuser.pem int.pem > clientuser.pem
    The result of the concatenation, clientuser.pem is the completed client certificate.

Using Client and Server Certificates for Secure XDCR

• If the procedures explained in Cluster Protection with Root and Node Certificates and Client Access: Root-Certificate Authorization have been followed, specify:
  • The remote cluster root certificate as servercertfiles/ca.pem.
  • The client certificate as servercertfiles/clientcertfiles/travel-sample.pem.
  • The client private key as servercertfiles/clientcertfiles/travel-sample.key.
• If the procedures explained in Cluster Protection with Root, Intermediate, and Node Certificates and Client Access: Intermediate-Certificate Authorization have been followed, specify:
  • The remote cluster root certificate as servercertfiles2/root/ca.pem.
  • The client certificate as servercertfiles2/clients/clientuser.pem.
  • The client private key as servercertfiles2/clients/private/clientuser.key.