Manage Certificate Authorities for mTLS authentication on Confluent Cloud¶

You can manage trusted certificate authorities (CAs) for mTLS authentication using the Confluent Cloud Console, Confluent CLI, and Confluent Cloud APIs. The following sections describe how to create, describe, update, delete certificate authorities, and how email notifications are sent when certificates in a configured Certificate Authority are approaching expiration.

Create a Certificate Authority¶

To create a Certificate Authority (CA) to use with X.509 client certificate authentication for mTLS, follow these steps.

To create a certificate authority using the Confluent Cloud Console:

In the Confluent Cloud Console, go to Account & access, then click Workload identities. Alternatively, click https://confluent.cloud/settings/org/workload-identities.
Click Add provider. The New identity provider page displays.
Select Certificate authority for the authentication type.
Enter the following details:

Name Enter a meaningful name for your certificate authority.

Description (Optional) Enter a description for the certificate authority.
Click Add PEM file to upload the Certificate Authority (CA). Provide the certificate chain containing the root and any intermediate CAs used to verify client certificates. For details, see Requirements for mTLS.
(Optional) Click Upload CRL file to upload the Certificate Revocation List (CRL). If the PEM file you uploaded contains the CRL URL, this is auto-populated. You can also manually provide the CRL URL.
Confirm your Certificate Authority configuration details. The serial number and SHA-1 fingerprints are provided to let you match the values in your Certificate Authority with the values with your local files.
Click Validate and save.

For details, see:

Certificate revocation for mTLS authentication on Confluent Cloud

To create a Certificate Authority using the Confluent CLI, use the following CLI command, replacing <ca-name> with the name of the Certificate Authority:

confluent iam certificate-authority create --name <ca-name> [flags]

Example

Create the Certificate Authority “my-ca” using the certificate chain stored in the CERTIFICATE_CHAIN environment variable:

confluent iam certificate-authority create my-ca \
  --description "my certificate authority" \
  --certificate-chain $CERTIFICATE_CHAIN \
  --certificate-chain-filename certificate.pem

If you are configuring with a Certificate Revocation List (CRL), use --crl-url "http://domain.certificate-revocation.crl" or --crl-chain "<base64_encoded_crl_chain>".

To create a certificate authority using the REST API, use the following HTTP POST request:

POST https://api.confluent.cloud/iam/v2/certificate-authorities

To create a JSON payload for creating a certificate authority, you can use the following example as a template. crl_url is optional, and can be substituted with --arg crl_chain "$(cat path/to/<crl-filename>.pem)".

json_payload=$(jq -n \
  --arg name "<ca-name>" \
  --arg description "<ca-description>" \
  --arg certificate_chain "$(cat path/to/<ca-chain-filename>.pem)" \
  --arg certificate_chain_filename "<ca-chain-filename>.pem" \
  --arg crl_url "<crl_url>" \
  '{
    display_name: $name,
    description: $description,
    certificate_chain: $certificate_chain,
    certificate_chain_filename: $certificate_chain_filename,
    crl_url: $crl_url
  }');

JSON Payload Fields¶
Field	Description
display_name	The name of the certificate authority. Replace `<ca-name>` with your desired name.
description	(Optional) A description of the certificate authority. Replace `<ca-description>` with your description.
certificate_chain	The base64 encoded certificate chain. Replace `<base64_encoded_certificate_chain>` with your certificate chain.
certificate_chain_filename	The filename of the certificate chain. Replace `<certificate_chain_filename>` with your filename.
crl_url	(Optional) The URL of the Certificate Revocation List (CRL). Replace `<crl_url>` with your CRL URL.
crl_chain	(Optional) The Base64-encoded CRL chain. Replace `<base64_encoded_crl_chain>` with your CRL chain.

For details, see the Create a Certificate Authority (API Reference).

Describe a Certificate Authority¶

To get the details of a certificate authority, follow these steps.

To get the details of a certificate authority:

In the Confluent Cloud Console, go to Account & access, then click Workload identities. Alternatively, click https://confluent.cloud/settings/org/workload-identities.
Click the name of the certificate authority. The Certificate authority details page displays.

To get the details of a certificate authority, use the following CLI command, replacing <ca-id> with the ID of the certificate authority:

