Improve authN and authZ topics #1115
Conversation
|
Important Review skippedAuto incremental reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the You can disable this status message by setting the 📝 WalkthroughWalkthroughThe changes reorganize and clarify the documentation related to Redpanda Console authentication, authorization, and navigation. The navigation structure was updated to move UI-related links to the "Develop" section and flatten the console configuration hierarchy. The authentication and authorization documentation was extensively rewritten to clarify the distinction between using Redpanda's RBAC/ACLs (via impersonation) versus Console role bindings, with improved examples and configuration guidance. New documentation was added to explicitly describe OIDC limitations and migration steps from Console role bindings to Redpanda ACLs, including concrete examples and summary tables. Some files were deleted or updated to reflect the new documentation structure. Sequence Diagram(s)sequenceDiagram
participant User
participant Console
participant Redpanda
User->>Console: Login (OIDC/Basic)
Console->>Console: Authenticate User
alt Impersonation Enabled
Console->>Redpanda: Forward API requests with user identity
Redpanda->>Redpanda: Authorize via RBAC/ACLs
Redpanda-->>Console: API Response
else Impersonation Disabled
Console->>Console: Authorize via Console roleBindings
Console-->>User: UI/API Response
end
Assessment against linked issues
Suggested reviewers
🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
✅ Deploy Preview for redpanda-docs-preview ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🧹 Nitpick comments (9)
modules/manage/partials/security/oidc/limitations.adoc (1)
3-10: Nitpick: unify bullet sentence style. Consider starting each point with “TherpkCLI” or “Redpanda Console” for consistency across bullets.modules/migrate/pages/console-v3.adoc (1)
215-222: Suggest using an admonition for emphasis. The note about impersonation ignoringroleBindingsis critical—consider wrapping it in an[IMPORTANT]or[NOTE]block to improve visibility.modules/ROOT/nav.adoc (1)
48-49: Optional: Reorder for alphabetical consistency. Consider listingFilter MessagesandDeserialize Messagesin alphabetical order or grouping by function for easier scanning.modules/console/pages/config/security/authentication.adoc (2)
22-29: Eliminate redundant introduction and unify terminology
The two opening paragraphs (lines 22 and 24) overlap in content. Consider merging them for conciseness and harmonize the bullet list capitalization (e.g., “Basic Authentication” instead of “basic authentication”) for consistency.
107-109: Clarify OIDC redirect and token refresh behavior
TheredirectUrl,accessType, andpromptfields are well explained. Consider adding a cross-reference to the “HTTP path rewrites” topic for users using custom hostnames.modules/console/pages/config/security/authorization.adoc (4)
31-33: Merge repetitive role disclaimer
Lines 31 and 33 both note that Console roles apply only when impersonation is disabled and require Redpanda ACLs. Consider combining to avoid redundancy.
47-47: Review role limitations for consistency
The Viewer and Editor rows use “Cannot…”, while Admin uses “No limitations.” For parallel style, consider “None” or “N/A” in the Admin row to match the sentence fragment pattern.Also applies to: 56-56, 63-63
111-116: Clarify nesting of authentication in example
The snippet intermixes Kafka SASL and Console’sauthentication:section without explicit top-level context. Recommend adding a comment or header indicating that bothkafka:and top-levelauthentication:live at the root of the same config file.
122-122: Quote example usernames for clarity
Wrapname: Peterin quotes ("Peter") to avoid YAML parsing issues and match other examples.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (8)
modules/ROOT/nav.adoc(2 hunks)modules/console/pages/config/index.adoc(0 hunks)modules/console/pages/config/security/authentication.adoc(5 hunks)modules/console/pages/config/security/authorization.adoc(3 hunks)modules/manage/pages/console/index.adoc(1 hunks)modules/manage/partials/authentication.adoc(1 hunks)modules/manage/partials/security/oidc/limitations.adoc(1 hunks)modules/migrate/pages/console-v3.adoc(2 hunks)
💤 Files with no reviewable changes (1)
- modules/console/pages/config/index.adoc
⏰ Context from checks skipped due to timeout of 90000ms (3)
- GitHub Check: Redirect rules - redpanda-docs-preview
- GitHub Check: Header rules - redpanda-docs-preview
- GitHub Check: Pages changed - redpanda-docs-preview
🔇 Additional comments (15)
modules/manage/partials/security/oidc/limitations.adoc (1)
1-10: Approve addition of OIDC limitations section. This succinctly outlines current constraints relevant to users.modules/manage/pages/console/index.adoc (1)
4-4: Approve addition of page alias. This preserves backward compatibility for references to the old console configuration index.modules/migrate/pages/console-v3.adoc (2)
176-179: Approve clarification on roleBindings migration. The new paragraphs clearly explain how v3 consolidates roleBindings into the main configuration.
223-245: Approve rpk ACL examples. The Bash snippet provides clear, actionable commands for mapping Console roles to Redpanda ACLs.modules/ROOT/nav.adoc (2)
40-40: Approve addition of UI links under Develop. Moving these console UI topics to the Develop section improves discoverability for developer workflows.
199-206: Verify nav entries align with new file structure. Ensure that the promotedxref:console:config/...pages exist at the specified paths and that the:page-aliases:inmodules/manage/pages/console/index.adoccorrectly coversconsole:config/index.adoc.modules/console/pages/config/security/authentication.adoc (5)
92-93: Configure JWT signing and cookie security correctly
ThejwtSigningKeyanduseSecureCookiessettings are clear and well documented. Using secure cookies (useSecureCookies: true) is recommended in production to prevent token leakage.
95-98: OIDC runtime acquisition parameters are well detailed
Theoidcblock clearly explains required fields (enabled,issuerUrl,clientId,clientSecret). Ensure that theissuerUrlmatches your IdP’s v2.0 endpoint.
100-102: Additional scopes and TLS options are comprehensive
IncludingadditionalScopesandissuerTlsoptions provides necessary flexibility for mTLS and scope requests. The use of comments (# <7>,# <8>) is consistent with the rest of the doc.
134-134: Static token mode succinctly documented
Thetokenfield is correctly placed and noted as pre-acquired. A reminder about token rotation or expiration handling in the limitations section could be helpful.
185-186: Entra ID scopes example aligns with Azure requirements
Good addition of theapi://<client-id>/entraid.v2-access-tokensscope pattern and accompanying note referencing Microsoft docs.modules/console/pages/config/security/authorization.adoc (4)
82-85: Static Kafka credentials example is clear
TheimpersonateUser: falseblock withusername,password, andmechanismis correctly illustrated. The inline footnotes explain context well.
87-91: RoleBindings mapping example is correct
TheroleBindings:section andloginType: basicmapping are properly formatted and explained by the footnote.
130-130: Approve multi-role assignment explanation
The new description of multiple roles producing a union of permissions is clear and well-placed.
139-143: Multi-role example formatting is accurate
The example shows separate- roleNameentries forviewerandeditorcorrectly, reinforcing that duplicate roles are idempotent.
| Roles in Redpanda Console determine the actions users can perform in the UI. These roles are defined independently from Redpanda roles and only apply when impersonation is disabled. When impersonation is enabled, user permissions are derived entirely from Redpanda's internal role and ACL configuration. | ||
|
|
||
| Redpanda Console comes with the following roles: | ||
| For example, even if a user is assigned the Admin role in Console, they must also have the appropriate Redpanda ACLs to successfully perform protected actions. |
There was a problem hiding this comment.
exactly!, @mattschumpert, this piece was surprising when I found out. If I'm giving my user Console's built-in "Admin", why do I have to keep granting it more permissions? As a user, it makes no sense at all.
There was a problem hiding this comment.
Do you mean debug bundle generation specifically?
JakeSCahill
changed the title
| Roles in Redpanda Console determine the actions users can perform in the UI. These roles are defined independently from Redpanda roles and only apply when impersonation is disabled. When impersonation is enabled, user permissions are derived entirely from Redpanda's internal role and ACL configuration. | ||
|
|
||
| Redpanda Console comes with the following roles: | ||
| For example, even if a user is assigned the Admin role in Console, they must also have the appropriate Redpanda ACLs to successfully perform protected actions. |
There was a problem hiding this comment.
Do you mean debug bundle generation specifically?
Co-authored-by: Joyce Fee <102751339+Feediver1@users.noreply.github.com>
Co-authored-by: Joyce Fee <102751339+Feediver1@users.noreply.github.com>
Co-authored-by: Joyce Fee <102751339+Feediver1@users.noreply.github.com>
Description
Resolves https://redpandadata.atlassian.net/browse/DOC-1293
Review deadline: May 12
This pull request includes updates to the documentation and configuration files for Redpanda, focusing on improvements to authentication documentation. The most significant changes include adding new navigation links, reorganizing sections for better clarity, and enhancing the authentication documentation with additional details and examples.
Documentation and Navigation Updates:
modules/ROOT/nav.adocfor features such as "Edit Topic Configuration," "Filter Messages," and "Deserialize Messages." These changes improve discoverability of specific features.modules/ROOT/nav.adocto move "Upgrade" and "Migrate" sections to a more logical position, ensuring a clearer hierarchy. [1] [2]Authentication Documentation Enhancements:
authentication.adocfile by clarifying the integration of authentication methods (OIDC and basic authentication) with Redpanda APIs, and added detailed examples for configuration. This includes runtime acquisition and static token modes for OIDC. [1] [2]Page previews
Checks