This documentation was originally written for Redpanda as part of the Group-Based Access Control (GBAC) feature. It is reproduced here as a portfolio writing sample. Authored from scratch — no prior documentation existed for this feature.
Group-Based Access Control (GBAC)
Group-based access control (GBAC) extends OIDC authentication to let you manage permissions at the group level instead of per user. You can grant permissions to groups in two ways: create ACLs with Group:<name> principals, or assign groups as members of RBAC roles. Both approaches can be used independently or together. Because group membership is managed by your identity provider (IdP), onboarding and offboarding require no changes in Redpanda.
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
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.
GBAC works across all Redpanda APIs:
- Kafka API
- Admin API
- Schema Registry
- HTTP Proxy
Authorization patterns
GBAC supports two usage patterns:
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.
Group as an ACL principal: Create an ACL with a Group:<name> principal. Users in that group receive that permission directly.
Both patterns can be used together. When a user belongs to multiple groups, they inherit the combined permissions of all groups.
Authorization evaluation
Redpanda evaluates all authorization sources (user ACLs, role ACLs, group ACLs, and group-to-role ACLs) in a single unified flow:
- Check all sources for deny: If any source produces a deny, the request is rejected regardless of allows from other sources.
- Check all sources for allow: If no deny is found, Redpanda checks for an allow across all sources.
- Default deny: If no allow is found, the request is denied.
Authorization sources evaluated:
- User ACLs
- Role ACLs (RBAC)
- Group ACLs
- Group→Role ACLs
Prerequisites
- OIDC authentication must be configured and enabled on your cluster.
- Superuser access to configure cluster properties and manage ACLs.
- Enterprise Edition license on your cluster.
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, refer to 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.
Deny ACL precedence: Redpanda checks deny rules before allow rules across all authorization sources. A deny from any source rejects the request, even if another source would grant allow. This is consistent with standard Redpanda ACL conflict resolution.
Group membership timing: Group membership reflects the claims in the OIDC token at authentication time. Changes made in the IdP (adding or removing group memberships) take effect at the user's next authentication, when a new token is issued.
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.
With 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
Flat group values (default)
{"groups": ["engineering", "analytics"]}
With oidc_group_claim_path: "$.groups", Redpanda resolves principals Group:engineering and Group:analytics.
Nested claim
{"realm_access": {"roles": ["eng", "fin"]}}
With oidc_group_claim_path: "$.realm_access.roles", Redpanda resolves principals Group:eng and Group:fin.
Path-style group names with suffix extraction
{"groups": ["/departments/eng/platform", "/departments/eng/infra"]}
With nested_group_behavior: "suffix", Redpanda resolves principals Group:platform and Group:infra.
CSV-formatted group claim
{"groups": "engineering,analytics,finance"}
Redpanda automatically splits comma-separated values and resolves principals Group:engineering, Group:analytics, and Group:finance.