DOC-1347 Document principalMapping configuration for Redpanda Console OIDC auth #1158
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 are limited to documentation updates across several files. The main update is the addition and documentation of a new Sequence Diagram(s)sequenceDiagram
participant User
participant RedpandaConsole
participant OIDCProvider
User->>RedpandaConsole: Initiate OIDC login
RedpandaConsole->>OIDCProvider: Redirect for authentication
OIDCProvider->>User: Prompt for credentials
User->>OIDCProvider: Provide credentials
OIDCProvider->>RedpandaConsole: Return OIDC token
RedpandaConsole->>RedpandaConsole: Apply principalMapping to token claim
RedpandaConsole->>RedpandaConsole: Map to internal username
RedpandaConsole->>RedpandaConsole: Check role bindings for username
RedpandaConsole-->>User: Grant/deny access based on authorization
Assessment against linked issues
Assessment against linked issues: Out-of-scope changesNo out-of-scope changes were found. 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. 🪧 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: 0
🧹 Nitpick comments (2)
modules/reference/pages/properties/cluster-properties.adoc (1)
4097-4100: Use-for bullets in Related topics.Unordered lists in this file consistently use
-for list items. Update the new section to match existing style:*Related topics*: -* xref:manage:security/authentication.adoc#oidc[OpenID Connect authentication] -* xref:manage:kubernetes/security/authentication/k-authentication.adoc[OpenID Connect authentication in Kubernetes] +*Related topics*: + - xref:manage:security/authentication.adoc#oidc[OpenID Connect authentication] + - xref:manage:kubernetes/security/authentication/k-authentication.adoc[OpenID Connect authentication in Kubernetes]modules/console/pages/config/security/authorization.adoc (1)
234-293: DocumentprincipalMappingtransformation featureThe new section comprehensively explains how to transform OIDC claims using JSONPath, regex, replacement, and modifiers. Consider renaming the heading to
=== `principalMapping` transformation syntaxto match code formatting conventions.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (7)
modules/console/pages/config/connect-to-redpanda.adoc(1 hunks)modules/console/pages/config/http-path-rewrites.adoc(1 hunks)modules/console/pages/config/security/authentication.adoc(2 hunks)modules/console/pages/config/security/authorization.adoc(5 hunks)modules/console/pages/config/security/tls-termination.adoc(1 hunks)modules/console/pages/config/topic-documentation.adoc(1 hunks)modules/reference/pages/properties/cluster-properties.adoc(1 hunks)
⏰ Context from checks skipped due to timeout of 90000ms (4)
- GitHub Check: Redirect rules - redpanda-docs-preview
- GitHub Check: Header rules - redpanda-docs-preview
- GitHub Check: run-tests (ubuntu-latest)
- GitHub Check: Pages changed - redpanda-docs-preview
🔇 Additional comments (12)
modules/console/pages/config/topic-documentation.adoc (1)
1-1: Consistent title update
Changed the document title to “Enable Topic Documentation in Redpanda Console” to match the naming convention used across other Console configuration pages.modules/console/pages/config/security/tls-termination.adoc (1)
1-1: Consistent title update
Updated the title to “TLS Termination in Redpanda Console,” aligning it with the standardized naming scheme for Console docs.modules/console/pages/config/http-path-rewrites.adoc (1)
1-1: Consistent title update
Revised the title to “HTTP Path Rewrites in Redpanda Console” for uniformity across Console configuration guides.modules/console/pages/config/connect-to-redpanda.adoc (1)
1-1: Title clarifies console contextThe updated title explicitly states that this document configures Redpanda Console, improving clarity.
modules/console/pages/config/security/authentication.adoc (4)
1-1: Title updated to specify Console contextChanging the title to include "in Redpanda Console" aligns it with other security docs and clarifies scope.
118-119: AddprincipalMappingoption to OIDC configThe new
principalMappingfield (defaulting to$.sub) and its explanatory footnote clearly describe how to map and transform claims for role bindings.Also applies to: 132-132
121-121: Fix spacing in JWT signing key descriptionThe
<1>footnote now correctly includes a space before the variable example, improving readability.
128-131: Clarify optional TLS and redirect settingsFootnotes
<8>–<11>have been reworded for clarity on TLS config, redirect URL, and OAuth prompts. Clear and concise.modules/console/pages/config/security/authorization.adoc (4)
1-1: Title updated to specify Console contextRenaming to "Authorization in Redpanda Console" aligns with the authentication doc and clarifies the scope.
11-11: Clarify distinction between authentication and authorizationThe updated line clearly differentiates login from post-login permissions, improving the introduction.
77-78: Enable OIDC in static service account exampleAdding
oidc: enabled: trueensures consistency with the authentication overview and allows OIDC UI login in this mode.
106-106: Refine impersonation note in collapsible sectionThe revised note explicitly states that console roles are ignored when impersonation is enabled, reinforcing expected behavior.
|
|
||
| === Transform identities with principal mappings | ||
|
|
||
| If you use OIDC login, the identity in the JWT token (the `sub` claim by default) must match a `name` in the `roleBindings` configuration. You can use the `principalMapping` configuration option to transform the identity claim into a username format expected by your role bindings. |
There was a problem hiding this comment.
WDYT about mentioning that this defaults to $.sub which just extracts the sub claim as is, without transforming the value. I think this makes the syntax a little clearer than saying "the sub claim by default".
| The `principalMapping` syntax uses this format: | ||
|
|
||
| ---- | ||
| <jsonpath>/<regex>/<replacement>/<modifiers> | ||
| ---- | ||
|
|
||
| * `jsonpath`: Path to the claim field in the token (such as `$.email`) | ||
| * `regex`: A regular expression to extract part of the claim | ||
| * `replacement`: A replacement string using a captured group (such as `$1`) | ||
| * `modifiers`: Optional flags, such as: | ||
| - `L` — convert to lowercase | ||
| - `U` — convert to uppercase |
There was a problem hiding this comment.
Great explanation. Good that we include it, since it's very custom, but powerful!
|
Suggest adding glossterm for RBAC on authorization & authentication pages. |
Description
Resolves https://redpandadata.atlassian.net/browse/DOC-1347
Review deadline: June 13
This pull request updates multiple Redpanda Console configuration documentation files to improve clarity and consistency, with a focus on authentication, authorization, and other configuration topics. Key changes include renaming page titles for better context, adding new configuration options for OIDC authentication, and introducing detailed examples for principal mappings.
Documentation updates and improvements:
connect-to-redpanda.adoc,http-path-rewrites.adoc,authentication.adoc,authorization.adoc,tls-termination.adoc,topic-documentation.adoc) to include "in Redpanda Console" for better context. [1] [2] [3] [4] [5] [6]Authentication enhancements:
principalMappingoption for OIDC: Added theprincipalMappingconfiguration option to map and transform OIDC token claims into user identities for role bindings. Detailed examples and syntax explanations are provided, including regex-based transformations. [1] [2]Authorization refinements:
authentication.adoctoauthorization.adocfor better organization and alignment with related content. [1] [2]Related references:
cluster-properties.adocfile to improve discoverability.Page previews
Checks