Conversation
✅ Deploy Preview for redpanda-docs-preview ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
|
Important Review skippedAuto reviews are disabled on base/target branches other than the default branch. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
nguyen-andrew
left a comment
nguyen-andrew
left a comment
There was a problem hiding this comment.
Looks good so far! Just some minor comments and questions
modules/manage/partials/gbac-dp.adoc
Outdated
| @@ -0,0 +1,336 @@ | |||
| // tag::single-source[] | |||
|
|
|||
| Group-based access control (GBAC) builds on xref:manage:security/authorization/rbac.adoc[role-based access control (RBAC)] to simplify permission management at scale. Instead of assigning roles or ACLs to individual users, you assign them to OIDC groups managed by your identity provider (IdP). Users inherit permissions from all groups reported in their OIDC token claims, so onboarding and offboarding require no changes in Redpanda. | |||
There was a problem hiding this comment.
I wonder if we should mention OIDC earlier in the paragraph (like in the first sentence) so readers immediately understand that GBAC depends on OIDC being configured. I think the OIDC dependency could be easy to miss upfront until the reader reads further down (like the Prerequisites section).
modules/manage/partials/gbac-dp.adoc
Outdated
| 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. |
There was a problem hiding this comment.
Adding a link to Customize token claim extraction#nested_group_behavior or the nested_group_behavior section in the cluster properties reference could be helpful here too, if possible.
modules/manage/pages/kubernetes/security/authorization/k-gbac.adoc
Outdated
Show resolved
Hide resolved
treevon
left a comment
treevon
left a comment
There was a problem hiding this comment.
This looks good. The token extraction section is really nice with clear examples
modules/manage/partials/gbac-dp.adoc
Outdated
| == Prerequisites | ||
|
|
||
| * xref:manage:security/authentication.adoc#oidc[OIDC authentication] must be configured and enabled on your cluster. | ||
| * Superuser access to configure cluster properties and manage ACLs. |
There was a problem hiding this comment.
nit - this is a prerequisite to enable OIDC, so should appear first
There was a problem hiding this comment.
@treevon for Cloud should we just remove this superuser prereq?
modules/manage/partials/gbac-dp.adoc
Outdated
| --resource-pattern-type prefixed | ||
| ---- | ||
|
|
||
| If your groups use path-style names (with xref:reference:properties/cluster-properties.adoc#nested_group_behavior[`nested_group_behavior`] set to `none`), use the full path as the principal name: |
There was a problem hiding this comment.
I think we should move this to the section on claim extraction
# Conflicts: # modules/get-started/pages/release-notes/redpanda.adoc
modules/manage/partials/gbac-dp.adoc
Outdated
| end | ||
| .... | ||
|
|
||
| == Prerequisites |
There was a problem hiding this comment.
suggest moving Prerequisites up above How GBAC works
|
|
||
| . Click *Create role* to open the role creation form, or select an existing role and click *Edit*. | ||
|
|
||
| . In the *Principals* field, enter the group principal using the `Group:<name>` format. For example, `Group:engineering`. |
There was a problem hiding this comment.
| . In the *Principals* field, enter the group principal using the `Group:<name>` format. For example, `Group:engineering`. | |
| . For *Principals*, enter the group principal using the `Group:<name>` format. For example, `Group:engineering`. |
Not sure how this will look?
| -- | ||
| endif::[] | ||
| ==== | ||
|
|
There was a problem hiding this comment.
It's a little weird that the options for Create group-based ACLs include rpk and Console but right after View groups and roles options include rpk and Admin API. We can add Console for that too, right?
modules/manage/partials/gbac-dp.adoc
Outdated
| ifdef::env-cloud[] | ||
| Contact Redpanda support to configure these properties on Cloud clusters. | ||
| endif::[] |
There was a problem hiding this comment.
Do we need to confirm that, that these properties will not be configurable in Cloud? And it looks like we still need to create a PR in cloud-docs to add GBAC to Cloud.
| ---- | ||
|
|
||
| ==== CSV-formatted group claim | ||
|
|
There was a problem hiding this comment.
For CSV, I think the text should go above the example, similar to the others
There was a problem hiding this comment.
I feel like the text would make more sense below the token example rather then before. For ex, I think this reads better
this is an example token group claim from the idp
this is how redpanda would extract the groups from that token
rather than
this is how redpanda would extract the groups from that token
this is an example token group claim from the idp
| When xref:manage:audit-logging.adoc[audit logging] is enabled, authentication 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`. | ||
|
|
||
| == Suggested reading | ||
|
|
There was a problem hiding this comment.
The list of suggested readings have already been linked above, and idk if the labs are really relevant. I'd probably replace with a Next steps
There was a problem hiding this comment.
Changed Suggested reading to Next steps, but I think the labs automatically display based on the page categories
| * Assign a group as a member of an RBAC role so that all users in the group inherit the role's ACLs. | ||
| * Create ACLs directly with a `Group:<name>` principal. | ||
|
|
||
| Group membership is managed entirely by your IdP. Redpanda reads group information from the OIDC token at authentication time and works across all Redpanda APIs (Kafka, Admin, Schema Registry, and HTTP Proxy). |
There was a problem hiding this comment.
please conditionalize out Admin API for cloud
|
|
||
| * xref:manage:security/authorization/gbac.adoc[Configure Group-Based Access Control] | ||
| * xref:manage:kubernetes/security/authorization/k-role-controller.adoc[Manage Roles and ACLs (Operator)] | ||
| * xref:manage:security/authorization/rbac.adoc[Role-Based Access Control (RBAC)] |
There was a problem hiding this comment.
Can you please conditionalize all these /rbac links for Cloud to xref:security:authorization/rbac/rbac.adoc. We have Security up a level in Cloud
There was a problem hiding this comment.
These are for the Kubernetes doc, so n/a
Co-authored-by: Michele Cyran <michele@redpanda.com>
modules/manage/partials/gbac-dp.adoc
Outdated
| GBAC works across all Redpanda APIs: | ||
|
|
||
| * Kafka API | ||
| * Admin API |
There was a problem hiding this comment.
GBAC doesn't actually have any impact/influence on the Admin API. I think the Admin API only checks that your principal is a superuser and doesn't consider the groups at all (because I don't think you can set ACLs for Admin API endpoints).
| * 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. |
There was a problem hiding this comment.
I feel I'd make sense to put "Group as an ACL principal" first and "Group assigned to a role" second, since Group assigned to a role (which gets ACLs) is 1 more layer of indirection than Group ACLs:
- Group <-- ACLs
- Group -- Role <-- ACLs
|
|
||
| * No wildcard ACLs for groups: ACL matching for `Group:` principals uses literal string comparison only. Wildcard patterns are not supported. | ||
|
|
||
| == Assign groups to roles |
There was a problem hiding this comment.
Related: https://github.com/redpanda-data/docs/pull/1584/changes#r2997647468
I feel sort of the same way with the ordering of this section and L169, I think showing Direct Group ACLs first and then showing the additional indirection of Group--Roles<--ACLs would be easier to understand.
There was a problem hiding this comment.
Never mind, I just saw the note about "Redpanda Console assigns ACLs through roles". Maybe the overloading of the term "role" is a little confusing and reordering it might not help.
modules/manage/partials/gbac-dp.adoc
Outdated
|
|
||
| == 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:`. |
There was a problem hiding this comment.
I think the ACL terminology table might also need to be updated (the row for "Principal")
modules/manage/partials/gbac-dp.adoc
Outdated
|
|
||
| == 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:`. |
There was a problem hiding this comment.
Might be nice to have a link to the ACLs page so the reader can see more details of how to use ACLs?
| ---- | ||
| + | ||
| This helps diagnose incorrect claim paths, missing groups, or token content issues. The debug level reverts automatically after the expiry period (default: 300 seconds). | ||
|
|
There was a problem hiding this comment.
Would it be helpful to add the example of how to decode & inspect the OIDC token to check for groups (as shown in the TOI), or is that more in the realm of IdP documentation rather than redpanda documention?
modules/manage/partials/gbac-dp.adoc
Outdated
| When xref:manage:audit-logging.adoc[audit logging] is enabled, authentication 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`. | ||
| endif::[] | ||
| ifdef::env-cloud[] | ||
| When xref:manage:audit-logging.adoc[audit logging] is enabled, authentication 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`. |
There was a problem hiding this comment.
Reviewing this the first time around made me realize that we were missing audit logging for Authorization events against direct group ACLs, so I added that recently. See
There was a problem hiding this comment.
Here's a sample audit log for the API Activity event (6003) with an Authorization matched against an ALLOW ACL directly on a Group:
{
"category_uid": 6,
"class_uid": 6003,
"metadata": {
"product": {
"name": "Redpanda",
"uid": "0",
"vendor_name": "Redpanda Data, Inc.",
"version": "v26.1.0-dev"
},
"profiles": [
"cloud"
],
"version": "1.0.0"
},
"severity_id": 1,
"time": 1774544504327,
"type_uid": 600303,
"activity_id": 3,
"actor": {
"authorizations": [
{
"decision": "authorized",
"policy": {
"desc": "acl: {principal type {group} name {/sales} host {{any_host}} op all perm allow}, resource: type {topic} name {sales-topic} pattern {literal}",
"name": "aclAuthorization"
}
}
],
"user": {
"name": "alice",
"type_id": 1,
"groups": [
{
"type": "idp_group",
"name": "/sales"
}
]
}
},
"api": {
"operation": "produce",
"service": {
"name": "kafka rpc protocol"
}
},
"cloud": {
"provider": ""
},
"dst_endpoint": {
"ip": "127.0.1.1",
"port": 9092,
"svc_name": "kafka rpc protocol"
},
"resources": [
{
"name": "sales-topic",
"type": "topic"
}
],
"src_endpoint": {
"ip": "127.0.0.1",
"name": "rdkafka",
"port": 42728
},
"status_id": 1,
"unmapped": {
"authorization_metadata": {
"acl_authorization": {
"host": "{{any_host}}",
"op": "all",
"permission_type": "allow",
"principal": "type {group} name {/sales}"
},
"resource": {
"name": "sales-topic",
"pattern": "literal",
"type": "topic"
}
}
}
}| * Assign a group as a member of an RBAC role so that all users in the group inherit the role's ACLs. | ||
| * Create ACLs directly with a `Group:<name>` principal. | ||
|
|
||
| Group membership is managed entirely by your IdP. Redpanda reads group information from the OIDC token at authentication time and works across all Redpanda APIs (Kafka, Admin, Schema Registry, and HTTP Proxy). |
There was a problem hiding this comment.
Similar note as this comment - GBAC doesn't actually have any impact/influence on the Admin API.
5 participants
Description
Related PR to add Security to Admin API v2: redpanda-data/api-docs#60
Single sourcing to Cloud: redpanda-data/cloud-docs#536
This pull request introduces comprehensive documentation for Group-Based Access Control (GBAC) in Redpanda, detailing how permissions can now be assigned to OIDC groups in addition to individual users. It adds new conceptual and how-to guides, updates navigation, and describes configuration, usage patterns, and limitations for GBAC. It also documents new configuration properties relevant to group extraction from authentication tokens.
The most important changes are:
GBAC Documentation and How-to Guides:
gbac.adocunder security/authorization, with detailed instructions, usage patterns, configuration, and examples for assigning groups to roles and creating group-based ACLs. [1] [2]gbac-assign-group-role.adoc) and group ACL creation (gbac-create-group-acl.adoc). [1] [2]Navigation and Discoverability:
nav.adoc) to include GBAC under both Kubernetes and general security/authorization sections, making the new documentation easily discoverable. [1] [2]Release Notes and Feature Announcements:
nested_group_behaviorandoidc_group_claim_path.OIDC Authentication Documentation:
Resolves DOC-1789
Review deadline: March 3rd
Page previews
Main doc - GBAC
Cluster Properties:
Authorization index
Audit logging
Audit logging samples
What's new
Checks