Troubleshoot Mutual TLS (mTLS) issues in Confluent Cloud

Review the following to troubleshoot issues frequently encountered when connecting to Confluent Cloud using mTLS. If you are unable to resolve issues using the information below, contact Confluent Support.

TLS client connection behavior

The following listings describe the behavior of the TLS client when connecting to Confluent Cloud using mTLS.

  • Context is a single Confluent Cloud organization.
  • “N/A” means that the state of the subject is not considered.

External identifier

When using the REST API, ensure that you are using the correct field names and that the REST endpoints are specifically for certificate identity pools, not OAuth identity pools. For instance, the attribute name for a certificate identity pool is external_identifier, whereas an OAuth identity pool uses the identity_claim attribute.

Client connection behavior (TLS)

Client connection (TLS) Identity providers (for CA certificates) [server state] Certificate identity pools (of identity provider) [server state] Permission on certificate identity pool (to perform action on resource) [server state] Outcome (client-side) Explanation
Without keystore N/A N/A N/A Request timed out The client doesn’t provide a certificate, so it doesn’t have authentication information, resulting in a timed out response.
With keystore but client certificate is expired N/A N/A N/A TLS handshake error Because the client certificate is expired, the TLS handshake fails.
With keystore and client certificate is not expired No identity provider N/A N/A Request timed out The server doesn’t have information to verify the client certificate, resulting in an authentication error that leads to a timed out response.
With keystore and client certificate is not expired Identity provider signs client certificate but CA certificates are expired N/A N/A Request timed out Confluent routinely removes expired CA certificates from the truststore. Just like the no identity provider situation, this leads to a timed out response on the client. If the CA needs to be revoked immediately, then the corresponding certificate authority can be deleted from the Confluent Cloud organization after removing the CA’s attached certificate identity pools.
With keystore and client certificate is not expired Identity provider signs client certificate No matching certificate identity pool found N/A Request timed out When no certificate identity pool is found for the identity provider, an authentication error occurs, leading to a timed out response for the client.
With keystore and client certificate is not expired Identity provider signs client certificate With certificate identity pool No Authorization error If the principal doesn’t have permission to perform an action on a resource, an authorization error is expected.
With keystore and client certificate is not expired Identity provider signs client certificate With certificate identity pool Yes Request successful The client is authenticated successfully.
With librdkafka-based SSL/SASL_SSL client Identity provider signs client certificate Without certificate identity pool No TLS handshake error Confirm that the corresponding certificate authority configured in Confluent Cloud contains the signing certificate of the client certificate in the client keystore.

X.509 v3 extensions behavior

If a client receives an SSL handshake error and all Confluent Cloud and client configurations are correctly configured, then the issue might be with the client certificate itself.

If a client certificate declares the following X.509 v3 extensions, then the certificate is valid only if the extensions satisfy these conditions, in accordance with RFC 5280, which states that “If the extension is present, then the certificate MUST only be used for one of the purposes indicated.”

  • The Key Usage extension , which defines the purpose (for example, encipherment, signature, certificated signing) of the key contained in the certificate, must have digitalSignature as one of the purposes. For details, see 4.2.1.3. Key Usage (in RFC 5280).
  • The Extended Key Usage extension (indicates one or more purposes for which the certified public key might be used, in addition to or in place of the basic purposes indicated in the key usage extension) must have clientAuth as one of the purposes. For details, see 4.2.1.12 Extended Key Usage (in RFC 5280).

Note that if both the Key Usage and Extended Key Usage extensions are present, then the certificate is valid only if the purpose is consistent with both extensions.

Related content