# Configure GBAC in the Data Plane

> For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [cloud-data-platform-full.txt](https://docs.redpanda.com/cloud-data-platform-full.txt)

---
title: Configure GBAC in the Data Plane
latest-operator-version: v26.1.4
latest-console-tag: v3.7.3
latest-connect-version: 4.93.0
latest-redpanda-tag: v26.1.9
docname: authorization/gbac/gbac_dp
page-component-name: cloud-data-platform
page-version: master
page-component-version: master
page-component-title: Cloud
page-relative-src-path: authorization/gbac/gbac_dp.adoc
page-edit-url: https://github.com/redpanda-data/cloud-docs/edit/main/modules/security/pages/authorization/gbac/gbac_dp.adoc
description: Configure GBAC to manage access for provisioned users to cluster-level resources, like topics and consumer groups, using OIDC groups from your identity provider.
page-topic-type: how-to
learning-objective-1: Configure the cluster properties that enable GBAC
learning-objective-2: Assign an OIDC group to an RBAC role
learning-objective-3: "Create a group-based ACL using the Group: principal prefix"
page-git-created-date: "2026-04-07"
page-git-modified-date: "2026-05-26"
---

<!-- Source: https://docs.redpanda.com/cloud-data-platform/security/authorization/gbac/gbac_dp.md -->

> 📝 **NOTE**
>
> This feature is available for BYOC and Dedicated clusters.

Group-based access control (GBAC) in the [data plane](https://docs.redpanda.com/cloud-data-platform/reference/glossary/#data-plane) lets you manage Redpanda permissions at scale using the groups that already exist in your identity provider (IdP). Instead of creating and maintaining per-user permissions in Redpanda, you define access once for a group and your IdP controls who belongs to it. When users join or leave a team, their Redpanda access updates automatically at next login with no changes needed in Redpanda.

GBAC extends [OIDC authentication](https://docs.redpanda.com/cloud-data-platform/security/cloud-authentication/#single-sign-on) and supports two ways to grant permissions to groups: create [ACLs](https://docs.redpanda.com/cloud-data-platform/security/authorization/acl/) with `Group:<name>` principals, or assign groups as members of [RBAC](https://docs.redpanda.com/cloud-data-platform/security/authorization/rbac/) roles. Both approaches can be used independently or together.

After reading this page, you will be able to:

-   Configure the cluster properties that enable GBAC

-   Assign an OIDC group to an RBAC role

-   Create a group-based ACL using the Group: principal prefix


## [](#prerequisites)Prerequisites

To use GBAC, you need:

-   [OIDC authentication](https://docs.redpanda.com/cloud-data-platform/security/cloud-authentication/#single-sign-on) configured and enabled on your cluster.

-   Your IdP configured to include group claims in the OIDC access token (for example, a `groups` claim).


## [](#how-gbac-works)How GBAC works

When a user authenticates with OIDC, Redpanda reads a configurable claim from the JWT access token (for example, `$.groups`) and extracts the list of groups the user belongs to. Redpanda then matches those group names against `Group:<name>` principals in its ACLs and role assignments.

Group membership is managed entirely by your IdP. Redpanda never stores or manages group membership directly. It reads group information from the OIDC token at authentication time. Changes you make in the IdP (adding or removing group memberships) take effect at the user’s next authentication, when a new token is issued.

GBAC works across the following Redpanda APIs:

-   Kafka API

-   Schema Registry

-   HTTP Proxy


### [](#authorization-patterns)Authorization patterns

GBAC supports two usage patterns:

-   Group as an ACL principal: Create an ACL with a `Group:<name>` principal. Users in that group receive that permission directly.

-   Group assigned to a role: Assign a group as a member of a role-based access control (RBAC) role. All users in the group inherit the role’s ACLs.


Both patterns can be used together. When a user belongs to multiple groups, they inherit the combined permissions of all groups.

Redpanda evaluates all authorization sources (user ACLs, role ACLs, group ACLs, and group-to-role ACLs) in a single unified flow. Deny rules are checked first across all sources. If any source produces a deny, Redpanda rejects the request regardless of allows from other sources. If no deny is found, Redpanda checks for an allow across all sources. If no allow is found, Redpanda denies the request by default.

flowchart LR A\[Request\] --> B{"Check all sources\\nfor deny"} B -- "Deny found" --> DENY\["❌ Deny"\] B -- "No deny found" --> C{"Check all sources\\nfor allow"} C -- "Allow found" --> ALLOW\["✅ Allow"\] C -- "No allow found" --> DEFAULT\["❌ Default deny"\] style DENY fill:#f44,color:#fff style ALLOW fill:#4a4,color:#fff style DEFAULT fill:#f44,color:#fff subgraph sources \[" "\] direction LR S1\["User ACLs"\] S2\["Role ACLs\\n(RBAC)"\] S3\["Group ACLs"\] S4\["Group→Role\\nACLs"\] end

Figure 1. Authorization evaluation flow

## [](#supported-identity-providers)Supported identity providers

GBAC works with any OIDC-compliant identity provider. These providers are commonly used with Redpanda:

-   [Auth0](https://auth0.com/docs/secure/tokens/json-web-tokens/create-custom-claims): Configure group claims in Auth0 Actions or Rules.

-   [Okta](https://developer.okta.com/docs/concepts/universal-directory/): Assign groups to applications and include them in token claims.

-   [Microsoft Entra ID (Azure AD)](https://learn.microsoft.com/en-us/entra/identity/hybrid/connect/how-to-connect-fed-group-claims): Configure group claims in the application manifest.


For IdP-specific configuration steps, see your provider’s documentation.

## [](#limitations)Limitations

-   Azure AD group limit: Users with more than 200 group memberships in Azure AD receive a URL reference in their token instead of a list of group names. Redpanda does not follow that URL and cannot resolve groups in this case.

    Mitigation: Filter token claims to include only the groups relevant to Redpanda.

-   Nested groups: Redpanda does not recursively resolve nested group hierarchies. If group A contains group B, only the direct memberships reported in the token are used. Use [`nested_group_behavior: suffix`](https://docs.redpanda.com/cloud-data-platform/reference/properties/cluster-properties/#nested_group_behavior) to extract the last path segment from hierarchical group names when needed.

-   No wildcard ACLs for groups: ACL matching for `Group:` principals uses literal string comparison only. Wildcard patterns are not supported.


## [](#configure-token-claim-extraction)Configure token claim extraction

Different identity providers store group information in different locations within the JWT 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](https://goessner.net/articles/JsonPath/) 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**.


## [](#create-group-based-acls)Create group-based ACLs

You can grant permissions directly to a group by creating an [ACL](https://docs.redpanda.com/cloud-data-platform/security/authorization/acl/) with a `Group:<name>` principal. This works the same as creating an ACL for a user, but uses the `Group:` prefix instead of `User:`.

### rpk

To grant cluster-level access to the `engineering` group:

```bash
rpk security acl create --allow-principal Group:engineering --operation describe --cluster
```

To grant topic-level access:

```bash
rpk security acl create \
  --allow-principal Group:engineering \
  --operation read,describe \
  --topic 'analytics-' \
  --resource-pattern-type prefixed
```

### Redpanda Cloud

In Redpanda Cloud, group-based ACLs are managed through roles. To create an ACL for an OIDC group:

1.  From **Security** on the left navigation menu, select the **Roles** tab.

2.  Click **Create role** to open the role creation form, or select an existing role and click **Edit**.

3.  For **User/principal**, enter the group principal using the `Group:<name>` format. For example, `Group:engineering`.

4.  Define the permissions (ACLs) you want to grant to users in the group. You can configure ACLs for clusters, topics, consumer groups, transactional IDs, Schema Registry subjects, and Schema Registry operations.

5.  Click **Create** (or **Update** if editing an existing role).


> 📝 **NOTE**
>
> Redpanda Cloud assigns ACLs through roles. To grant permissions to a group, create a role for that group, add the group as a principal, and define the ACLs on the role. To create ACLs with a `Group:` principal directly (without creating a role), use `rpk`.

### Data Plane API

1.  First, retrieve your cluster’s Data Plane API URL:

    ```bash
    export DATAPLANE_API_URL=$(curl -s https://api.redpanda.com/v1/clusters/<cluster-id> \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer <token>" | jq -r .cluster.dataplane_api)
    ```

2.  Make a [`POST /v1/acls`](https://docs.redpanda.com/api/doc/cloud-dataplane/operation/operation-aclservice_createacl) request with a `Group:` principal. For example, to grant the `engineering` group read access to a topic:

    ```bash
    curl -X POST "${DATAPLANE_API_URL}/v1/acls" \
      -H "Authorization: Bearer <token>" \
      -H "Content-Type: application/json" \
      -d '{
        "resource_type": "RESOURCE_TYPE_TOPIC",
        "resource_name": "analytics-events",
        "resource_pattern_type": "RESOURCE_PATTERN_TYPE_LITERAL",
        "principal": "Group:engineering",
        "host": "*",
        "operation": "OPERATION_READ",
        "permission_type": "PERMISSION_TYPE_ALLOW"
      }'
    ```

## [](#assign-groups-to-roles)Assign groups to roles

To manage permissions at scale, assign a group to an [RBAC](https://docs.redpanda.com/cloud-data-platform/security/authorization/rbac/) role. All users in the group inherit the role’s ACLs automatically.

### rpk

To assign a group to a role:

```bash
rpk security role assign <role-name> --principal Group:<group-name>
```

For example, to assign the `engineering` group to the `DataEngineers` role:

```bash
rpk security role assign DataEngineers --principal Group:engineering
```

To remove a group from a role:

```bash
rpk security role unassign <role-name> --principal Group:<group-name>
```

For example:

```bash
rpk security role unassign DataEngineers --principal Group:engineering
```

### Redpanda Cloud

To assign a group to a role in Redpanda Cloud:

1.  From **Security** on the left navigation menu, select the **Roles** tab.

2.  Select the role you want to assign the group to.

3.  Click **Edit**.

4.  For **User/principal**, enter the group name using the `Group:<name>` format. For example, `Group:engineering`.

5.  Click **Update**.


To remove a group from a role:

1.  From **Security** on the left navigation menu, select the **Roles** tab.

2.  Select the role that has the group assignment you want to remove.

3.  Click **Edit**.

4.  For **User/principal**, remove the `Group:<name>` entry.

5.  Click **Update**.

### Data Plane API

Make a [`PUT /v1/roles/{role_name}`](https://docs.redpanda.com/api/doc/cloud-dataplane/operation/operation-securityservice_updaterolemembership) request to assign a group to a role:

```bash
curl -X PUT "${DATAPLANE_API_URL}/v1/roles/DataEngineers" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "add": [{"principal": "Group:engineering"}]
  }'
```

To remove a group from a role, use the `remove` field:

```bash
curl -X PUT "${DATAPLANE_API_URL}/v1/roles/DataEngineers" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "remove": [{"principal": "Group:engineering"}]
  }'
```

## [](#view-groups-and-roles)View groups and roles

Use the following commands to inspect group assignments and role memberships.

### [](#list-groups-assigned-to-a-role)List groups assigned to a role

#### rpk

To see which groups are assigned to a role, use `--print-members`. Groups are listed alongside other principals such as `User:<name>` and appear as `Group:<name>` entries:

```bash
rpk security role describe <role-name> --print-members
```

For example:

```bash
rpk security role describe DataEngineers --print-members
```

To list all roles assigned to a specific group:

```bash
rpk security role list --principal Group:<group-name>
```

For example:

```bash
rpk security role list --principal Group:engineering
```

#### Redpanda Cloud

To view groups assigned to a role in Redpanda Cloud:

1.  From **Security** on the left navigation menu, select the **Roles** tab.

2.  Select the role you want to inspect.

3.  The role details page lists all principals, including any `Group:<name>` entries.

#### Data Plane API

To list all members of a role (including groups), make a [`GET /v1/roles/{role_name}/members`](https://docs.redpanda.com/api/doc/cloud-dataplane/operation/operation-securityservice_listrolemembers) request:

```bash
curl -X GET "${DATAPLANE_API_URL}/v1/roles/DataEngineers/members" \
  -H "Authorization: Bearer <token>"
```

The response includes a `members` array. Group members appear with the `Group:` prefix in the `principal` field.

To list all roles assigned to a specific group, make a [`GET /v1/roles`](https://docs.redpanda.com/api/doc/cloud-dataplane/operation/operation-securityservice_listroles) request with a principal filter:

```bash
curl -X GET "${DATAPLANE_API_URL}/v1/roles?filter.principal=Group:engineering" \
  -H "Authorization: Bearer <token>"
```

## [](#audit-logging)Audit logging

When [audit logging](https://docs.redpanda.com/cloud-data-platform/manage/audit-logging/) is enabled, Redpanda includes group information in the following event types:

-   Authentication events: Events across Kafka API, HTTP Proxy, and Schema Registry include the user’s IdP group memberships in the `user.groups` field with type `idp_group`.

-   Authorization events: When an authorization decision matches a group ACL, the matched group appears in the `actor.user.groups` field with type `idp_group`.


## [](#next-steps)Next steps

-   [Set up audit logging](https://docs.redpanda.com/cloud-data-platform/manage/audit-logging/) to monitor group-based access events.


## [](#suggested-reading)Suggested reading

-   [Configure GBAC in the Control Plane](https://docs.redpanda.com/cloud-data-platform/security/authorization/gbac/gbac/)

-   [Configure RBAC in the Control Plane](https://docs.redpanda.com/cloud-data-platform/security/authorization/rbac/rbac/)

-   [Configure RBAC in the Data Plane](https://docs.redpanda.com/cloud-data-platform/security/authorization/rbac/rbac_dp/)

-   [Single sign-on](https://docs.redpanda.com/cloud-data-platform/security/cloud-authentication/#single-sign-on)