<a id="manage-group-mappings"></a>

# Manage Group Mappings on Confluent Cloud

Use the Confluent Cloud Console, Confluent CLI, Confluent Cloud APIs, or Terraform to manage
group mappings:

- [Create a group mapping](#create-group-mapping)
- [Update a group mapping](#update-group-mapping)
- [Describe a group mapping](#describe-group-mapping)
- [List group mappings](#list-group-mapping)
- [Delete a group mapping](#delete-group-mapping)
- [Add role binding to a group mapping](#add-role-binding-group-mapping)
- [Add ACLs to a group mapping](#add-acls-group-mapping)

<a id="group-mapping-prequisites"></a>

## Prerequisites

- Required RBAC role: [OrganizationAdmin](../../../../../access-control/rbac/predefined-rbac-roles.md#organizationadmin-role) or [AccountAdmin](../../../../../access-control/rbac/predefined-rbac-roles.md#accountadmin-role).
- Confluent CLI version 3.41.0 or later. For help installing the CLI, see [Install Confluent Cloud CLI](https://docs.confluent.io/current/cloud/cli/install.html).

<a id="create-group-mapping"></a>

## Create a group mapping

Before creating any group mappings, an administrator designates a SAML attribute
for Confluent Cloud to extract the assigned group. This is a one-time setup that
applies
to all group mappings. For most organizations, the groups attribute
is the user groups or security groups, but any SAML attribute configured by
the identity provider can be used as groups (such as roles or a custom-defined
attribute).

A group mapping is an association between one or more groups and a set of
Confluent Cloud RBAC roles.

#### NOTE
Users assigned the [OrganizationAdmin](../../../../../access-control/rbac/predefined-rbac-roles.md#organizationadmin-role) role
through a group mapping do not receive email notifications. To receive
notifications, the user must be directly assigned the OrganizationAdmin
role or manually added in the specific notification settings. For details,
see [Notifications for Confluent Cloud](../../../../../../monitoring/configure-notifications.md#ccloud-notifications).

### Confluent Cloud Console

1. Go to the **Group mappings** page
   at [https://confluent.cloud/settings/org/group-mappings](https://confluent.cloud/settings/org/group-mappings).
2. Click **Add group mapping**. The **New Group Mapping** page appears.
3. In the **Group mapping details** section, enter the **Name** and
   **Description** for the group mapping.
4. In the **Map group or attribute value** section, select **Basic** to
   map a simple literal group, or **Advanced** to map groups based on
   a more complex condition.
   - **Basic**: Enter the value for a single group or attribute.
     For example, if the group claim is `groups`, enter the name of
     the group.
   - **Advanced**: Enter a CEL expression that allows mappings of one
     or more groups. Note that setting the value to `true`
     results in the group mapping being applied to all SSO users without
     needing to map to any specific groups from the SAML request.
     For details about CEL expressions, supported CEL filter operators,
     and examples, see [Use CEL expressions for advanced group mappings](#use-cel-expressions-group-mappings).
5. Click **Next**. The **Assign permission** page appears.
6. On the **Assign permission** page, assign the roles to the resources
   that the group mapping can access.
   1. Search for resources or expand the navigation tree and select a
      Confluent Cloud resource: Organization, Environment, Cluster, Topics,
      Schema Registry, Consumer Groups, Transactional IDs, ksqlDB Cluster,
      Connector, or Pipeline.
   2. Select a role and click **Add**. The role addition appears in the
   3. Select a role and click **Add**. The role addition appears in the
      change summary.
   4. Repeat the previous step to add more roles, if needed, to the
      group mapping.
   5. Review your new group mapping and click **Save**. The **Accounts
      & access** page appears displaying the new group mapping in the
      **User group permissions** section.

   You successfully added your new group mapping. If desired, you can
   continue adding group mappings.

### Confluent CLI

Use the `confluent iam group-mapping create` command
([Confluent CLI reference](https://docs.confluent.io/confluent-cli/current/command-reference/iam/group-mapping/confluent_iam_group-mapping_create.html))
to create a group mapping.

For example, the following command creates a group mapping named
`my-group-mapping` that maps the claims for `group` to the
`my-group` group.

```shell
confluent iam group-mapping create my-group-mapping
  --description "new description" \
  --filter "\"my-group\" in groups"
```

### Terraform

Use the `confluent_group_mapping` resource to create a group mapping.

Prerequisites:

- Terraform Provider for Confluent installed, and access to a Confluent Cloud administrator account.

To create a group mapping with Terraform Provider for Confluent, use the following snippet of Terraform configuration:

```terraform
# Configure the Confluent Provider
terraform {
  required_providers {
    confluent = {
      source  = "confluentinc/confluent"
    }
  }
}
provider "confluent" {
  cloud_api_key    = var.confluent_cloud_api_key    # optionally use CONFLUENT_CLOUD_API_KEY env var
  cloud_api_secret = var.confluent_cloud_api_secret # optionally use CONFLUENT_CLOUD_API_SECRET env var
}
...
resource "confluent_group_mapping" "application-developers" {
  display_name = "Application Developers"
  description  = "Admin access to production environment for Engineering"
  filter       = "\"engineering\" in groups"
}
# Create more resources ...
```

You must provide appropriate Confluent Cloud credentials to use
the provider.

For the full `confluent_group_mapping` resource reference, see the
[Confluent Terraform Provider documentation](https://registry.terraform.io/providers/confluentinc/confluent/latest/docs/resources/confluent_group_mapping)
in the Terraform registry.

<a id="update-group-mapping"></a>

## Update a group mapping

### Confluent Cloud Console

1. Go to the **Group mappings** page
   at [https://confluent.cloud/settings/org/group-mappings](https://confluent.cloud/settings/org/group-mappings).
2. In the table of group mappings under **User group permissions**, click
   the group mapping under **Name** that you want to update. The group
   mapping details page appears.
3. Edit the **Settings (\*\*Name** and **Description** fields) or **Mapping**
   for the group mapping, and click **Save**.

   You can edit the lines directly in the **Mapping** section, or click
   **Edit existing access** to open the **New access for <group-mapping-name>**
   page, assign roles to resources, and click **Save**. For available CEL
   operators and examples, see [Supported CEL filter operators](#supported-cel-operators-group-mapping).
4. Click **Save** to save your group mapping updates.

The group mapping is updated and the **Accounts & access** page reappears
displaying the updated group mapping in the **User group permissions**
section.

### Confluent CLI

Use the `confluent iam group-mapping update` command
([Confluent CLI reference](https://docs.confluent.io/confluent-cli/current/command-reference/iam/group-mapping/confluent_iam_group-mapping_update.html))
to update a group mapping.

For example, the following command updates the `my-group` group
to update the description to `updated description`.

```shell
confluent iam group-mapping update my-group \
  --description "updated description"
```

### Terraform

Use the `confluent_group_mapping` resource to update a group mapping.

For the full `confluent_group_mapping` resource reference, see the
[Confluent Terraform Provider documentation](https://registry.terraform.io/providers/confluentinc/confluent/latest/docs/resources/confluent_group_mapping)
in the Terraform registry.

<a id="describe-group-mapping"></a>

## Describe a group mapping

### Confluent Cloud Console

1. Go to the **Group mappings** page
   at [https://confluent.cloud/settings/org/group-mappings](https://confluent.cloud/settings/org/group-mappings).
2. In the table of group mappings under **User group permissions**, click the
   name of the group mapping you want to see the details for.

   The group mapping details view appears.

### Confluent CLI

Use the `confluent iam group-mapping describe` command
([Confluent CLI reference](https://docs.confluent.io/confluent-cli/current/command-reference/iam/group-mapping/confluent_iam_group-mapping_describe.html))
to describe a group mapping. For example, the following command describes
the `my-group-mapping` group mapping with the ID `group-123456`:

```shell
confluent iam group-mapping describe group-123456
```

<a id="list-group-mapping"></a>

## List group mappings

### Confluent Cloud Console

1. Go to the **Group mappings** page
   at [https://confluent.cloud/settings/org/group-mappings](https://confluent.cloud/settings/org/group-mappings).

The group mappings are listed with their **Name**, **Mapping**, **Group
mapping ID**, and **Description**. Click on a group mapping name to view
the details of the group mapping.

### Confluent CLI

Use the `confluent iam group-mapping list` command
([Confluent CLI reference](https://docs.confluent.io/confluent-cli/current/command-reference/iam/group-mapping/confluent_iam_group-mapping_list.html))
to list group mappings.

For example, the following command lists the group mappings and outputs
the results in JSON format.

```shell
confluent iam group-mapping list \
  --output json
```

<a id="delete-group-mapping"></a>

## Delete a group mapping

You can delete a group mapping if you are no longer using it. Because you cannot
temporarily disable a group mapping, you must delete the group mapping.

### Confluent Cloud Console

1. Go to the **Group mappings** page
   at [https://confluent.cloud/settings/org/group-mappings](https://confluent.cloud/settings/org/group-mappings).
2. In the table of group mappings under **User group permissions**, hover
   your cursor over the row you want to delete and click **Delete** (trash
   can icon) . The **Confirm deletion** dialog appears.
3. When you are sure you want to delete the group mapping, enter the group
   mapping ID to confirm, and click **Confirm**.

The group mapping is deleted and the **Accounts & access** page appears
displaying the remaining group mappings in the **User group permissions**
section.

### Confluent CLI

Use the `confluent iam group-mapping delate` command
([Confluent CLI reference](https://docs.confluent.io/confluent-cli/current/command-reference/iam/group-mapping/confluent_iam_group-mapping_delete.html#))
to delete a group mapping. For example, the following command deletes
the `my-group-mapping` group mapping with the ID `group-123456`:

```shell
confluent iam group-mapping delete group-123456
```

### Terraform

Use the `confluent_group_mapping` resource to delete a group mapping.

For the full `confluent_group_mapping` resource reference, see the
[Confluent Terraform Provider documentation](https://registry.terraform.io/providers/confluentinc/confluent/latest/docs/resources/confluent_group_mapping)
in the Terraform registry.

<a id="use-cel-expressions-group-mappings"></a>

## Use CEL expressions for advanced group mappings

You can create advanced group mappings that associate groups of users in your
SSO identity provider with Confluent Cloud RBAC roles by using Common Expression Language
(CEL) expressions and the supported CEL filter operators.
[Common Expression Language (CEL)](https://github.com/google/cel-spec#readme)
is a lightweight, open-source expression language designed for creating portable,
secure, and efficient rule evaluations.

CEL expressions are complete logical statements that evaluate to true or false
based on input data. In Confluent Cloud, the keyword groups refers to the array of
groups extracted from the SAML attribute provided by your SSO identity provider.
These expressions match user identity attributes from your SSO provider to
appropriate RBAC permissions. CEL filter operators (such as `IN`, `AND`, `OR`,
`startsWith`, and `endsWith`) can be used to construct these expressions
and create advanced matching conditions based on group membership patterns.

For example, a simple expression like `"kafka-admin" in groups` checks if a
user belongs to that specific group, while more complex expressions like this:

```text
groups.exists(group, group.startsWith("dev-")) && "reader" in groups
```

combine multiple conditions to create precise access control rules based on
organizational group structures.

<a id="supported-cel-operators-group-mapping"></a>

### Supported CEL filter operators

The following CEL filter operators are supported for creating
complex group mapping filters in Confluent Cloud. Operators are grouped by type and
listed in order of precedence (highest to lowest). For detailed syntax and examples,
see the sections below.

| Type    | Tests if a value exists in the groups array.                                                           |
|---------|--------------------------------------------------------------------------------------------------------|
| Syntax  | `value in array`                                                                                       |
| Example | ```text<br/>"everyone" in groups<br/>```<br/><br/>Returns `true` for `groups = ["everyone", "users"]`. |

<a id="logical-operators"></a>

#### Logical operators

##### AND

| Type    | Logical operator that evaluates if both conditions are true.                                                             |
|---------|--------------------------------------------------------------------------------------------------------------------------|
| Syntax  | `expr && expr`                                                                                                           |
| Example | ```text<br/>"kafka" in groups && "all" in groups<br/>```<br/><br/>Returns `true` for `groups = ["kafka", "all", "dev"]`. |

##### OR

| Type    | Logical operator that evaluates if either condition is true.                                                                 |
|---------|------------------------------------------------------------------------------------------------------------------------------|
| Syntax  | `expr || expr`                                                                                                               |
| Example | ```text<br/>"google" in groups || "confluent" in groups<br/>```<br/><br/>Returns `true` for `groups = ["confluent", "dev"]`. |

<a id="inclusion-test-operator"></a>

#### Inclusion test operator

##### IN

| Type    | Tests if a value exists in the groups array.                                                           |
|---------|--------------------------------------------------------------------------------------------------------|
| Syntax  | `value in array`                                                                                       |
| Example | ```text<br/>"everyone" in groups<br/>```<br/><br/>Returns `true` for `groups = ["everyone", "users"]`. |

<a id="string-operators"></a>

#### String operators

##### startsWith

| Type    | Tests if any group begins with the specified prefix.                                                                                                |
|---------|-----------------------------------------------------------------------------------------------------------------------------------------------------|
| Syntax  | `groups.exists(group, group.startsWith(prefix))`                                                                                                    |
| Example | ```text<br/>groups.exists(group, group.startsWith("kafka-"))<br/>```<br/><br/>Returns `true` for `groups = ["kafka-prod-admin", "kafka-dev-user"]`. |

##### endsWith

| Type    | Tests if any group ends with the specified suffix.                                                                                         |
|---------|--------------------------------------------------------------------------------------------------------------------------------------------|
| Syntax  | `groups.exists(group, group.endsWith(suffix))`                                                                                             |
| Example | ```text<br/>groups.exists(group, group.endsWith("-admin"))<br/>```<br/><br/>Returns `true` for `groups = ["kafka-admin", "system-admin"]`. |

<a id="add-role-binding-group-mapping"></a>

## Add role binding to a group mapping

You can add role bindings to a group mapping to grant RBAC roles for resources.

When adding role bindings, the principal is defined as `User:group-<ID>`, where
`<ID>` is the group mapping ID. For example, `User:group-DApG`.

Here’s an example showing how to add role bindings to a group mapping using
the Confluent CLI:

```shell
confluent iam rbac role-binding create \
  --principal User:group-DApG \
  --role CloudClusterAdmin \
  --environment env-y0t432 \
  --cloud-cluster lkc-8qrnp
```

Note that the group is defined as `User:group-DApG`. The group is
defined as a `User` resource type, with the resource ID of the group
mapping. The group mapping ID is `group-DApG`.

For more information, see [Confluent CLI Reference: confluent iam rbac role-binding create](https://docs.confluent.io/confluent-cli/current/command-reference/iam/rbac/role-binding/confluent_iam_rbac_role-binding_create.html).

You can use the [Confluent Terraform Provider](../../../../../../clusters/terraform-provider.md#confluent-terraform-provider)
to map a role binding to a group. For the full `confluent_group_mapping`
resource reference, see the
[Confluent Terraform Provider documentation](https://registry.terraform.io/providers/confluentinc/confluent/latest/docs/resources/confluent_group_mapping)
in the Terraform registry.

<a id="add-acls-group-mapping"></a>

## Add ACLs to a group mapping

You can add Access Control Lists (ACLs) to a group mapping to grant or deny
specific Kafka operations on resources like topics, consumer groups, or clusters.
For more information, see the [Confluent Cloud API](/cloud/current/api.html#tag/ACL-(v3)/operation/createKafkaAcls) .

When adding ACLs, the principal is defined as `User:group-<ID>`, where `<ID>`
is the group mapping ID. For example, `User:group-ivkf`.

The following examples show how to add ALLOW and DENY ACLs for a group mapping.
The REST endpoint is defined with `pkc-78942` with your Kafka cluster’s REST endpoint.
The cluster ID is `lkc-54098`. The group mapping ID is `group-ivkf`.
You must provide valid API credentials in the Authorization header.

### Add an ALLOW ACL

This example creates an ALLOW ACL that grants WRITE operations
on a topic named `team-topic` for users in the group mapping `group-ivkf`:

```bash
curl -X POST \
  https://pkc-78942.us-east-2.aws.confluent.cloud:443/kafka/v3/clusters/lkc-54098/acls \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic <base64-encoded-api-key:api-secret>" \
  -d '{
    "resource_type": "TOPIC",
    "resource_name": "team-topic",
    "pattern_type": "LITERAL",
    "principal": "User:group-ivkf",
    "host": "*",
    "operation": "WRITE",
    "permission": "ALLOW"
  }'
```

### Add a DENY ACL

This example creates a DENY ACL on a topic named `sensitive-topic`
that prevents all operations for users in the group mapping `group-ivkf`:

```bash
curl -X POST \
  https://pkc-78942.us-east-2.aws.confluent.cloud:443/kafka/v3/clusters/lkc-54098/acls \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic <base64-encoded-api-key:api-secret>" \
  -d '{
    "resource_type": "TOPIC",
    "resource_name": "sensitive-topic",
    "pattern_type": "LITERAL",
    "principal": "User:group-ivkf",
    "host": "*",
    "operation": "ALL",
    "permission": "DENY"
  }'
```