Manage Group Mappings on Confluent Cloud¶

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

Create a group mapping
Update a group mapping
Describe a group mapping
List group mappings
Delete a group mapping
Add role-binding to a group mapping

Prerequisites¶

Required RBAC role: OrganizationAdmin.
Confluent CLI version 3.41.0 or later. For help installing the CLI, see Install Confluent Cloud CLI.

Create a group mapping¶

An admininstrator starts a group mapping by designating a SAML attribute for Confluent Cloud to extract the assigned group. 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 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.

On the Accounts & access page, click Add group mapping in the User group permissions section. The New Group Mapping page appears.
In the Group mapping details section, enter the Name and Description for the group mapping.
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.
Click Next. The New Group Mapping page appears.
In the New Group Mapping 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. Click Add role assignment. The New role assignment page appears.
3. Select a role and click Add. Under the name of your group mapping, the assigned role appears with the resource and ID.
4. Repeat the previous step to add more roles, if needed, to the group mapping.
5. Click Next. The New Group Mapping page appears.
6. 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.

Use the confluent iam group-mapping create command (Confluent CLI reference) 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.

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

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:

# 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 in the Terraform registry.

Update a group mapping¶

Go to the Single sign-on tab on the Accounts & access page at https://confluent.cloud/settings/org/sso.
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.
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.
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.

Use the confluent iam group-mapping update command (Confluent CLI reference) to update a group mapping.

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

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

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 in the Terraform registry.

Describe a group mapping¶

Go to the Single sign-on tab on the Accounts & access page at https://confluent.cloud/settings/org/sso.
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.

Use the confluent iam group-mapping describe command (Confluent CLI reference) to describe a group mapping. For example, the following command describes the my-group-mapping group mapping with the ID group-123456:

confluent iam group-mapping describe group-123456

Use the confluent_group_mapping data source to describe a group mapping.

For the full confluent_group_mapping data source reference, see the Confluent Terraform Provider documentation in the Terraform registry.

List group mappings¶

Go to the Single sign-on tab on the Accounts & access page at https://confluent.cloud/settings/org/sso.

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.

Use the confluent iam group-mapping list command (Confluent CLI reference) to list group mappings.

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

confluent iam group-mapping list \
  --output json

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.

Go to the Single sign-on tab on the Accounts & access page at https://confluent.cloud/settings/org/sso.
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.
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.

Use the confluent iam group-mapping delate command (Confluent CLI reference) to delete a group mapping. For example, the following command deletes the my-group-mapping group mapping with the ID group-123456:

confluent iam group-mapping delete group-123456

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 in the Terraform registry.

Add role-binding to a group mapping¶

You can add role bindings to a group mapping to grant access to resources. Here’s an example showing how to add role bindings to a group mapping using the Confluent CLI:

confluent iam rbac role-binding create \
  --principal User:group-DApG \
  --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.

You can use the 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 in the Terraform registry.