Manage Certificate Identity Pools for mTLS authentication on Confluent Cloud

You can create a certificate identity pool to map a client certificate with a Confluent Cloud identity that has granular permissions. By using certificate identity pools, you can enable varying levels of access to your Confluent Cloud resources for different client certificates issued by your Certificate Authority.

You can create, update, and delete certificate identity pools using the Confluent Cloud Console, the Confluent CLI, and the Confluent Cloud APIs. Follow the steps in the following sections to create, describe, list, and delete certificate identity pools for mTLS authentication.

Required RBAC roles: One of the following:

• OrganizationAdmin

• AccountAdmin

• EnvironmentAdmin

• CloudClusterAdmin

• KsqlAdmin

• ResourceOwner

Create a certificate identity pool for mTLS

You can create a certificate identity pool for mTLS using the Confluent Cloud Console, the Confluent CLI, and the Confluent Cloud APIs.

Confluent Cloud Console

To create a certificate identity pool for mTLS:

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

2. Select the identity provider that you want to use to create the certificate identity pool.

3. Click Add identity pool if none exists; otherwise, click Add pool. The New identity pool page displays.

4. Configure the certificate identity pool using the following fields:

   • Name: A name for the certificate identity pool.

   • Description: A description for the certificate identity pool.

5. Under Add identity pool owner, grant the ResourceOwner role to the account that owns the certificate identity pool. This account can manage, edit, assign, and delete this identity pool.

   • Account type: Select the account type that owns the certificate identity pool.

   • Account: Select the account that owns the certificate identity pool.

   Note that if you do not specify an account, only OrganizationAdmin and AccountAdmin roles can manage the identity pool after creation.

6. Under Add certificate identifier, select the specific certificate metadata extracted from certificates to uniquely identify clients during authentication. Defaults to CN. This value appears in audit log records where the authentication method was mTLS.

7. Under Set filters (required), set up filters to specify which identities can authenticate using your certificate identity pool. For details, see Create CEL Filters for mTLS Authentication on Confluent Cloud.

8. Click Next. The summary page displays.

9. Review the confirmation page and then click Validate and save. The certificate identity pool is created and added to the list of identity pools.

Confluent CLI

To create a certificate identity pool for mTLS, use the following CLI command, replacing the placeholder values with your own values. The certificate identity pool name and provider are required.

confluent iam certificate-pool create <cert_identity_pool_name> \
  --description "<description>" \
  --resource-owner <principal-id> \
  --provider <ca-id> \
  --filter "<filter>" \
  --external-identifier "<external-identifier>"

The --resource-owner parameter is recommended if the user is not an OrganizationAdmin or AccountAdmin. The --resource-owner parameter specifies the principal ID (user, service account, identity pool, or group mapping) of the account that will own the certificate identity pool. The principal ID should not include the prefix (for example, User:).

Requires CLI version 4.18.0 or later.

Here is an example:

confluent iam certificate-pool create my-cert-pool \
  --description "My certificate identity pool" \
  --resource-owner u-111aaa \
  --provider ca-1234567890

For details, run the following CLI command:

confluent iam certificate-pool create --help

REST API

Make an HTTP POST request to the mTLS certificate identity pool endpoint, replacing the placeholder values with your own values. For the AssignedResourceOwner parameter, specify the principal ID (user, service account, identity pool, or group mapping) that will own the certificate identity pool. The owner will have full management permissions over the identity pool. If not specified, only OrganizationAdmin and AccountAdmin roles can manage the pool.

Specify the owner account without the prefix. For example, if the resource owner is User:u-111aaa, include AssignedResourceOwner=u-111aaa in the request.

curl -X POST \
  -H "Authorization: <Basic or Bearer Auth>" \
  -H 'Content-Type: application/json' \
  -d '{"display_name": "<certificate pool name>",
     "description": "<description>",
     "filter":"<filter>",
     "external_identifier": "<external identifier>"}' \
  https://api.confluent.cloud/iam/v2/certificate-authorities/<certificate_authority_id>/identity-pools?AssignedResourceOwner=<resource-owner>

Here’s an example:

curl -X POST \
  -H "Authorization: <Basic or Bearer Auth>" \
  -H 'Content-Type: application/json' \
  -d '{"display_name": "My Certificate Identity Pool",
     "description": "Prod Access to Kafka clusters to Release Engineering",
     "filter": "CN == \"my-client\"",
     "external_identifier": "CN"}' \
  https://api.confluent.cloud/iam/v2/certificate-authorities/ca-1234567890/identity-pools?AssignedResourceOwner=u-111aaa

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

Terraform

Use the confluent_certificate_pool Terraform resource to create, edit, or delete certificate identity pools on Confluent Cloud. The pool’s parent certificate authority must already exist; use the confluent_certificate_authority resource to manage it.

Describe a certificate identity pool for mTLS

Get the details of a certificate identity pool for mTLS.

Confluent Cloud Console

To describe a certificate identity pool for mTLS:

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

2. Click the name of the certificate authority that contains the identity pool you want to describe. The Certificate Authority details page displays.

3. Click the name of the certificate identity pool. The Overview page displays.

Confluent CLI

To describe a certificate identity pool for mTLS, use the following CLI command, replacing the placeholder values with your own values.

confluent iam certificate-pool describe <certificate-pool-id> \
  --provider <ca-id>

For details, run the following CLI command:

confluent iam certificate-pool describe --help

REST API

Make an HTTP GET request to the mTLS certificate identity pool endpoint with a specified certificate identity pool ID, replacing the placeholder values with your own values.

