Collapse navigation tree

Collapse

Configure GBAC in the Control Plane

This feature is available for BYOC and Dedicated clusters.

Use Redpanda Cloud group-based access control (GBAC) in the control plane to manage access to organization resources based on OIDC groups from your identity provider (IdP). For example, you can grant one group access to development clusters while restricting production access to another group. You can also restrict access to geographically dispersed clusters to support data residency requirements. When a user’s group membership changes in the IdP, their Redpanda access updates automatically.

After reading this page, you will be able to:

  • Register an OIDC group in Redpanda Cloud

  • Assign a predefined or custom role to a group

  • Manage group-based access at the organization level

GBAC terminology

Group: A group is a collection of users defined in your IdP. With GBAC, you can assign groups to roles or ACLs in Redpanda Cloud, so that users inherit permissions based on their group membership in your IdP.

Role: A role is a list of permissions. Permissions are attached to roles. Users assigned multiple roles receive the union of all permissions defined in those roles. Redpanda Cloud has several predefined roles that you cannot modify or delete, including Reader, Writer, and Admin. You can also create custom roles.

Role binding: Role binding assigns a role to an account. Administrators can add, edit, or remove role bindings for a user. When you change the permissions for a given role, all users and service accounts with that role automatically get the modified permissions.

Manage organization access

In the Redpanda Cloud Console, the Organization IAM page lets you create groups. When you create a group, you define its permissions with role binding. When you edit a group, you can change its role bindings to update the group’s permissions. When you change the permissions for a given role, all groups with that role automatically get the modified permissions.

Various resources can be assigned as the scope of a role, including the following:

  • Organization

  • Resource group

  • Network

  • Network peering

  • Cluster (Serverless clusters have a different set of permissions from BYOC and Dedicated clusters.)

  • MCP server

You can manage GBAC configurations with the Redpanda Cloud Console or with the Control Plane API.

Configure group claim extraction

Different identity providers structure group information differently in their OIDC tokens. Before you register groups, configure your SSO connection to tell Redpanda Cloud where to find group claims in the token.

In Redpanda Cloud, group claim extraction is configured through your SSO connection settings.

  1. In the Cloud UI, navigate to Organization IAM > Single sign-on, then select your IdP connection.

  2. For Mapping mode, select use_map.

  3. Configure Attributes (JSON) to map attribute names to claim paths, including federated_groups for group claims.

    A claim path is a JSON path expression that tells Redpanda where to find group information in the OIDC token. The appropriate claim path for each attribute may vary per IdP.

    For example, Okta exposes group claims in ${context.userinfo.groups}. In this case, you must also include groups in Userinfo scope.

Token structure examples

The following examples show how Redpanda extracts group principals from different token formats.

Flat group values (default)

With oidc_group_claim_path: "$.groups", Redpanda extracts principals Group:engineering and Group:analytics from the token.

{"groups": ["engineering", "analytics"]}

Nested claim

With oidc_group_claim_path: "$.realm_access.roles", Redpanda extracts principals Group:eng and Group:fin from the token.

{"realm_access": {"roles": ["eng", "fin"]}}

Path-style group names with no suffix extraction (default)

With nested_group_behavior: "none" (the default), Redpanda maps the full path to principals Group:/departments/eng/platform and Group:/departments/eng/infra.

{"groups": ["/departments/eng/platform", "/departments/eng/infra"]}

CSV-formatted group claim

Some identity providers return group claims as a single comma-separated string instead of an array.

{"groups": "engineering,analytics,finance"}

Redpanda automatically splits comma-separated values and extracts principals Group:engineering, Group:analytics, and Group:finance.

Register groups

To assign an IdP group to a role or ACL, you must first register the group in Redpanda Cloud:

  • Cloud UI

  • Control Plane API

  1. Navigate to Organization IAM > Groups.

  2. Click Create group.

  3. Enter a Name that matches the group in your IdP exactly (for example, engineering).

  4. Optionally, enter a Description, and configure a Role binding to assign the group to a role with a specific scope and resource.

  5. Click Create.

Make a POST /v1/groups request to the Control Plane API:

curl -X POST 'https://api.redpanda.com/v1/groups' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <token>' \
  -d '{
    "group": {
      "name": "<group-name>",
      "description": "<group-description>"
    }
  }'

Replace <group-name> with the name that matches the group in your IdP (for example, engineering). The name must match exactly for GBAC to map the group correctly.

Predefined roles

Redpanda Cloud provides several predefined roles that you cannot modify or delete, including Reader, Writer, and Admin.

You can see all predefined roles along with their permissions on the Roles tab of Organization IAM.

Custom roles

In addition to the predefined roles, administrators can create custom roles to mix and match permissions for specific use cases. Custom roles let you grant only the permissions a group needs, without the broad access of predefined roles.

Custom roles are created on the Roles tab in Organization IAM. For steps to create a custom role, see Custom roles in RBAC.

When you register a group or edit a group’s role binding, you can assign any predefined or custom role to the group.

Suggested reading