// Module included in the following assemblies:
//
// assembly-security.adoc

[id='configuring-external-clients-to-trust-cluster-ca-{context}']
= Configuring external clients to trust the cluster CA

This procedure describes how to configure a Kafka client that resides outside the Kubernetes cluster – connecting to an `external` listener – to trust the cluster CA certificate.
Follow this procedure when setting up the client and during the renewal period, when the old clients CA certificate is replaced.

Follow the steps to configure trust certificates that are signed by the cluster CA for Java-based Kafka Producer, Consumer, and Streams APIs.

Choose the steps to follow according to the certificate format of the cluster CA: PKCS #12 (`.p12`) or PEM (`.crt`).

The steps describe how to obtain the certificate from the Cluster Secret that verifies the identity of the Kafka cluster.

IMPORTANT: The `_<cluster-name>_-cluster-ca-cert` `Secret` will contain more than one CA certificate during the CA certificate renewal period.
Clients must add _all_ of them to their truststores.

.Prerequisites

* The Cluster Operator must be running.
* There needs to be a `Kafka` resource within the Kubernetes cluster.
* You need a Kafka client application outside the Kubernetes cluster that will connect using TLS, and needs to trust the cluster CA certificate.

.Using PKCS #12 format (.p12)

. Extract the cluster CA certificate and password from the generated `_<cluster-name>_-cluster-ca-cert` Secret.
+
[source,shell,subs="+quotes"]
kubectl get secret _<cluster-name>_-cluster-ca-cert -o jsonpath='{.data.ca\.p12}' | base64 -d > ca.p12
+
[source,shell,subs="+quotes"]
kubectl get secret _<cluster-name>_-cluster-ca-cert -o jsonpath='{.data.ca\.password}' | base64 -d > ca.password

. Configure the Kafka client with the following properties:
+
* A security protocol option:
** `security.protocol: SSL` when using TLS for encryption (with or without TLS authentication).
** `security.protocol: SASL_SSL` when using SCRAM-SHA authentication over TLS.
* `ssl.truststore.location` with the truststore location where the certificates were imported.
* `ssl.truststore.password` with the password for accessing the truststore. This property can be omitted if it is not needed by the truststore.
* `ssl.truststore.type=PKCS12` to identify the truststore type.

.Using PEM format (.crt)

. Extract the cluster CA certificate from the generated `_<cluster-name>_-cluster-ca-cert` Secret.
+
[source,shell,subs="+quotes"]
kubectl get secret _<cluster-name>_-cluster-ca-cert -o jsonpath='{.data.ca\.crt}' | base64 -d > ca.crt

. Use the certificate with clients that use certificates in X.509 format.
