DOC-1347 Document principalMapping configuration for Redpanda Console OIDC auth (#1158)

Author: JakeSCahill

modules/console/pages/config/connect-to-redpanda.adoc

@@ -1,4 +1,4 @@
-= Configure a Connection to a Redpanda Cluster
+= Configure Redpanda Console to Connect to a Redpanda Cluster
 :description: This topic provides instructions on configuring Redpanda Console to connect to a Redpanda cluster. The configuration ensures that Redpanda Console can communicate with your Redpanda brokers.
 
 Redpanda Console connects to your Redpanda cluster using dedicated configuration blocks for the Kafka API, Schema Registry API, and Admin API. Each connection serves a different purpose:

modules/console/pages/config/http-path-rewrites.adoc

@@ -1,4 +1,4 @@
-= HTTP Path Rewrites
+= HTTP Path Rewrites in Redpanda Console
 :description: Learn how to configure Redpanda Console to work seamlessly with your URL path rewrites, particularly when hosted under a subpath.
 :page-aliases: console:features/http-path-rewrites.adoc, manage:console/http-path-rewrites.adoc
 

modules/console/pages/config/security/authentication.adoc

@@ -1,4 +1,4 @@
-= Authentication
+= Authentication in Redpanda Console
 :description: Authentication in Redpanda Console enables users to log in and optionally forward their credentials to the connected Redpanda cluster, ensuring all API requests are executed under the user's identity.
 :page-aliases: console:single-sign-on/authentication.adoc, manage:security/console/authentication.adoc, console:config/security/plain.adoc, console:config/security/okta.adoc, console:config/security/generic-oidc.adoc, console:config/security/keycloak.adoc, console:config/security/github.adoc, console:config/security/google.adoc, console:config/security/azure-ad.adoc
 :page-categories: Security, Management, Redpanda Console
@@ -36,7 +36,7 @@ image::console:login.png[]
 Redpanda Console can authenticate to Redpanda APIs in two ways:
 
 * *User impersonation:* Uses the same credentials you log in with to authenticate API requests. This ensures accurate audit logs and unified identity enforcement.
-* *Static service account credentials:* Uses preconfigured credentials defined in the Redpanda Console configuration file. Useful when impersonation is disabled or RBAC needs to be separated from Redpanda identities.
+* *Static service account credentials:* Uses preconfigured credentials defined in the Redpanda Console configuration file. Useful when impersonation is disabled or glossterm:RBAC[] needs to be separated from Redpanda identities.
 
 Upon login, Redpanda Console generates a secure session with a JSON Web Token (JWT), signed by the `authentication.jwtSigningKey`. The JWT can be stored as a secure cookie and is used to authenticate API requests.
 
@@ -115,19 +115,21 @@ authentication:
     redirectUrl: "http://localhost:8080/auth/callbacks/oidc" # <9>
     accessType: "offline" # <10>
     prompt: "consent" # <11>
+    principalMapping: "$.sub" # <12>
 ----
 
-<1> Required. Secret key for signing JWTs. Must be at least 32 characters. Store securely. You can also use the `AUTHENTICATION_JWTSIGNINGKEY`environment variable.
+<1> Required. Secret key for signing JWTs. Must be at least 32 characters. Store securely. You can also use the `AUTHENTICATION_JWTSIGNINGKEY` environment variable.
 <2> Recommended in production. Marks cookies as secure.
 <3> Required. Enables OIDC authentication.
 <4> Required. URL of the OIDC identity provider (IdP).
 <5> Required. The client ID from your IdP.
 <6> Required. The client secret from your IdP. You can also use the `AUTHENTICATION_OIDC_CLIENTSECRET` environment variable.
 <7> Requested scopes. Some IdPs such as Azure Entra ID require additional scopes to request OAuth 2.0-compliant tokens.
-<8> Optional. TLS configuration for secure connections to the IdP. Configure TLS only if you require mTLS or if you use a self-signed certificate for your identity provider.
-<9> Optional. Redirect URI registered with the IdP. This URL must be registered with your IdP and must point to the `/auth/callbacks/oidc` path in Redpanda Console. If this URL is not configured, Redpanda Console constructs the URL by using the base URL from the request and adding the `/auth/callbacks/oidc` path. You may want to configure this URL if you use xref:console:config/http-path-rewrites.adoc[HTTP path rewrites].
-<10> Optional. Controls whether a refresh token is requested. A value of `offline` (default) requests a refresh token for long-lived sessions. Set it to `online` if you don't want a refresh token.
-<11> Optional. Determines how the authorization prompt is displayed. Use `consent` (default) to force the consent screen to appear even if the user has previously authorized the application. Alternatives include `none` (no prompt) or `select_account` to allow the user to choose an account. Some IdPs require `consent` to issue a refresh token.
+<8> Optional. TLS configuration for secure connections to the IdP. Configure TLS only if you require mTLS or use a self-signed certificate.
+<9> Optional. Redirect URI registered with the IdP. This URI must point to the `/auth/callbacks/oidc` path in Redpanda Console. If not set, Console constructs the URL from the request. Configure this option explicitly if you're using xref:console:config/http-path-rewrites.adoc[HTTP path rewrites].
+<10> Optional. Controls whether a refresh token is requested. `offline` (default) requests a refresh token. Set to `online` to disable refresh token requests.
+<11> Optional. Determines how the authorization prompt appears. Use `consent` (default) to force re-consent. Other options include `none` and `select_account`. Some IdPs require `consent` to issue a refresh token.
+<12> Optional. Extracts and optionally transforms a claim from the OIDC token to use as the user's identity in Redpanda Console role bindings. The default is `"$.sub"`, which uses the `sub` (subject) claim from the token. This value is then compared to the `name` field in your `authorization.roleBindings` configuration. For full syntax and transformation examples, see xref:console:config/security/authorization.adoc#_transform_identities_with_principal_mappings[Transform identities with principal mappings].
 
 ==== Enable static token mode
 
@@ -404,20 +406,6 @@ authorization:
 When impersonation is disabled, Redpanda Console executes Admin API requests as the service identity represented in the token. This is typically the `sub` from the client credentials flow, and must match an ACL or RBAC binding.
 ====
 
-== Authorization overview
-
-Authentication allows users to log in, but authorization determines what they can do once authenticated.
-
-Redpanda Console supports role-based access control (RBAC) through two modes:
-
-- **User impersonation enabled**: Redpanda enforces authorization using its internal ACL and RBAC rules. The identity of the logged-in user is forwarded to the Kafka API, Admin API, and Schema Registry.
-- **User impersonation disabled**: Redpanda Console enforces access using `roleBindings` in the Redpanda Console configuration file. All API requests are made using a static service account.
-
-[IMPORTANT]
-====
-Even with a valid login, users must still be granted permissions in Redpanda or in `roleBindings` to access resources. A Redpanda Console role (such as Admin) does not automatically grant permissions in Redpanda.
-====
-
 == Next steps
 
 - xref:console:config/security/authorization.adoc[Configure role-based access control (RBAC) in Redpanda Console]

modules/console/pages/config/security/authorization.adoc

@@ -1,4 +1,4 @@
-= Authorization
+= Authorization in Redpanda Console
 :description: Redpanda Console supports role-based access control (RBAC) to restrict system access to authorized users. This page is intended for cluster administrators who manage Redpanda Console access and need to configure UI-based authorization.
 :page-aliases: console:single-sign-on/authorization.adoc, manage:security/console/authorization.adoc, console:features/role-bindings.adoc, console:reference/role-bindings.adoc, reference:console/role-bindings.adoc
 :page-categories: Security, Management, Redpanda Console
@@ -8,7 +8,7 @@
 include::shared:partial$enterprise-and-console.adoc[]
 ====
 
-{description}
+Authentication allows users to log in, but authorization determines what they can do once authenticated.
 
 Redpanda Console supports two authorization modes, depending on whether *user impersonation* is enabled in the authentication configuration:
 
@@ -20,7 +20,7 @@ Redpanda Console supports two authorization modes, depending on whether *user im
 | Redpanda Console evaluates permissions using role bindings defined in its configuration. Redpanda sees all requests as coming from a static service account.
 
 | Impersonation enabled (`impersonateUser: true`)
-| Redpanda evaluates permissions using its internal RBAC and ACLs. Any role bindings in the Redpanda Console configuration are ignored.
+| Redpanda evaluates permissions using its internal glossterm:RBAC[] and ACLs. Any role bindings in the Redpanda Console configuration are ignored.
 |===
 
 For more information about authentication options, see the xref:console:config/security/authentication.adoc[Redpanda Console authentication].
@@ -76,6 +76,8 @@ Use this mode to allow users to log in, while still having all API calls execute
 authentication:
   basic:
     enabled: true
+  oidc:
+    enabled: true
 
 kafka:
   sasl:
@@ -101,7 +103,7 @@ Roles in Redpanda Console determine which UI features users can access. These ro
 .Do you have user impersonation enabled?
 [%collapsible]
 ====
-Redpanda Console roles are not used when user impersonation is enabled for an API. When impersonation is enabled, the user's identity is forwarded to Redpanda, which then authorizes access based on RBAC and ACL rules. 
+Redpanda Console roles are not used when user impersonation is enabled for an API. When impersonation is enabled, the user's identity is forwarded to Redpanda, which then authorizes access based on RBAC and ACL rules.
 
 To successfully log in and access the UI, users must have valid Redpanda credentials and ACLs that permit access to the Kafka API.
 
@@ -229,6 +231,67 @@ authorization:
 
 All APIs must be accessible using a superuser principal. If the service account lacks superuser status, Redpanda Console may not be able to fetch cluster status, access the Admin API, or interact with the Schema Registry.
 
+=== Transform identities with principal mappings
+
+If you use OIDC login, the identity in the JWT token is extracted using a JSONPath expression. By default, this expression is `$.sub`, which means the value of the `sub` claim is used as the username. You can override this expression using the `principalMapping` option to transform or extract a different claim to match the `name` values in your `roleBindings` configuration.
+
+To keep authorization consistent between Console and Redpanda, set `principalMapping` to match Redpanda's cluster configuration value for xref:reference:properties/cluster-properties.adoc#oidc_principal_mapping[`oidc_principal_mapping`].
+
+.Example: Map email to local username
+[,yaml,lines=9]
+----
+authentication:
+  oidc:
+    enabled: true
+    issuerUrl: https://auth.dev.cloud.redpanda.com/
+    clientId: R1iX7Pls9UMXiUoYBOn4NcIUTbaGX4JG
+    clientSecret: redacted
+    redirectUrl: http://localhost:9090/auth/callbacks/oidc
+    successfulLoginRedirectUrl: http://localhost:3000
+    principalMapping: $.email/([^@]+)@example.com/$1/L
+----
+
+This example:
+
+* Extracts the `email` field from the OIDC token
+* Uses a regular expression to capture the username part
+* Replaces the value with the captured group `$1`
+* Converts the result to lowercase (`L` modifier)
+
+As a result, the user identity becomes `matt` when the email is `matt@example.com`.
+
+You can then define role bindings like this:
+
+[,yaml]
+----
+authorization:
+  roleBindings:
+    - roleName: admin
+      users:
+        - loginType: oidc
+          name: matt
+----
+
+==== Match syntax and modifiers
+
+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
+
+[NOTE]
+====
+If `principalMapping` is not set, Redpanda Console defaults to using the `sub` claim as the user identity.
+====
+
 == Multiple roles and duplicate bindings
 
 You can assign multiple roles to the same user through role bindings. In this case, the user receives the union of all permissions associated with those roles.

modules/console/pages/config/security/tls-termination.adoc

@@ -1,4 +1,4 @@
-= TLS Termination
+= TLS Termination in Redpanda Console
 :page-aliases: manage:security/console/tls-termination.adoc
 :description: To secure Redpanda Console using TLS, you can let Redpanda Console handle TLS termination or you can offload it to an upstream component, such as a reverse proxy or a Cloud HTTPS LoadBalancer.
 :page-categories: Management, Security, Redpanda Console

modules/console/pages/config/topic-documentation.adoc

@@ -1,4 +1,4 @@
-= Enable Topic Documentation
+= Enable Topic Documentation in Redpanda Console
 :description: Embed your Kafka topic documentation into the Redpanda Console UI by linking a Git repository that contains the topic documentation files.
 :page-aliases: console:features/topic-documentation.adoc, manage:console/topic-documentation.adoc
 

modules/reference/pages/properties/cluster-properties.adoc

@@ -4110,6 +4110,12 @@ Rule for mapping JWT payload claim to a Redpanda user principal.
 
 ifndef::env-cloud[]
 *Default:* `$.sub`
+
+*Related topics*:
+
+* xref:manage:security/authentication.adoc#oidc[OpenID Connect authentication]
+* xref:manage:kubernetes/security/authentication/k-authentication.adoc[OpenID Connect authentication in Kubernetes]
+
 endif::[]
 
 ---