curl -X GET \
  -H 'Authorization: <Basic or Bearer Auth>' \
  'https://api.confluent.cloud/iam/v2/certificate-authorities/{provider_id}/identity-pools/{id}'

For details, see the Get a Certificate Identity Pool (API Reference).

List certificate identity pools for mTLS

Get a list of the certificate identity pools for mTLS.

Confluent Cloud Console

To see a list of your certificate identity pools for mTLS:

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

2. Click the name of the certificate authority you want to see the certificate identity pools for. The Certificate Authority details page displays.

For the list of certificate identity pools, see the Identity pools section. The list of certificate identity pools includes the following details:

• Name

• Pool ID

• Description

To see the details of a specific certificate identity pool, click the name of the certificate identity pool. The certificate identity pool details page displays.

Confluent CLI

To list the certificate identity pools for mTLS, use the following CLI command, replacing the placeholder values with your own values.

confluent iam certificate-pool list \
  --provider <ca-id>

For details, run the following CLI command:

confluent iam certificate-pool list --help

REST API

Make an HTTP GET request to the mTLS certificate identity pool endpoint, replacing the placeholder values with your own values.

curl -X GET \
  -H 'Authorization: <Basic or Bearer Auth>' \
  'https://api.confluent.cloud/iam/v2/certificate-authorities/{provider_id}/identity-pools'

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

Update a certificate identity pool for mTLS

Update the details of a certificate identity pool for mTLS, such as the name, description, filter, and certificate identifier.

Confluent Cloud Console

To update the details of a certificate identity pool for mTLS:

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

2. Click the name of the certificate authority containing the identity pool you want to update.

3. Click the name of the certificate identity pool you want to update. The Overview page displays.

4. Click Edit next to any of the following fields to modify them:

   • Name: Update the name of the certificate identity pool.

   • Description: Modify the description.

   • Filter: Update the filter expression that determines which certificates can authenticate.

   • Certificate identifier: Change how clients are identified in audit logs.

5. To modify permissions:

   1. Click Edit existing access in the Access section

   2. Add or remove role bindings as needed

   3. Click Save to apply the permission changes

6. To update the identity pool owner:

   1. Click Edit in the Identity pool owner section

   2. Select a new account type and account

   3. Click Save to apply the ownership change

7. Review your changes and click Save to apply all modifications and return to the Certificate Authority page.

Note: Some fields may be read-only depending on your access level. Only identity pool owners, OrganizationAdmins, and AccountAdmins can modify certain settings.

Confluent CLI

To update the details of a certificate identity pool for mTLS, use the following CLI command, replacing the placeholder values with your own values. The --provider flag is required to identify the certificate authority that owns the pool.

confluent iam certificate-pool update <certificate-pool-id> \
  --provider <ca-id> \
  --name <certificate-pool-name> \
  --description <description> \
  --filter <filter> \
  --external-identifier <external-identifier>

REST API

Make an HTTP PUT request to the mTLS certificate identity pool endpoint with a specified certificate identity pool ID, replacing the placeholder values with your own values.

curl -X PUT \
  -H 'Authorization: <Basic or Bearer Auth>' \
  -H 'content-type: application/json' \
  -d '{"display_name":"My Certificate Identity Pool","description":"Prod Access to Kafka clusters to Release Engineering"}' \
  'https://api.confluent.cloud/iam/v2/certificate-authorities/{provider_id}/identity-pools/{id}'

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

Delete a certificate identity pool for mTLS

Delete a certificate identity pool for mTLS.

Confluent Cloud Console

To delete a certificate identity pool for mTLS:

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

2. Click the name of the certificate authority you want to delete the certificate identity pool for. The Certificate Authority details page displays.

3. Hover over the name of the certificate identity pool you want to delete and click the trash icon to delete the certificate identity pool.

The certificate identity pool is deleted.

Confluent CLI

To delete a certificate identity pool for mTLS, use the following CLI command, replacing the placeholder values with your own values.

confluent iam certificate-pool delete <certificate-pool-id>

For details, run the following CLI command:

confluent iam certificate-pool delete --help

REST API

Make an HTTP DELETE request to the mTLS certificate identity pool endpoint with a specified certificate identity pool ID, replacing the placeholder values with your own values.

curl -X DELETE \
  -H 'Authorization: <Basic or Bearer Auth>' \
  'https://api.confluent.cloud/iam/v2/certificate-authorities/{provider_id}/identity-pools/{id}'

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

Using multiple certificate identity pools

When you use multiple certificate identity pools to map client certificates to granular permissions, here are some important considerations to keep in mind:

• If a client certificate is mapped to multiple certificate identity pools, the client receives the union of permissions from all the mapped identity pools.

• If a client certificate matches multiple certificate identity pools with different certificate identifier values, the certificate identifier is prioritized as follows:

  Priority	Certificate identifier	Maximum length
  1	CN	255 characters
  2	DN	255 characters
  3	Serial number
  4	SAN	255 characters
  5	SHA-1 fingerprint

  Note: If the CN, DN, or SAN exceeds 255 characters, the values used are truncated to 255 characters.

Related content

• Certificate Identity Pools (iamv2) API Reference

• Manage Certificate Authorities for mTLS authentication on Confluent Cloud

• Troubleshoot Mutual TLS (mTLS) issues in Confluent Cloud

• Use Mutual TLS (mTLS) to Authenticate to Confluent Cloud Resources

• Confluent Resource Names

• Predefined RBAC Roles

• Role Bindings (iam/v2) [Confluent Cloud API]

• Certificate Identity Pools (iam/v2) [Confluent Cloud API]

• Create CEL Filters for mTLS Authentication