--- title: Configure Client Certificates description: Enterprise Analytics supports client-authentication by means of X.509 \ certificates. pubDate: 2026-08-17T09:53:44.266Z antora: editUrl: https://github.com/couchbaselabs/docs-enterprise-analytics/edit/release/2.0/modules/manage/pages/manage-security/configure-client-certificates.adoc xref: xref:2.0@enterprise-analytics:manage:manage-security/configure-client-certificates.adoc[] --- [Consult the llms.txt file for a full list of contents](/llms.txt) [View original HTML](/enterprise-analytics/2.0/manage/manage-security/configure-client-certificates.html) # Configure Client Certificates > Enterprise Analytics supports client-authentication by means of X.509 \\ certificates. ## [](#couchbase-client-authentication)Couchbase Client Authentication Couchbase clients can authenticate by means of X.509 certificates. This page provides step-by-step instructions for the creation of client certificates. For a list of Couchbase-Server ports that provide secure connectivity to clients, see [Connectivity](../../../../server/current/learn/clusters-and-availability/connectivity.md). ## [](#cert-auth-for-couchbase-server)Configure Client Certificates for Enterprise Analytics The section contains two procedures for the creation of a client certificate and key, whereby authentication with Enterprise Analytics can be performed: * [Client Access: Root-Certificate Authorization](#client-certificate-authorized-by-a-root-certificate) 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](configure-server-certificates.md#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 Enterprise Analytics, 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](../../../../server/current/learn/security/using-multiple-cas.md). * [Client Access: Intermediate-Certificate Authorization](#client-certificate-authorized-by-an-intermediate-certificate) 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](configure-server-certificates.md#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 Enterprise Analytics to be accessed by the client: * Contains the sample database `travel-sample`: this is the database whose contents the client wishes to read and write. For information about sample databases and how to install them, see [About Enterprise Analytics](../../intro/intro.md). * Has a defined, locally authenticated user named `clientuser`, who has been assigned a role that permits reading and writing to the `travel-sample` database. For information about creating users and roles, see [Manage Users and Roles](manage-users-and-roles.md). * Has client-certificate handling configured as either _enabled_ or _mandatory_. For details, see [Enable Client-Certificate Handling](enable-client-certificate-handling.md). Note that additional information about file-types can be found in the procedures for _server_\-certificate generation; in [Configure Server Certificates](configure-server-certificates.md). ### [](#client-certificate-authorized-by-a-root-certificate)Client Access: Root-Certificate Authorization Proceed as follows: 1. Within the top-level directory created in [Cluster Protection with Root and Node Certificates](configure-server-certificates.md#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 <> ./client.ext.tmp If Enterprise Analytics is configured to search for an email address to be used as a username (as described in [Specifying Usernames for Client-Certificate Authentication](../../../../server/current/learn/security/certificates.md#identity-encoding-in-client-certificates) and [Enable Client-Certificate Handling](enable-client-certificate-handling.md)), the user `john.smith` will be submitted for authentication. If this extension is _not_ added, and Enterprise Analytics 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. ### [](#client-certificate-authorized-by-an-intermediate-certificate)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](configure-server-certificates.md#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](configure-server-certificates.md#root-intermediate-and-node-certificates). cd servercertfiles2/root 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. Note that the extension file used here to constrain the capabilities of the intermediate certificate is that created in [Cluster Protection with Root, Intermediate, and Node Certificates](configure-server-certificates.md#create-intermediate-extensions-file). 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 < clientuser.pem The result of the concatenation, `clientuser.pem` is the completed client certificate. ## [](#cert%5Fauth%5Ffor%5Fjava%5Fclient)Configure Client Certificates for Java Clients A _Java_ client uses a _keystore_ to access the certificates it requires for authentication. Certificate and keystore preparation is demonstrated by the procedures in the following two sections, which are: * [Java Client Access: Root-Certificate Authorization](#java-client-access-root-certificate-authorization). This creates a Java-client certificate signed by the cluster's root certificate. As such, the procedure follows on from the server-certificate creation-process documented in [Cluster Protection with Root and Node Certificates](configure-server-certificates.md#root-and-node-certificates); and makes use of the directories and keys created there. * [Java Client Access: Intermediate-Certificate Authorization](#java-client-access-intermediate-certificate-authorization). This creates a Java-client certificate signed by the cluster's intermediate certificate. As such, the procedure follows on from the server-certificate creation-process documented in [Cluster Protection with Root, Intermediate and Node Certificates](configure-server-certificates.md#root-intermediate-and-node-certificates); and makes use of the directories and keys created there. Note that the [assumptions](#assumptions) specified for the examples above likewise apply to the Java client examples below. ### [](#java-client-access-root-certificate-authorization)Java Client Access: Root-Certificate Authorization Proceed as follows: 1. Access the main working directory created in [Cluster Protection with Root and Node Certificates](configure-server-certificates.md#root-and-node-certificates), and create and access a new working directory for the Java client certificate to be created. cd servercertfiles mkdir javaclient cd javaclient 2. Define two environment variables: one for the name of the keystore to be created, another for its password. ```bash export KEYSTORE_FILE=my.keystore export STOREPASS=storepass ``` 3. If necessary, install a package containing the `keytool` utility: ```bash sudo apt install openjdk-11-jre-headless ``` Note that available packages can be found by means of `sudo apt-cache search openjdk`. 4. 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`. ```bash keytool -genkey -keyalg RSA -alias selfsigned \ -keystore ${KEYSTORE_FILE} -storepass ${STOREPASS} -validity 360 \ -keysize 2048 -noprompt -dname "CN=clientuser, OU=People, O=MyCompany, \ L=None, S=None, C=UA" -keypass ${STOREPASS} ``` Note that the `Common Name` for the certificate is specified as `clientuser`, which is the username established on Enterprise Analytics, whose role-assignment is supportive of reading and writing data to the `travel-sample` bucket. 5. Generate the certificate signing-request: ```bash keytool -certreq -alias selfsigned -keyalg RSA -file my.csr \ -keystore ${KEYSTORE_FILE} -storepass ${STOREPASS} -noprompt ``` This creates the signing-request file, `my.csr`. Note that in this example, although only the `Common Name` is being used to establish the identity of the user seeking authorization, one or more `Subject Alternative Names` could also be added. For example, by adding `-ext "san=email:john.smith@mail.com"` to the certificate signing-request used in the current step, the email-address `john.smith@mail.com` could be established as the basis for an alternative username to be submitted for authentication. See [Specifying Usernames for Client-Certificate Authentication](../../../../server/current/learn/security/certificates.md#identity-encoding-in-client-certificates), for more information. 6. Generate the client certificate, signing it with the root private key, and thereby establishing the root certificate's authority: ```bash openssl x509 -req -in my.csr -CA ../ca.pem \ -CAkey ../ca.key -CAcreateserial -out clientcert.pem -days 365 ``` 7. Add the root certificate to the keystore: ```bash keytool -import -trustcacerts -file ../ca.pem \ -alias root -keystore ${KEYSTORE_FILE} -storepass ${STOREPASS} -noprompt ``` 8. Add the client certificate to the keystore: ```bash 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. A sample Java program, which accesses a keystore from a local filesystem, is provided in [Authenticating a Java Client by Certificate](../../../../java-sdk/current/howtos/sdk-authentication.md#authenticating-the-java-client-by-certificate). ### [](#java-client-access-intermediate-certificate-authorization)Java Client Access: Intermediate-Certificate Authorization Proceed as follows: 1. Access the main working directory created in [Cluster Protection with Root, Intermediate, and Node Certificates](configure-server-certificates.md#root-intermediate-and-node-certificates), and create and access a new working directory for the Java client certificate to be created. cd servercertfiles2 mkdir javaclient cd javaclient 2. Define two environment variables: one for the name of the keystore to be created, another for its password: export KEYSTORE_FILE=my.keystore export STOREPASS=storepass 3. If necessary, install a package containing the `keytool` utility: sudo apt install openjdk-11-jre-headless 4. 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=clientuser, OU=People, O=MyCompany, \ L=None, S=None, C=UA" -keypass ${STOREPASS} Note that the Common Name for the certificate is specified as `clientuser`, which is the username established on Enterprise Analytics, whose role-assignment is supportive of reading and writing data to the `travel-sample` bucket. 5. Generate the certificate signing-request: keytool -certreq -alias selfsigned -keyalg RSA -file my.csr \ -keystore ${KEYSTORE_FILE} -storepass ${STOREPASS} -noprompt 6. Generate the client certificate, signing it with the intermediate private key, and thereby establishing the intermediate certificate's authority: openssl x509 -req -in my.csr -CA ../servers/int.pem \ -CAkey ../servers/int.key -CAcreateserial -out clientcert.pem -days 365 Since the intermediate private key was encrypted, a prompt now appears, requesting entry of the pass phrase for the key: Enter pass phrase for ../servers/int.key: Enter the pass phrase against the prompt. 7. Add the root certificate to the keystore: keytool -import -trustcacerts -file ../root/ca.pem \ -alias root -keystore ${KEYSTORE_FILE} -storepass ${STOREPASS} -noprompt 8. Add the intermediate certificate to the keystore: keytool -import -trustcacerts -file ../servers/int.pem \ -alias root2 -keystore ${KEYSTORE_FILE} -storepass ${STOREPASS} -noprompt 9. 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. A sample Java program, which accesses a keystore from a local filesystem, is provided in [Authenticating a Java Client by Certificate](../../../../java-sdk/current/howtos/sdk-authentication.md#authenticating-the-java-client-by-certificate). ## [](#enabling-client-security)Securing Client Access with TLS For an application to communicate securely with Enterprise Analytics, SSL/TLS must be enabled on the client side. Enablement requires a copy of the root certificate used by Enterprise Analytics: this can be accessed from the Enterprise Analytics Web Console, as described in [Root Certificate](manage-security-settings.md#root-certificate-security-screen-display). Note that if, at some point, the root certificate gets regenerated on the server-side, a copy of the new version must be obtained, and the client re-enabled.