Collapse navigation tree

Collapse

Configure GBAC in the Data Plane

This feature is available for BYOC and Dedicated clusters.

Group-based access control (GBAC) in the 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 and supports two ways to grant permissions to groups: create ACLs with Group:<name> principals, or assign groups as members of 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

To use GBAC, you need:

  • OIDC authentication 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

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

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

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

  • Auth0: Configure group claims in Auth0 Actions or Rules.

  • Okta: Assign groups to applications and include them in token claims.

  • Microsoft Entra ID (Azure AD): Configure group claims in the application manifest.

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

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 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

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

Create group-based ACLs

You can grant permissions directly to a group by creating an 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

  • Redpanda Cloud

  • Data Plane API

To grant cluster-level access to the engineering group:

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

To grant topic-level access:

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

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).

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.

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

    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 request with a Group: principal. For example, to grant the engineering group read access to a topic:

    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

To manage permissions at scale, assign a group to an RBAC role. All users in the group inherit the role’s ACLs automatically.

  • rpk

  • Redpanda Cloud

  • Data Plane API

To assign a group to a role:

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

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

rpk security role assign DataEngineers --principal Group:engineering

To remove a group from a role:

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

For example:

rpk security role unassign DataEngineers --principal Group:engineering

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.

Make a PUT /v1/roles/{role_name} request to assign a group to a role:

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:

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

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

List groups assigned to a role

  • rpk

  • Redpanda Cloud

  • Data Plane API

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:

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

For example:

rpk security role describe DataEngineers --print-members

To list all roles assigned to a specific group:

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

For example:

rpk security role list --principal Group:engineering

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.

To list all members of a role (including groups), make a GET /v1/roles/{role_name}/members request:

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 request with a principal filter:

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

Audit logging

When 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

Suggested reading