Collapse navigation tree

Collapse

Configure Group-Based Access Control

This feature requires an enterprise license. To get a trial license key or extend your trial period, generate a new trial license key. To purchase a license, contact Redpanda Sales.

If Redpanda has enterprise features enabled and it cannot find a valid license, restrictions apply.

Group-based access control (GBAC) 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:

  • An Enterprise Edition license applied to your cluster.

  • Superuser access to configure cluster properties and manage ACLs.

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

Authorization evaluation flow
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

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.

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 Console

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 Console, 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. In the Principals field, 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 Console 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.

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 Console

  • Admin 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 Console:

  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. In the Principals section, 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. In the Principals section, remove the Group:<name> entry.

  5. Click Update.

Use the Admin API SecurityService operations to manage group-to-role assignments. Send all requests as POST with a JSON body. For guidance on using the Admin API (ConnectRPC), see Manage Redpanda using the Admin API.

To assign a group to a role, make a POST AddRoleMembers request:

curl -u <user>:<password> \
  --request POST 'http://localhost:9644/redpanda.core.admin.v2.SecurityService/AddRoleMembers' \
  --header 'Content-Type: application/json' \
  --data '{
    "roleName": "DataEngineers",
    "members": [{"group": {"name": "engineering"}}]
  }'

To remove a group from a role, make a POST RemoveRoleMembers request:

curl -u <user>:<password> \
  --request POST 'http://localhost:9644/redpanda.core.admin.v2.SecurityService/RemoveRoleMembers' \
  --header 'Content-Type: application/json' \
  --data '{
    "roleName": "DataEngineers",
    "members": [{"group": {"name": "engineering"}}]
  }'

View groups and roles

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

List groups assigned to a role

  • rpk

  • Redpanda Console

  • Admin 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 Console:

  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.

These operations use the Admin API v2 SecurityService. Send all requests as POST with a JSON body.

To retrieve a role’s details including all members (users and groups), make a POST GetRole request:

curl -u <user>:<password> \
  --request POST 'http://localhost:9644/redpanda.core.admin.v2.SecurityService/GetRole' \
  --header 'Content-Type: application/json' \
  --data '{"name": "DataEngineers"}'

The response includes a members array with both user and group entries.

To list all roles, make a POST ListRoles request:

curl -u <user>:<password> \
  --request POST 'http://localhost:9644/redpanda.core.admin.v2.SecurityService/ListRoles' \
  --header 'Content-Type: application/json' \
  --data '{}'

To verify how Redpanda resolves groups from an OIDC token, make a POST ResolveOidcIdentity request. Pass the token in the Authorization header. The response includes the resolved principal, token expiry, and a groups field listing all groups extracted from the token:

curl \
  --request POST 'http://localhost:9644/redpanda.core.admin.v2.SecurityService/ResolveOidcIdentity' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <jwt-access-token>' \
  --data '{}'

Customize token claim extraction

Different identity providers store group information in different locations within the JWT token.

Two cluster properties control how Redpanda extracts group names:

  • oidc_group_claim_path: A JSON path expression that tells Redpanda where to find group information in the OIDC token. For example, Auth0 and Okta typically use a top-level groups claim ($.groups), while Keycloak nests roles inside realm_access ($.realm_access.roles). Default: $.groups.

  • nested_group_behavior: Controls how Redpanda handles group names that use path-style notation (for example, /departments/eng/platform). Set to none to use the full path as-is, or suffix to extract only the last segment. Default: none.

    When nested_group_behavior is set to suffix, groups that share a leaf name (for example, /departments/eng/groupA and /departments/sales/groupA) both resolve to Group:groupA. ACLs or role assignments for that principal apply to members of both groups. Design your group naming conventions to avoid unintended collisions.

To update these properties, use any configuration method (rpk cluster config set, the Admin API, or Redpanda Console). Changes take effect immediately without a restart.

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"]}

Path-style group names with suffix extraction

When nested_group_behavior is set to suffix, Redpanda maps the last path segment to principals Group:platform and Group: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.

Troubleshoot GBAC

If group-based permissions are not working as expected:

  • Decode the JWT access token from your IdP and verify that the expected group claims are present:

    echo $ACCESS_TOKEN | cut -d. -f2 | base64 -d 2>/dev/null | jq .

    Look for the claim that matches your oidc_group_claim_path configuration (default: $.groups).

  • Use the ResolveOidcIdentity Admin API endpoint to verify which groups Redpanda extracts from a token. See View groups and roles.

  • Verify that your cluster configuration matches the token structure:

    rpk cluster config get oidc_group_claim_path
rpk cluster config get nested_group_behavior

  • Temporarily enable debug logging for the security logger to see all claims in the validated JWT:

    rpk redpanda admin config log-level set security --level debug

    This helps diagnose incorrect claim paths, missing groups, or token content issues. The debug level reverts automatically after the expiry period (default: 300 seconds).

Audit logging

When audit logging is enabled, Redpanda includes group information in the following event types:

  • Authentication events: Events across Kafka API, HTTP Proxy, Schema Registry, and Admin API 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 labs

Search all labs