Skip to content

Commit 0a5e0e8

Browse files
paulohtb6kbatuigasmicheleRP
authored
GBAC (#1584)
Co-authored-by: Kat Batuigas <kbatuigas@gmail.com> Co-authored-by: Kat Batuigas <36839689+kbatuigas@users.noreply.github.com> Co-authored-by: Michele Cyran <michele@redpanda.com>
1 parent fa0375c commit 0a5e0e8

15 files changed

Lines changed: 909 additions & 10 deletions

File tree

‎modules/ROOT/nav.adoc‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -173,6 +173,7 @@
173173
*** xref:manage:security/authentication.adoc[Authentication]
174174
*** xref:manage:security/authorization/index.adoc[Authorization]
175175
**** xref:manage:security/authorization/rbac.adoc[Role-Based Access Control (RBAC)]
176+
**** xref:manage:security/authorization/gbac.adoc[Group-Based Access Control (GBAC)]
176177
**** xref:manage:security/authorization/acl.adoc[Access Control Lists (ACLs)]
177178
*** xref:manage:security/fips-compliance.adoc[FIPS Compliance]
178179
*** xref:manage:security/encryption.adoc[]

‎modules/get-started/pages/release-notes/redpanda.adoc‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,17 @@ This topic includes new content added in version {page-component-version}. For a
77
* xref:redpanda-cloud:get-started:whats-new-cloud.adoc[]
88
* xref:redpanda-cloud:get-started:cloud-overview.adoc#redpanda-cloud-vs-self-managed-feature-compatibility[Redpanda Cloud vs Self-Managed feature compatibility]
99
10+
== Group-based access control (GBAC)
11+
12+
Redpanda {page-component-version} introduces xref:manage:security/authorization/gbac.adoc[group-based access control (GBAC)], which extends OIDC authentication to support group-based permissions. In addition to assigning roles or ACLs to individual users, you can assign them to OIDC groups. Users inherit permissions from all groups reported by their identity provider (IdP) in the OIDC token claims.
13+
14+
GBAC supports two authorization patterns:
15+
16+
* Assign a group as a member of an RBAC role so that all users in the group inherit the role's ACLs.
17+
* Create ACLs directly with a `Group:<name>` principal.
18+
19+
Group membership is managed entirely by your IdP. Redpanda reads group information from the OIDC token at authentication time and works across the Kafka API, Schema Registry, and HTTP Proxy.
20+
1021
== FIPS 140-3 validation and FIPS Docker image
1122

1223
Redpanda's cryptographic module has been upgraded from FIPS 140-2 to https://csrc.nist.gov/pubs/fips/140-3/final[FIPS 140-3^] validation. Additionally, Redpanda now provides a FIPS-specific Docker image (`docker.redpanda.com/redpandadata/redpanda:<version>-fips`) for `amd64` and `arm64` architectures, with the required OpenSSL FIPS module pre-configured.
@@ -34,3 +45,10 @@ xref:develop:produce-data/leader-pinning.adoc[Leader Pinning] now supports the `
3445
Redpanda now supports throughput quotas based on authenticated user principals. Unlike client-based quotas (which rely on self-declared `client-id` values), user-based quotas enforce limits using verified identities from SASL, mTLS, or OIDC authentication.
3546

3647
You can set quotas for individual users, default users, or fine-grained user/client combinations. See xref:manage:cluster-maintenance/about-throughput-quotas.adoc[] for conceptual details, and xref:manage:cluster-maintenance/manage-throughput.adoc#set-user-based-quotas[Set user-based quotas] to get started.
48+
49+
== New configuration properties
50+
51+
**Authentication:**
52+
53+
* xref:reference:properties/cluster-properties.adoc#nested_group_behavior[`nested_group_behavior`]: Control how Redpanda handles nested groups extracted from authentication tokens
54+
* xref:reference:properties/cluster-properties.adoc#oidc_group_claim_path[`oidc_group_claim_path`]: JSON path to extract groups from the JWT payload

‎modules/manage/pages/audit-logging/audit-log-samples.adoc‎

Lines changed: 143 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,9 @@
33
:page-categories: Management, Security
44
// tag::single-source[]
55

6+
ifdef::env-cloud[:gbac-doc: security:authorization/gbac.adoc]
7+
ifndef::env-cloud[:gbac-doc: manage:security/authorization/gbac.adoc]
8+
69
ifndef::env-cloud[]
710
[NOTE]
811
====
@@ -80,6 +83,59 @@ This scenario shows the message resulting from an admin using rpk with successfu
8083
----
8184
====
8285

86+
.Authentication successful (OIDC with group claims)
87+
[%collapsible]
88+
====
89+
This scenario shows a successful OIDC authentication event that includes the user's IdP group memberships in the `user.groups` field. Group memberships are extracted from the OIDC token and included in all authentication events for OIDC users.
90+
[,json]
91+
----
92+
{
93+
"category_uid": 3,
94+
"class_uid": 3002,
95+
"metadata": {
96+
"product": {
97+
"name": "Redpanda",
98+
"uid": "0",
99+
"vendor_name": "Redpanda Data, Inc.",
100+
"version": "v26.1.1"
101+
},
102+
"version": "1.0.0"
103+
},
104+
"severity_id": 1,
105+
"time": 1700533469078,
106+
"type_uid": 300201,
107+
"activity_id": 1,
108+
"auth_protocol": "SASL-OAUTHBEARER",
109+
"auth_protocol_id": 99,
110+
"dst_endpoint": {
111+
"ip": "127.0.0.1",
112+
"port": 9092,
113+
"svc_name": "kafka rpc protocol"
114+
},
115+
"is_cleartext": false,
116+
"is_mfa": false,
117+
"service": {
118+
"name": "kafka rpc protocol"
119+
},
120+
"src_endpoint": {
121+
"ip": "10.0.1.50",
122+
"name": "kafka-client",
123+
"port": 48210
124+
},
125+
"status_id": 1,
126+
// IdP group memberships extracted from the OIDC token
127+
"user": {
128+
"name": "alice@example.com",
129+
"type_id": 1,
130+
"groups": [
131+
{"type": "idp_group", "name": "engineering"},
132+
{"type": "idp_group", "name": "analytics"}
133+
]
134+
}
135+
}
136+
----
137+
====
138+
83139
.Authentication failed
84140
[%collapsible]
85141
====
@@ -237,6 +293,93 @@ This example illustrates an ACL update that also requires a superuser authentica
237293
----
238294
====
239295

296+
.Authorization matched on a group ACL
297+
[%collapsible]
298+
====
299+
This example shows an API Activity (6003) where the authorization decision matched an ALLOW ACL on a `Group:` principal. The `actor.user.groups` field includes the matched group with type `idp_group`, and the `authorization_metadata` shows the group ACL that granted access. See xref:{gbac-doc}[Group-Based Access Control].
300+
301+
[,json]
302+
----
303+
{
304+
"category_uid": 6,
305+
"class_uid": 6003,
306+
"metadata": {
307+
"product": {
308+
"name": "Redpanda",
309+
"uid": "0",
310+
"vendor_name": "Redpanda Data, Inc.",
311+
"version": "v26.1.0"
312+
},
313+
"version": "1.0.0"
314+
},
315+
"severity_id": 1,
316+
"time": 1774544504327,
317+
"type_uid": 600303,
318+
"activity_id": 3,
319+
"actor": {
320+
"authorizations": [
321+
{
322+
"decision": "authorized",
323+
"policy": {
324+
"desc": "acl: {principal type {group} name {/sales} host {{any_host}} op all perm allow}, resource: type {topic} name {sales-topic} pattern {literal}",
325+
"name": "aclAuthorization"
326+
}
327+
}
328+
],
329+
// The matched group appears in the user's groups field
330+
"user": {
331+
"name": "alice",
332+
"type_id": 1,
333+
"groups": [
334+
{
335+
"type": "idp_group",
336+
"name": "/sales"
337+
}
338+
]
339+
}
340+
},
341+
"api": {
342+
"operation": "produce",
343+
"service": {
344+
"name": "kafka rpc protocol"
345+
}
346+
},
347+
"dst_endpoint": {
348+
"ip": "127.0.1.1",
349+
"port": 9092,
350+
"svc_name": "kafka rpc protocol"
351+
},
352+
"resources": [
353+
{
354+
"name": "sales-topic",
355+
"type": "topic"
356+
}
357+
],
358+
"src_endpoint": {
359+
"ip": "127.0.0.1",
360+
"name": "rdkafka",
361+
"port": 42728
362+
},
363+
"status_id": 1,
364+
"unmapped": {
365+
"authorization_metadata": {
366+
"acl_authorization": {
367+
"host": "{{any_host}}",
368+
"op": "all",
369+
"permission_type": "allow",
370+
"principal": "type {group} name {/sales}"
371+
},
372+
"resource": {
373+
"name": "sales-topic",
374+
"pattern": "literal",
375+
"type": "topic"
376+
}
377+
}
378+
}
379+
}
380+
----
381+
====
382+
240383
.Metadata request (with counts)
241384
[%collapsible]
242385
====

‎modules/manage/pages/security/authorization/acl.adoc‎

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -62,8 +62,8 @@ Understanding these terms helps you configure least-privilege access.
6262
| Term | Definition | Example
6363

6464
| Principal
65-
| The entity (user or role) requesting access
66-
| `User:analytics-user`, `RedpandaRole:data-engineers`
65+
| The entity (user, role, or group) requesting access
66+
| `User:analytics-user`, `RedpandaRole:data-engineers`, `Group:engineering`
6767

6868
| Resource
6969
| The Redpanda component being accessed (cluster, topic, consumer group, transactional ID, Schema Registry glossterm:subject[], and Schema Registry operation)
@@ -91,7 +91,13 @@ ACL commands work on a multiplicative basis. If you specify two principals and t
9191
[[principals]]
9292
=== Principals
9393

94-
All ACLs require a principal. A principal is composed of two parts: the type, and the name. Redpanda supports the types "User" and "RedpandaRole". When you create user "bar", Redpanda expects you to add ACLs for "User:bar".
94+
All ACLs require a principal. A principal is composed of two parts: the type, and the name. Redpanda supports the types "User", "RedpandaRole", and "Group". When you create user "bar", Redpanda expects you to add ACLs for "User:bar". To grant permissions to an OIDC group, use the `Group:` prefix (for example, `Group:engineering`).
95+
ifndef::env-cloud[]
96+
See xref:manage:security/authorization/gbac.adoc[].
97+
endif::[]
98+
ifdef::env-cloud[]
99+
See xref:security:authorization/gbac.adoc[].
100+
endif::[]
95101

96102
The `--allow-principal` and `--deny-principal` flags add this prefix for you, if necessary.
97103

‎modules/manage/pages/security/authorization/gbac.adoc‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
= Configure Group-Based Access Control
2+
: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.
3+
:page-topic-type: how-to
4+
:page-categories: Management, Security
5+
:personas: security_engineer, platform_engineer
6+
:learning-objective-1: Configure the cluster properties that enable GBAC
7+
:learning-objective-2: Assign an OIDC group to an RBAC role
8+
:learning-objective-3: Create a group-based ACL using the Group: principal prefix
9+
10+
ifndef::env-cloud[]
11+
[NOTE]
12+
====
13+
include::shared:partial$enterprise-license.adoc[]
14+
====
15+
endif::[]
16+
17+
include::manage:partial$gbac-dp.adoc[]

‎modules/manage/pages/security/authorization/index.adoc‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
= Configure Authorization
2-
:description: Redpanda provides two mechanisms for controlling user permissions.
2+
:description: Redpanda provides mechanisms for controlling user permissions, including ACLs, role-based access control, and group-based access control.
33
:page-aliases: security:authorization/index.adoc, manage:security/authorization.adoc
44
:page-categories: Management, Security
55
:page-layout: index
66

77

8-
Authorization works in tandem with xref:security/authentication.adoc[authentication]. Authentication grants permission to interact with Redpanda resources while authorization controls what a principal is permitted to do once authenticated.
8+
Authorization works in tandem with xref:security/authentication.adoc[authentication]. Authentication verifies who a principal is. Authorization controls what that principal can do once authenticated.

‎modules/manage/partials/audit-logging.adoc‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -159,10 +159,11 @@ NOTE: The Included column captures whether the event itself is included (for exa
159159
|===
160160
|Data Logging Level |Audit Event |Included? |Details
161161

162-
.11+|System Level
162+
.12+|System Level
163163
|Date and time stamp for each entry |Yes |`time` field on each event
164164
|Successful and failed access attempts |Yes |The `status_id` field shows success/failure for all access attempts for which auditing is enabled
165165
|User ID |Yes |`user.name`
166+
|User group memberships |Yes |`user.groups` field with type `idp_group`. Included in authentication events for OIDC users and in authorization events when a group ACL matches. See xref:manage:security/authorization/gbac.adoc[].
166167
|User connect and disconnect time |No |Connect and disconnect time may be inferred from the presence or absence of activity.
167168
|Password change |Yes |For SCRAM users managed through Redpanda core, the Admin API call associated with the password change is logged. Note that this does not cover users synced from external IdPs, such as through OIDC.
168169
|Changes of security settings |Yes |For example, ACL creation is logged (kafka `create_acls`), and cluster configuration changes are logged (Admin API events)

‎modules/manage/partials/authentication.adoc‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -867,6 +867,8 @@ but can instead rely on the trusted authentication capabilities of established I
867867
Redpanda's implementation of OIDC provides SASL/OAUTHBEARER support for the Kafka API, and supports
868868
standard OIDC authentication across all other HTTP APIs, including Schema Registry, HTTP Proxy, and the Admin API.
869869

870+
TIP: With OIDC enabled, you can also use xref:manage:security/authorization/gbac.adoc[group-based access control (GBAC)] to assign Redpanda permissions to OIDC groups instead of individual users. To use GBAC, configure your IdP to include group claims in the access token (for example, a `groups` claim). See your IdP's documentation for how to add group claims to tokens.
871+
870872
include::manage:partial$security/oidc/limitations.adoc[leveloffset=+3]
871873

872874
===== OIDC credentials flow and access token validation

‎modules/manage/partials/gbac-assign-group-role.adoc‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
To assign a group to a role in {ui}:
2+
3+
. From *Security* on the left navigation menu, select the *Roles* tab.
4+
5+
. Select the role you want to assign the group to.
6+
7+
. Click *Edit*.
8+
9+
. In the *Principals* section, enter the group name using the `Group:<name>` format. For example, `Group:engineering`.
10+
11+
. Click *Update*.
12+
13+
To remove a group from a role:
14+
15+
. From *Security* on the left navigation menu, select the *Roles* tab.
16+
17+
. Select the role that has the group assignment you want to remove.
18+
19+
. Click *Edit*.
20+
21+
. In the *Principals* section, remove the `Group:<name>` entry.
22+
23+
. Click *Update*.

‎modules/manage/partials/gbac-create-group-acl.adoc‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
In {ui}, group-based ACLs are managed through roles. To create an ACL for an OIDC group:
2+
3+
. From *Security* on the left navigation menu, select the *Roles* tab.
4+
5+
. Click *Create role* to open the role creation form, or select an existing role and click *Edit*.
6+
7+
. In the *Principals* field, enter the group principal using the `Group:<name>` format. For example, `Group:engineering`.
8+
9+
. 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.
10+
11+
. Click *Create* (or *Update* if editing an existing role).
12+
13+
NOTE: {ui} 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`.

0 commit comments

Comments
 (0)