confluent iam certificate-authority describe <ca-id>

For details on the confluent iam certificate-authority describe command, run the following CLI command:

confluent iam certificate-authority describe --help

To get the details of a certificate authority, use the following HTTP GET request, replacing <certificate-authority-id> with the ID of the certificate authority:

GET https://api.confluent.cloud/iam/v2/certificate-authorities/<certificate-authority-id>

For details, see the Read a Certificate Authority (API Reference).

List all Certificate Authorities¶

To get a list of all Certificate Authorities, follow these steps.

To get a list of all Certificate Authorities:

In the Confluent Cloud Console, go to Account & access, then click Workload identities. Alternatively, click https://confluent.cloud/settings/org/workload-identities.

The list of Certificate Authorities is displayed.

To get a list of all Certificate Authorities, use the following CLI command:

confluent iam certificate-authority list

For details on the confluent iam certificate-authority list command, run the following CLI command:

confluent iam certificate-authority list --help

To get a list of all Certificate Authorities, use the following HTTP GET request:

GET https://api.confluent.cloud/iam/v2/certificate-authorities

For details, see the List of Certificate Authorities (API Reference).

Update a Certificate Authority¶

To update a configured Certificate Authority, follow these steps.

To update a Certificate Authority:

In the Confluent Cloud Console, go to Account & access, then click Workload identities. Alternatively, click https://confluent.cloud/settings/org/workload-identities.
Click the name of the Certificate Authority. The Certificate authority details page displays.
Click Edit to update the Certificate Authority details.
Update the Certificate Authority details.
Click Save.

To update the description of a Certificate Authority, use the following CLI command, replacing <ca-id> with the ID of the Certificate Authority and add any of the following optional arguments:

confluent iam certificate-authority update <ca-id> \
  --name "<ca-name>" \
  --description "<ca-description>" \
  --certificate-chain "<base64_encoded_certificate_chain>" \
  --certificate-chain-filename "<certificate_chain_filename>" \
  --output "<output_format>"

For details on the confluent iam certificate-authority update command, run the following CLI command:

confluent iam certificate-authority update --help

To update a Certificate Authority, use an HTTP PUT request to https://api.confluent.cloud/iam/v2/certificate-authorities/ca-id, replacing <ca-id> with the ID of the Certificate Authority and adding the fields to update.

For example, you can update the CRL manually using a local CRL file, replacing <base64_encoded_crl_chain> with the Base64-encoded CRL chain:

json_payload=$(jq -n --arg crl_chain \
  "$(cat <path/to/crl_file>.pem)" \
  '{crl_chain: $crl_chain}');

For details, see the Update a Certificate Authority (API Reference).

Delete a Certificate Authority¶

To delete a Certificate Authority, follow these steps.

Important

Before deleting a Certificate Authority, you must delete any identity pools that reference the Certificate Authority.

To delete a Certificate Authority:

In the Confluent Cloud Console, go to Account & access, then click Workload identities. Alternatively, click https://confluent.cloud/settings/org/workload-identities.
Click the name of the Certificate Authority that you want to delete. The Certificate authority details page displays.
Click Edit.
At the bottom of the page, click Delete certificate authority.

After confirming the deletion, the Certificate Authority is deleted.

To delete a Certificate Authority, use the following CLI command, replacing <ca-id> with the ID of the Certificate Authority:

confluent iam certificate-authority delete <ca-id>

For details on the confluent iam certificate-authority delete command, run the following CLI command:

confluent iam certificate-authority delete --help

To delete a Certificate Authority, use the following HTTP DELETE request, replacing <ca-id> with the ID of the Certificate Authority:

DELETE https://api.confluent.cloud/iam/v2/certificate-authorities/<ca-id>

For details, see the Delete a Certificate Authority (API Reference).

Email notifications¶

As certificates in a configured Certificate Authority approach their expiration dates, email notifications, titled “Action Required: Update expiring certificate authority”, are sent to principals with the Organization Admin role. These email notifications are sent progressively more often (60 days, 30 days, 7 days, 3 days, 2 days, and 1 day before expiration) until the Certificate Authority is updated. If all certificates in a configured Certificate Authority are expired, then any client certificates intended to authenticate with the expired Certificate Authority fail.