# Configure Group-Based Access Control

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

---
title: Configure Group-Based Access Control
latest-redpanda-tag: v26.1.9
latest-console-tag: v3.7.3
latest-operator-version: v26.1.4
# EOL = End-of-Life (support lifecycle status)
page-is-nearing-eol: "false"
page-is-past-eol: "false"
page-eol-date: March 31, 2027
latest-connect-version: 4.93.0
docname: security/authorization/gbac
page-component-name: streaming
page-version: "26.1"
page-component-version: "26.1"
page-component-title: Streaming
page-relative-src-path: security/authorization/gbac.adoc
page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/security/authorization/gbac.adoc
description: Manage Redpanda permissions at scale using your identity provider's groups. Define access once per group and let your IdP control membership, with no per-user configuration in Redpanda.
page-topic-type: how-to
personas: security_engineer, platform_engineer
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-03-31"
page-git-modified-date: "2026-03-31"
support-status: supported
---

<!-- Source: https://docs.redpanda.com/streaming/current/manage/security/authorization/gbac.md -->

> 📝 **NOTE**
>
> This feature requires an [enterprise license](https://docs.redpanda.com/streaming/current/get-started/licensing/). To get a trial license key or extend your trial period, [generate a new trial license key](https://redpanda.com/try-enterprise). To purchase a license, contact [Redpanda Sales](https://redpanda.com/upgrade).
>
> If Redpanda has enterprise features enabled and it cannot find a valid license, [restrictions](https://docs.redpanda.com/streaming/current/get-started/licensing/#self-managed) 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](https://docs.redpanda.com/streaming/current/manage/security/authentication/#oidc) and supports two ways to grant permissions to groups: create [ACLs](https://docs.redpanda.com/streaming/current/manage/security/authorization/acl/) with `Group:<name>` principals, or assign groups as members of [RBAC](https://docs.redpanda.com/streaming/current/manage/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:

-   An [Enterprise Edition](https://docs.redpanda.com/streaming/current/get-started/licensing/overview/) license applied to your cluster.

-   Superuser access to configure cluster properties and manage ACLs.

-   [OIDC authentication](https://docs.redpanda.com/streaming/current/manage/security/authentication/#oidc) 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/streaming/current/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.


## [](#customize-token-claim-extraction)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`](https://docs.redpanda.com/streaming/current/reference/properties/cluster-properties/#oidc_group_claim_path): A [JSON path](https://goessner.net/articles/JsonPath/) 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`](https://docs.redpanda.com/streaming/current/reference/properties/cluster-properties/#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`.

    > 📝 **NOTE**
    >
    > 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](https://docs.redpanda.com/streaming/current/manage/cluster-maintenance/cluster-property-configuration/) (`rpk cluster config set`, the Admin API, or Redpanda Console). Changes take effect immediately without a restart.

### [](#token-structure-examples)Token structure examples

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

#### [](#flat-group-values-default)Flat group values (default)

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

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

#### [](#nested-claim)Nested claim

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

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

#### [](#path-style-group-names-with-no-suffix-extraction-default)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`.

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

#### [](#path-style-group-names-with-suffix-extraction)Path-style group names with suffix extraction

When [`nested_group_behavior`](https://docs.redpanda.com/streaming/current/reference/properties/cluster-properties/#nested_group_behavior) is set to `suffix`, Redpanda maps the last path segment to principals `Group:platform` and `Group:infra`.

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

#### [](#csv-formatted-group-claim)CSV-formatted group claim

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

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

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

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

You can grant permissions directly to a group by creating an [ACL](https://docs.redpanda.com/streaming/current/manage/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 Console

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.  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 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)Assign groups to roles

To manage permissions at scale, assign a group to an [RBAC](https://docs.redpanda.com/streaming/current/manage/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 Console

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

### Admin API

Use the Admin API [`SecurityService`](https://docs.redpanda.com/api/doc/admin/v2/group/endpoint-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](https://docs.redpanda.com/streaming/current/manage/use-admin-api/).

To assign a group to a role, make a [`POST AddRoleMembers`](https://docs.redpanda.com/api/doc/admin/v2/operation/operation-redpanda-core-admin-v2-securityservice-addrolemembers) request:

```bash
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`](https://docs.redpanda.com/api/doc/admin/v2/operation/operation-redpanda-core-admin-v2-securityservice-removerolemembers) request:

```bash
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)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 Console

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.

#### Admin API

These operations use the [Admin API v2](https://docs.redpanda.com/api/doc/admin/v2/group/endpoint-securityservice) `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`](https://docs.redpanda.com/api/doc/admin/v2/operation/operation-redpanda-core-admin-v2-securityservice-getrole) request:

```bash
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`](https://docs.redpanda.com/api/doc/admin/v2/operation/operation-redpanda-core-admin-v2-securityservice-listroles) request:

```bash
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`](https://docs.redpanda.com/api/doc/admin/v2/operation/operation-redpanda-core-admin-v2-securityservice-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:

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

## [](#troubleshoot-gbac)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:

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

    Look for the claim that matches your [`oidc_group_claim_path`](https://docs.redpanda.com/streaming/current/reference/properties/cluster-properties/#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](#view-groups-and-roles).

-   Verify that your cluster configuration matches the token structure:

    ```bash
    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:

    ```bash
    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)Audit logging

When [audit logging](https://docs.redpanda.com/streaming/current/manage/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)Next steps

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


## Suggested labs

-   [Enable Unified Identity with Azure Entra ID for Redpanda and Redpanda Console](https://docs.redpanda.com/labs/docker-compose/oidc/)
-   [Migrate Data with Redpanda Migrator](https://docs.redpanda.com/labs/docker-compose/redpanda-migrator/)

[Search all labs](https://docs.redpanda.com/labs)