You are viewing the documentation for a prerelease version.

View Latest

Configure Client Certificates

Couchbase Server supports client-authentication by means of X.509 certificates.

Couchbase Client Authentication

Couchbase clients can authenticate by means of X.509 certificates. This page explains how client certificates can be prepared for a Java client. It also provides information on TLS levels, and on supported ciphers.

For a list of Couchbase-Server ports that provide secure connectivity to clients, see Connectivity.

Configure Certificates for a Java Client

Once the root certificate for a Couchbase Server-node has been deployed, a Java client can authenticate by means of an appropriately prepared keystore, and so gain access to the Data, Query, and Search Services.

Proceed as follows. Note that these instructions use the Ubuntu 16 environment previously configured in Configure Server Certificates.

  1. Define environment variables for the name of the keystore to be created, and its password.

    export KEYSTORE_FILE=my.keystore
    export STOREPASS=storepass
  2. If necessary, install a package containing the keytool utility:

    sudo apt install openjdk-9-jre-headless
  3. Within the top-level, SSLCA directory that you created, generate the keystore. Note that the password you specify for the alias, by means of the --keypass flag, must be identical to the password you specify for the keystore, by means of the --storepass flag. In this case, both passwords are specified as ${STOREPASS}; which resolves to storepass.

    keytool -genkey -keyalg RSA -alias selfsigned \
    -keystore ${KEYSTORE_FILE} -storepass ${STOREPASS} -validity 360 -keysize 2048 \
    -noprompt  -dname "CN=${USERNAME}, OU=None, O=None, L=None, S=None, C=US" -keypass ${STOREPASS}
  4. Generate the certificate signing-request:

    keytool -certreq -alias selfsigned -keyalg RSA -file my.csr \
    -keystore ${KEYSTORE_FILE} -storepass ${STOREPASS} -noprompt
  5. Generate the client certificate, signing it with the intermediate private key:

    openssl x509 -req -in my.csr -CA ./${INT_DIR}/${INTERMEDIATE}.pem \
    -CAkey ./${INT_DIR}/${INTERMEDIATE}.key -CAcreateserial -out clientcert.pem -days 365
  6. Add the root certificate to the keystore:

    keytool -import -trustcacerts -file ./${ROOT_DIR}/${ROOT_CA}.pem \
    -alias root -keystore ${KEYSTORE_FILE} -storepass ${STOREPASS} -noprompt
  7. Add the intermediate certificate to the keystore:

    keytool -import -trustcacerts -file ./${INT_DIR}/${INTERMEDIATE}.pem \
    -alias int -keystore ${KEYSTORE_FILE} -storepass ${STOREPASS} -noprompt
  8. Add the client certificate to the keystore:

    keytool -import -keystore ${KEYSTORE_FILE} -file clientcert.pem \
    -alias selfsigned -storepass ${STOREPASS} -noprompt

This concludes preparation of the Java client’s keystore. Copy the file (in this case, my.keystore) to a location on a local filesystem from which the Java client can access it.

Securing Client Access with TLS

For an application to communicate securely with Couchbase Server, SSL/TLS must be enabled on the client side. Enablement requires a copy of the certificate used by Couchbase Server: this can be accessed from the Couchbase Web Console, as described in Root Certificate.

Note that if, at some point, this certificate gets regenerated on the server-side, a copy of the new version must be obtained, and the client re-enabled.