Configure Truststores for TLS Handshake with Identity Providers

With OAuth enabled, Confluent Platform services always verify your identity provider’s TLS certificate, even if no truststore is configured.

If your identity provider uses a certificate signed by a public Certificate Authority (CA) that the Java Virtual Machine (JVM) trusts by default, you don’t need to configure a truststore. Confluent Platform services use the default JVM truststore to verify the certificate.

However, if a service already has a truststore configured, for example for mTLS, it no longer uses the default JVM truststore to verify your identity provider. In that case, add the identity provider’s CA certificate to that truststore, even if the CA is public. Otherwise, OAuth fails.

If your identity provider uses a self-signed TLS certificate or a certificate signed by a private CA that the JVM doesn’t trust by default, you must configure a truststore for each of your Confluent Platform services. The truststore includes the certificate of the CA that issued the identity provider certificate or the identity provider certificate itself, if it is self-signed, and is configured with the location and password properties. Follow the steps below to configure the truststore for your Confluent Platform service.

Step 1 - Download the identity provider TLS certificate

Use the following openssl command to download the certificate of your identity provider, replacing <idp-host>:<idp-port> with its hostname and port, for example, login.example.com:443. If your identity provider’s certificate is signed by a CA, this command saves only the identity provider’s own certificate, not the CA certificate. Obtain the CA certificate from your PKI or identity provider administrator, or from the public CA’s website, and import it instead of the identity provider certificate. A truststore that holds only the identity provider certificate breaks when your identity provider rotates it.

openssl s_client -showcerts \
  -connect <idp-host>:<idp-port> -servername <idp-host> </dev/null 2>/dev/null|openssl x509 \
  -outform PEM ><idp-certfile>.pem

Step 2 - Import the identity provider TLS certificate to the truststore

Use the keytool command to import the certificate to the truststore for your Confluent Platform service. Replace the placeholder values with your own values.

keytool -import -alias <idp-alias> -file <idp-certfile>.pem \
  -storetype JKS \
  -keystore <idp-keystore-path> \
  -storepass <idp-keystore-password> \
  -noprompt

You must restart the corresponding Confluent Platform service for it to reload the truststore.

Step 3 - Configure the truststore in your Confluent Platform service

For each of your Confluent Platform services, configure the truststore with the ssl.truststore.location and ssl.truststore.password properties. Replace the placeholder values with your own values.

Kafka broker

listener.name.external.oauthbearer.sasl.jaas.config=org.apache.kafka.common.security.oauthbearer.OAuthBearerLoginModule required \
  ssl.truststore.location="<path_to_kafka_broker.jks>" \
  ssl.truststore.password="<kafka_broker_truststore_password>";

Metadata Service (MDS)

confluent.metadata.server.ssl.truststore.location=<path_to_kafka_broker.jks>
confluent.metadata.server.ssl.truststore.password=<kafka_broker_truststore_password>

Confluent Schema Registry

ssl.truststore.location=<path_to_schema_registry.jks>
ssl.truststore.password=<schema_registry_truststore_password>

Confluent REST Proxy

Embedded

kafka.rest.ssl.truststore.location=<path_to_kafka_broker.jks>
kafka.rest.ssl.truststore.password=<kafka_broker_truststore_password>

Standalone

ssl.truststore.location=<path_to_kafka_rest_truststore.jks>
ssl.truststore.password=<kafka_rest_truststore_password>

Kafka Connect

ssl.truststore.location=<path_to_kafka_connect.truststore>.jks
ssl.truststore.password=<kafka_connect_truststore_password>

The Connect worker’s Kafka clients use the same truststore. If the worker connects to Kafka over TLS, the truststore must also include the broker’s CA certificate. Otherwise, the worker can’t connect to Kafka and exits.

Confluent Control Center

As a Kafka client

confluent.controlcenter.kafka.sasl.jaas.config=org.apache.kafka.common.security.oauthbearer.OAuthBearerLoginModule required \
  clientId="<client-id>" \
  ssl.truststore.location="<path_to_control_center_truststore.jks>" \
  ssl.truststore.password="<control_center_truststore_password>" \
  clientSecret="<client-secret>" \
  scope="<scope>";

As a REST client

confluent.controlcenter.rest.ssl.truststore.location=<path_to_control_center_truststore.jks>
confluent.controlcenter.rest.ssl.truststore.password=<control_center_truststore_password>

As a Connect client

confluent.controlcenter.connect.<connect-cluster>.ssl.truststore.location=<path_to_control_center_truststore.jks>
confluent.controlcenter.connect.<connect-cluster>.ssl.truststore.password=<control_center_truststore_password>

Configure Confluent Platform services for hostname verification

When you don’t configure a truststore, Confluent Platform services use the default JVM TLS settings, including hostname verification, to connect to your identity provider.

When you use a custom TLS context (truststore), hostname verification is disabled by default. To enable hostname verification, set the following property for each service. The property name depends on the service:

  • Metadata Service (MDS):

    confluent.metadata.server.confluent.idp.ssl.endpoint.identification.algorithm=https
    
  • Confluent Schema Registry, standalone Confluent REST Proxy, and Kafka Connect (no prefix):

    ssl.endpoint.identification.algorithm=https
    
  • Embedded Confluent REST Proxy:

    kafka.rest.ssl.endpoint.identification.algorithm=https
    

If you need to disable the property, for example when using AWS DNS, delete the configuration property or explicitly set it to blank or empty.