<a id="manage-identity-pool-mtls"></a>

# 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](../../../../../_glossary.md#term-granularity). 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.

#### NOTE
If your organization needs higher limits for mTLS certificate identity pools,
see the [Advanced Security add-on](../../../../advanced-security.md#advanced-security-add-on). The
add-on increases the limit for organizations that need more certificate-based
workload identities. For default limits,
see [mTLS service quotas](../../../../../quotas/service-quotas.md#ccloud-resource-limits-mtls).

The Advanced Security add-on is a Limited Availability feature in Confluent Cloud.
For more information, see [Advanced Security add-on for Confluent Cloud](../../../../advanced-security.md#advanced-security-add-on).

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](../../../../access-control/rbac/predefined-rbac-roles.md#organizationadmin-role)
* [AccountAdmin](../../../../access-control/rbac/predefined-rbac-roles.md#accountadmin-role)
* [EnvironmentAdmin](../../../../access-control/rbac/predefined-rbac-roles.md#environmentadmin-role)
* [CloudClusterAdmin](../../../../access-control/rbac/predefined-rbac-roles.md#cloudclusteradmin-role)
* [KsqlAdmin](../../../../access-control/rbac/predefined-rbac-roles.md#ksqladmin-role)
* [ResourceOwner](../../../../access-control/rbac/predefined-rbac-roles.md#resourceowner-role)

<a id="create-identity-pool-mtls"></a>

## 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](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](../../../../access-control/rbac/predefined-rbac-roles.md#resourceowner-role)
   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](cel-filters.md#create-cel-filters-mtls).
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.

```shell
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:

```shell
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:

```shell
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.

```shell
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:

```shell
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)](https://docs.confluent.io/cloud/current/ccloud/create-iam-v-2-certificate-authority/).

### Terraform

Use the [confluent_certificate_pool](https://registry.terraform.io/providers/confluentinc/confluent/latest/docs/resources/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](https://registry.terraform.io/providers/confluentinc/confluent/latest/docs/resources/confluent_certificate_authority)
resource to manage it.

<a id="describe-identity-pool-mtls"></a>

## 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](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.

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

For details, run the following CLI command:

```shell
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.

```shell
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)](https://docs.confluent.io/cloud/current/ccloud/get-iam-v-2-certificate-authority/).

### Terraform

Use the [confluent_certificate_pool](https://registry.terraform.io/providers/confluentinc/confluent/latest/docs/data-sources/confluent_certificate_pool)
data source to look up an existing certificate identity pool by ID or name.

<a id="list-identity-pools-mtls"></a>

## 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](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.

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

For details, run the following CLI command:

```shell
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.

```shell
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)](https://docs.confluent.io/cloud/current/ccloud/list-iam-v-2-certificate-authorities/).

### Terraform

Terraform doesn’t provide a list operation for certificate identity
pools. Use the [confluent_certificate_pool](https://registry.terraform.io/providers/confluentinc/confluent/latest/docs/data-sources/confluent_certificate_pool)
data source to look up a specific pool, or run `terraform state
list` to see the pools defined in your configuration.

<a id="update-identity-pool-mtls"></a>

## 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](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.

```shell
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.

```shell
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)](https://docs.confluent.io/cloud/current/ccloud/update-iam-v-2-certificate-authority/).

### Terraform

Update the `description`, `external_identifier`, or `filter`
attribute in your [confluent_certificate_pool](https://registry.terraform.io/providers/confluentinc/confluent/latest/docs/resources/confluent_certificate_pool)
resource block, then run `terraform apply`.

<a id="delete-identity-pool-mtls"></a>

## 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](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.

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

For details, run the following CLI command:

```shell
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.

```shell
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)](https://docs.confluent.io/cloud/current/ccloud/delete-iam-v-2-certificate-authority/).

### Terraform

Remove the [confluent_certificate_pool](https://registry.terraform.io/providers/confluentinc/confluent/latest/docs/resources/confluent_certificate_pool)
resource block from your configuration and run `terraform apply`,
or run `terraform destroy -target=confluent_certificate_pool.<resource_name>`.

<a id="multiple-identity-pools-mtls"></a>

## 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](https://docs.confluent.io/cloud/current/ccloud/certificate-identity-pools-iam-v-2/)
* [Manage Certificate Authorities for mTLS authentication on Confluent Cloud](certificate-authority.md#manage-certificate-authority-mtls)
* [Troubleshoot Mutual TLS (mTLS) issues in Confluent Cloud](troubleshoot.md#troubleshoot-mtls)
* [Use Mutual TLS (mTLS) to Authenticate to Confluent Cloud Resources](overview.md#mtls-overview)
* [Confluent Resource Names](../../../../access-control/hierarchy/confluent-resource-names.md#confluent-resource-names)
* [Predefined RBAC Roles](../../../../access-control/rbac/predefined-rbac-roles.md#cloud-rbac-roles)
* [Role Bindings (iam/v2) [Confluent Cloud API]](https://docs.confluent.io/cloud/current/ccloud/role-bindings-iam-v-2/)
* [Certificate Identity Pools (iam/v2) [Confluent Cloud API]](https://docs.confluent.io/cloud/current/ccloud/certificate-identity-pools-iam-v-2/)
* [Create CEL Filters for mTLS Authentication](cel-filters.md#create-cel-filters-mtls)