From c54061124fe66729d089dc0d36a6588e865604fb Mon Sep 17 00:00:00 2001 From: JakeSCahill Date: Wed, 7 May 2025 16:53:41 +0100 Subject: [PATCH 01/24] DOC-1293 Add guidance on converting Console role bindings to Redpanda ACLs --- modules/migrate/pages/console-v3.adoc | 55 ++++++++++++++++++++++++++- 1 file changed, 54 insertions(+), 1 deletion(-) diff --git a/modules/migrate/pages/console-v3.adoc b/modules/migrate/pages/console-v3.adoc index cacb98e022..2a0a44772b 100644 --- a/modules/migrate/pages/console-v3.adoc +++ b/modules/migrate/pages/console-v3.adoc @@ -173,7 +173,9 @@ Redpanda requires a JWT-encoded access token for authentication. While most iden === Role bindings -In v2, role bindings could be configured in a separate file. In v3, the `enterprise` stanza is deprecated, and role bindings must now be configured directly in your main configuration under the `authorization.roleBindings` stanza. For more details, see xref:console:config/security/authorization.adoc[]. +In v2, role bindings could be configured in a separate file. In v3, role bindings are configured directly in the `authorization.roleBindings` stanza of the main configuration file. + +If you do **not** use impersonation, you can continue to use role bindings to control access within Redpanda Console. Each role binding maps users to roles in Redpanda Console using their login type and identity. Here is an example of how to migrate role bindings from a separate file to the main configuration: @@ -210,6 +212,57 @@ authorization: ---- -- +However, if you are using *impersonation* in v3, `roleBindings` are ignored. Instead, access is controlled by Redpanda using ACLs and RBAC. + +==== Migrate Console roles to Redpanda ACLs + +If you previously assigned roles in Redpanda Console, you must now provision those users in Redpanda and grant them the appropriate permissions. + +The following examples show how to map Console roles (`viewer`, `editor`, `admin`) to Redpanda ACLs. + +[,bash] +---- +# Allow a viewer to read topics and consumer groups +rpk security acl create \ + --allow-principal User:alice@example.com \ + --operation read,describe \ + --topic '*' \ + --group '*' + +# Allow an editor to produce and consume +rpk security acl create \ + --allow-principal User:alice@example.com \ + --operation read,write,describe \ + --topic '*' + +rpk security acl create \ + --allow-principal User:alice@example.com \ + --operation describe \ + --group '*' + +# Grant admin access (needs separate superuser assignment for Admin API) +rpk cluster config set superusers "['alice@example.com']" +---- + +[cols="1,3", options="header"] +|=== +| Console Role | Equivalent ACLs in Redpanda + +| Viewer +| `read`, `describe` on topics and groups + +| Editor +| `read`, `write`, `describe` on topics and `describe` on groups + +| Admin +| All of the above, plus `superuser` role using the cluster configuation +|=== + +For details, see: + +- xref:manage:security/authorization/acl.adoc[] +- xref:console:config/security/authorization.adoc[] + == Schema Registry migration In v2, the Schema Registry configuration was nested under the `kafka` stanza. In v3, this configuration is now a top-level stanza. From 6789aa8c25b4cd2a4b63dc71fa6a169ed20eadf2 Mon Sep 17 00:00:00 2001 From: JakeSCahill Date: Wed, 7 May 2025 17:00:12 +0100 Subject: [PATCH 02/24] Improve authN and authZ topics for Console --- modules/ROOT/nav.adoc | 30 +- modules/console/pages/config/index.adoc | 4 - .../pages/config/security/authentication.adoc | 400 ++++++++++-------- .../pages/config/security/authorization.adoc | 111 ++--- modules/manage/pages/console/index.adoc | 1 + modules/manage/partials/authentication.adoc | 2 +- .../partials/security/oidc/limitations.adoc | 10 + 7 files changed, 305 insertions(+), 253 deletions(-) delete mode 100644 modules/console/pages/config/index.adoc create mode 100644 modules/manage/partials/security/oidc/limitations.adoc diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index 9c102a1f76..66e055d5d3 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -37,6 +37,7 @@ ** xref:develop:benchmark.adoc[] ** xref:develop:http-proxy.adoc[] ** xref:develop:config-topics.adoc[] +** xref:console:ui/edit-topic-configuration.adoc[Edit Topic Configuration] ** xref:develop:produce-data/index.adoc[Produce Data] *** xref:develop:produce-data/configure-producers.adoc[] *** xref:develop:produce-data/idempotent-producers.adoc[Idempotent Producers] @@ -44,6 +45,8 @@ ** xref:develop:consume-data/index.adoc[Consume Data] *** xref:develop:consume-data/consumer-offsets.adoc[Consumer Offsets] *** xref:develop:consume-data/follower-fetching.adoc[Follower Fetching] +*** xref:console:ui/programmable-push-filters.adoc[Filter Messages] +*** xref:console:ui/record-deserialization.adoc[Deserialize Messages] ** xref:develop:data-transforms/index.adoc[] *** xref:develop:data-transforms/how-transforms-work.adoc[Overview] *** xref:develop:data-transforms/run-transforms-index.adoc[Get Started] @@ -193,22 +196,17 @@ *** xref:manage:schema-reg/schema-id-validation.adoc[] *** xref:console:ui/schema-reg.adoc[Manage in Redpanda Console] ** xref:manage:console/index.adoc[Redpanda Console] -*** xref:console:config/index.adoc[Configuration] -**** xref:console:config/configure-console.adoc[Configure Console] -**** xref:console:config/enterprise-license.adoc[Add an Enterprise License] -**** xref:console:config/connect-to-redpanda.adoc[Connect to Redpanda] -**** xref:console:config/security/index.adoc[Security] -***** xref:console:config/security/authentication.adoc[Authentication] -***** xref:console:config/security/authorization.adoc[Authorization] -***** xref:console:config/security/tls-termination.adoc[TLS Termination] -**** xref:console:config/http-path-rewrites.adoc[HTTP Path Rewrites] -**** xref:console:config/deserialization.adoc[Deserialization] -**** xref:console:config/kafka-connect.adoc[Kafka Connect] -**** xref:console:config/topic-documentation.adoc[Topic Documentation] -*** xref:console:ui/programmable-push-filters.adoc[Filter Messages] -*** xref:console:ui/record-deserialization.adoc[Deserialize Messages] -*** xref:console:ui/edit-topic-configuration.adoc[Edit Topic Configuration] -*** link:https://github.com/redpanda-data/console/[GitHub^] +*** xref:console:config/configure-console.adoc[Configure Console] +*** xref:console:config/enterprise-license.adoc[Add an Enterprise License] +*** xref:console:config/connect-to-redpanda.adoc[Connect to Redpanda] +*** xref:console:config/security/index.adoc[Security] +**** xref:console:config/security/authentication.adoc[Authentication] +**** xref:console:config/security/authorization.adoc[Authorization] +**** xref:console:config/security/tls-termination.adoc[TLS Termination] +*** xref:console:config/http-path-rewrites.adoc[HTTP Path Rewrites] +*** xref:console:config/deserialization.adoc[Deserialization] +*** xref:console:config/kafka-connect.adoc[Kafka Connect] +*** xref:console:config/topic-documentation.adoc[Topic Documentation] ** xref:manage:recovery-mode.adoc[Recovery Mode] ** xref:manage:rack-awareness.adoc[Rack Awareness] ** xref:manage:monitoring.adoc[] diff --git a/modules/console/pages/config/index.adoc b/modules/console/pages/config/index.adoc deleted file mode 100644 index e03b71b055..0000000000 --- a/modules/console/pages/config/index.adoc +++ /dev/null @@ -1,4 +0,0 @@ -= Configure Redpanda Console -:description: Learn how to configure and manage Redpanda Console. -:page-layout: index - diff --git a/modules/console/pages/config/security/authentication.adoc b/modules/console/pages/config/security/authentication.adoc index 89ef066226..271d756465 100644 --- a/modules/console/pages/config/security/authentication.adoc +++ b/modules/console/pages/config/security/authentication.adoc @@ -19,24 +19,25 @@ include::shared:partial$enterprise-and-console.adoc[] ==== -This topic describes how to enable authentication in Redpanda Console and explains how it interacts with the Kafka API, Admin API, and Schema Registry API in Redpanda. +This topic describes how to enable authentication in Redpanda Console and how it integrates with the Kafka, Admin, and Schema Registry APIs in Redpanda. -Authentication in Redpanda Console lets users log in and optionally forward credentials to the connected cluster, ensuring API requests run under the user's identity. Redpanda Console supports two authentication methods: +Authentication in Redpanda Console lets users log in and optionally forward their credentials to the connected cluster. This ensures API requests run under the user's identity. -* **OIDC (OpenID Connect):** - Uses external identity providers, such as Google, to facilitate single sign-on (SSO). -* **Basic authentication:** - Provides a traditional username and password login. +Redpanda Console supports the following authentication methods: + +* **OIDC (OpenID Connect):** Integrates with external identity providers (IdPs) for single sign-on (SSO). +* **basic authentication:** Uses traditional username and password credentials. image::console:login.png[] -== How authentication works in Redpanda Console +== How authentication works -Redpanda Console can authenticate to the Kafka, Admin, and Schema Registry APIs (Redpanda APIs) using two methods: +Redpanda Console can authenticate to Redpanda APIs in two ways: -- *User impersonation*: Redpanda Console uses the same credentials you use to log into Redpanda Console to authenticate API requests to Redpanda. This authentication method ensures accurate audit trails in xref:manage:audit-logging.adoc[Redpanda audit logs] and unified authorization across both Redpanda and Redpanda Console. Your credentials authenticate with any <>. +* *User impersonation:* Uses the same credentials you log in with to authenticate API requests. This ensures accurate audit logs and unified identity enforcement. +* *Static 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 credentials*: For services such as Kafka Connect and Git, or optionally for Redpanda APIs, Redpanda Console uses static credentials defined in the configuration. +Upon login, 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. [mermaid,width=450px] .... @@ -55,88 +56,72 @@ flowchart TD D --> L[Git] .... -Upon successful login, Redpanda Console creates a secure session by generating a JSON Web Token (JWT). Signed with `authentication.jwtSigningKey` and optionally stored as a secure cookie, the JWT encapsulates your credentials (an OIDC ID token or username/password) to authenticate API requests. - -=== OIDC authentication - -With OIDC, users are redirected to an external identity provider, such as Google, for authentication. After login, the provider issues an ID token that is encapsulated in a JWT. This token is used in the following ways: - -* **Kafka authentication:** - The ID token is mapped to SASL-OAUTHBEARER, allowing Kafka to authenticate requests under the user's identity. - -* **HTTP API authentication:** - The ID token is used in header-based authentication (`Authorization: Bearer `) in the Schema Registry and Admin API. - -Redpanda must be configured with OIDC authentication for its APIs. The OIDC configurations across these APIs must match. Using a consistent identity provider avoids authentication mismatches and ensures seamless integration. - -=== Basic authentication - -For basic authentication, the user submits a username and password directly to Redpanda Console. These credentials are validated and encapsulated within a JWT, which is then used as follows: - -* **Kafka authentication:** - The provided credentials are mapped to SASL-SCRAM, ensuring that Kafka operations execute with the correct user identity. - -* **HTTP API authentication:** - The JWT supports HTTP Basic authentication for other APIs. - == Prerequisites -Your credentials must correspond to an existing user in your Redpanda cluster. Redpanda Console verifies access by confirming whether your credentials authenticate with the Kafka API. As a result, the authentication mechanism configured in Redpanda Console must match the Kafka API's configuration. For example: +* Your credentials must match an existing user in your Redpanda cluster. +* The authentication method used in Redpanda Console must match the configuration of the Kafka API: -- *OIDC:* If you want to log into Redpanda Console with OIDC, you must have SASL-OAUTHBEARER authentication configured for the Kafka API. -- *Basic:* If you want to log into Redpanda Console with basic authentication (username/password), you must have SASL-SCRAM authentication configured for the Kafka API. +**If using OIDC:** +You must have SASL/OAUTHBEARER authentication configured for the Kafka API. -See xref:manage:security/authentication.adoc[Configure Authentication for Redpanda]. +**If using basic authentication:** +You must have SASL/SCRAM authentication configured for the Kafka API. -[[enable-authentication]] -== Enable authentication for Redpanda Console +xref:manage:security/authentication.adoc[Learn how to configure authentication for Redpanda]. -Enable OIDC and basic authentication in Redpanda Console. OIDC offers secure single sign-on for production, while basic authentication provides a simple login option. +== Enable authentication -You can enable both OIDC and basic authentication simultaneously. If you enable both, Redpanda Console presents users with a choice of login methods. +Redpanda Console supports enabling both OIDC and basic authentication simultaneously. If both are enabled, users can choose how to log in. === Enable OIDC authentication -To enable OIDC authentication, configure your OIDC settings in the Redpanda Console configuration file. You can obtain an OIDC token using one of the following modes: +To configure OIDC, choose one of two modes: + +* *Runtime acquisition mode:* Redpanda Console obtains a token from the IdP. +* *Static token mode:* You provide a pre-acquired OIDC token. -* **Runtime acquisition mode:** Configure `clientId`, `clientSecret`, `tokenEndpoint`, and `scope` to have Redpanda Console acquire a token at runtime. -* **Static token mode:** Supply only a pre-acquired token directly using the `token` field. +Redpanda and Redpanda Console require OAuth 2.0-compliant JWT tokens for user authentication. When using OIDC, your IdP must issue JWTs. Redpanda Console uses these tokens to authenticate to Redpanda APIs through SASL/OAUTHBEARER or Bearer headers. -Here is an example configuration for **runtime acquisition mode**: +include::manage:partial$security/oidc/limitations.adoc[leveloffset=+2] + +==== Enable runtime acquisition mode [,yaml] ---- authentication: - jwtSigningKey: "" <1> - useSecureCookies: true <2> + jwtSigningKey: "" # <1> + useSecureCookies: false # <2> oidc: - enabled: true <3> - issuerUrl: "https://accounts.google.com" <4> - clientId: "" <5> - clientSecret: "" <6> + enabled: true # <3> + issuerUrl: "https://login.microsoftonline.com/a5da3be7-35c1-44ff-b6e8-b3b755686ae2/v2.0" # <4> + clientId: "" # <5> + clientSecret: "" # <6> + additionalScopes: + - "" # <7> issuerTls: - enabled: true <7> + enabled: true # <8> caFilepath: "/path/to/ca.pem" certFilepath: "/path/to/issuer-cert.pem" keyFilepath: "/path/to/issuer-key.pem" insecureSkipTlsVerify: false - redirectUrl: "http://localhost:8080/auth/callbacks/oidc" <8> - accessType: "offline" <9> - prompt: "consent" <10> + redirectUrl: "http://localhost:8080/auth/callbacks/oidc" # <9> + accessType: "offline" # <10> + prompt: "consent" # <11> ---- -<1> `authentication.jwtSigningKey` (required): The secret key for signing JWTs. Keep it confidential. It must be at least 32 characters long. Use xref:console:config/configure-console.adoc#environment-variables[environment variables] or command-line flags for sensitive data. -<2> `authentication.useSecureCookies`: A boolean flag indicating whether session cookies should be marked as secure. This should be set to true in production environments to enforce HTTPS. -<3> `authentication.oidc.enabled` (required): Enables OIDC-based authentication. When enabled, external identity providers can be used for single sign-on. -<4> `authentication.oidc.issuerUrl` (required): The URL of the OIDC identity provider. -<5> `authentication.oidc.clientId` (required): The client identifier registered with the OIDC provider during the client registration process. -<6> `authentication.oidc.clientSecret` (required): The client secret associated with the registered client identifier. This secret is used to authenticate the client to the OIDC provider. Use xref:console:config/configure-console.adoc#environment-variables[environment variables] or command-line flags for sensitive data. -<7> `authentication.oidc.issuerTls`: TLS configuration for securely connecting to the identity provider. Configure the CA certificate (and optionally a client certificate and key) to ensure secure communication. You need to configure TLS only if you require mTLS or if you use a self-signed certificate for your identity provider. -<8> `authentication.oidc.redirectUrl`: The URL where the identity provider redirects users after successful authentication. 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]. -<9> `authentication.oidc.accessType`: Controls whether a refresh token is requested. You can set it to `offline` (default) to request a refresh token for long-lived sessions. Set it to `online` if you don't want a refresh token. -<10> `authentication.oidc.prompt`: 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. +<1> Required. Secret key for signing JWTs. Must be at least 32 characters. Store securely. +<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. +<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. -Here is an example configuration for **static token mode**: +==== Enable static token mode [,yaml] ---- @@ -146,154 +131,184 @@ authentication: oidc: enabled: true issuerUrl: "https://accounts.google.com" - token: "" <1> + token: "" # <1> issuerTls: enabled: true caFilepath: "/path/to/ca.pem" - certFilepath: "/path/to/issuer-cert.pem" - keyFilepath: "/path/to/issuer-key.pem" - insecureSkipTlsVerify: false redirectUrl: "http://localhost:8080/auth/callbacks/oidc" accessType: "offline" prompt: "consent" ---- -<1> `authentication.oidc.token`: In static token mode, the `token` field supplies a pre-acquired OIDC token. This token is used to authenticate with the OIDC provider. Keep this token secret to ensure the integrity and security of user sessions. +<1> A pre-acquired OIDC token. Keep this secure. + +==== Supported identity providers + +You can use any OIDC-compliant IdP with Redpanda Console. Here are common providers: + +[cols="1,3"] +|=== +| Provider | Example `issuerUrl` + +| Google +| `\https://accounts.google.com` + +| Okta +| `\https:///oauth2/default` + +| Microsoft Entra ID (Azure AD) +| `\https://login.microsoftonline.com//v2.0` + +| Keycloak +| `\https:///realms/` + +| GitHub (Enterprise) +| `\https://github.com/login/oauth` +|=== + +For example, this is how to configure Redpanda Console with Entra ID: + +[,yaml] +---- +authentication: + jwtSigningKey: vazxnT+ZHtxKslK6QlDGovcYnSjTk/lKMmZ+mHrBVE+YdVDkLgSuP6AszAKe9Gvq + basic: + enabled: true + oidc: + enabled: true + issuerUrl: "https://login.microsoftonline.com//v2.0" + clientId: "" + clientSecret: "" + redirectUrl: "http://localhost:8080/auth/callbacks/oidc" + accessType: "offline" + prompt: "consent" + additionalScopes: + - "api:///entraid.v2-access-tokens" <1> +---- + +<1> In Entra ID, scopes are required to explicitly request OAuth 2.0-compliant access tokens. See https://learn.microsoft.com/en-us/azure/active-directory/develop/quickstart-configure-app-expose-web-apis[Microsoft documentation^] for more information. -Then, <> for specific APIs. +==== Connect clients to Redpanda + +When using OIDC, clients authenticate to Redpanda using OAuth 2.0 access tokens (JWTs). These tokens are issued by your identity provider (IdP) and must be refreshed before they expire. Token refresh can be handled in different ways depending on the Kafka client library. For example, with https://kafka.js.org/docs/configuration#oauthbearer-example[KafkaJS^], use the `oauthBearerProvider` option to provide a token refresh function. === Enable basic authentication -To enable basic authentication, configure your authentication settings in the Redpanda Console configuration file. +To configure basic authentication: -[, yaml] +[,yaml] ---- authentication: - jwtSigningKey: <1> - useSecureCookies: false <2> - # Basic auth logins are mapped to SASL-SCRAM for Kafka. + jwtSigningKey: "" # <1> + useSecureCookies: true # <2> basic: - enabled: true <3> + enabled: true # <3> ---- -<1> `authentication.jwtSigningKey` (required): The secret key for signing JWTs. Keep it confidential. Minimum 32 characters. Use xref:console:config/configure-console.adoc#environment-variables[environment variables] or command-line flags for sensitive data. -<2> `authentication.useSecureCookies`: A boolean flag indicating whether the JWT cookie should be marked as secure. Set to true in production to enforce HTTPS. -<3> `authentication.basic.enabled` (required): Enables or disables basic (username/password) authentication. When enabled, credentials are mapped to SASL-SCRAM for Kafka. -Then, <> for specific APIs. +<1> Required. Secret key for JWTs. Must be at least 32 characters. +<2> Recommended in production. Marks cookies as secure. +<3> Required. Enables username/password login. -[[api-authentication]] -== Configure API authentication +==== Connect clients to Redpanda -After you <> for Redpanda Console, you must configure how Redpanda Console authenticates to the following APIs in your Redpanda cluster: +When using basic authentication, clients authenticate to Redpanda using a SASL/SCRAM username and password. The credentials must match a user configured in the Redpanda cluster. -* **Kafka API:** Enables core messaging operations and authenticates requests to your Kafka cluster. -* **Schema Registry API:** Allows Redpanda Console to manage and display schema information. -* **Admin API:** Unlocks management features such as viewing cluster details, managing users, and generating debug bundles. +Most Kafka client libraries support SASL/SCRAM out of the box. You must configure the client with: -Choose one of the following authentication methods for each API: +- `sasl.mechanism`: One of `SCRAM-SHA-256` or `SCRAM-SHA-512` +- `sasl.username`: The Redpanda username +- `sasl.password`: The corresponding password -* **User impersonation:** - Redpanda Console uses the same credentials you use to log into Redpanda Console to authenticate API requests to Redpanda. This authentication method ensures accurate audit trails in xref:manage:audit-logging.adoc[Redpanda audit logs] and unified authorization across both Redpanda and Redpanda Console. Your credentials authenticate with any <>. - + - In this mode, Redpanda Console's role-based access control (RBAC) is bypassed for the impersonated API calls. +== Configure API authentication -* **Static credentials:** - Use preconfigured credentials to authenticate to Redpanda and use role bindings for access control in Redpanda Console. This authentication method is useful when impersonation is disabled or when you need to separate Redpanda Console RBAC from the logged-in user's identity in Redpanda. +You must configure how Redpanda Console authenticates to each Redpanda API: Kafka, Admin, and Schema Registry. -=== Kafka API +Choose one method per API: -When user impersonation is enabled, the logged-in user's credentials are used for authentication. +* **User impersonation:** Uses the login credentials of the current user. +* **Static credentials:** Uses preconfigured credentials and role bindings. -User impersonation example: +=== Kafka API examples -[source,yaml] +.User impersonation +[,yaml] ---- kafka: - brokers: ["broker1.example.com:9092"] + brokers: ["broker1:9092"] sasl: enabled: true - impersonateUser: true <1> -authentication: <2> - jwtSigningKey: "secret-key" - basic: - enabled: true + impersonateUser: true ---- -<1> `kafka.sasl.impersonateUser`: When set to `true`, Redpanda Console impersonates the user who is logged in when making requests to the Kafka API. -<2> `authentication`: Enables users to log into Redpanda Console using basic authentication. You could also enable OIDC for login. - -When impersonation is disabled, you must supply static credentials and role bindings to define the access permissions. - -NOTE: Redanda Console still authenticates to the Kafka API using the logged-in user's credentials. The static credentials are used only for authenticating Kafka API calls after the user is logged in. - -Static credentials example: +.Static credentials with SCRAM [,yaml] ---- kafka: - brokers: ["broker1.example.com:9092"] + brokers: ["broker1:9092"] sasl: enabled: true - impersonateUser: false <1> - username: "static-kafka-user" <2> - password: "static-kafka-pass" <3> - mechanism: "SCRAM-SHA-256" <4> -authentication: - jwtSigningKey: "secret-key" - basic: - enabled: true + impersonateUser: false + username: "static-kafka-user" + password: "static-pass" + mechanism: "SCRAM-SHA-256" authorization: - roleBindings: <5> + roleBindings: - roleName: viewer users: - loginType: basic name: "static-kafka-user" ---- -<1> `kafka.sasl.impersonateUser`: When set to `false`, Redpanda Console does not impersonate the user who is logged in when making requests to the Kafka API. -<2> `kafka.sasl.username`: Specifies the static Kafka username. -<3> `kafka.sasl.password`: Specifies the static Kafka password. Use xref:console:config/configure-console.adoc#environment-variables[environment variables] or command-line flags for sensitive data. -<4> `kafka.sasl.mechanism`: Specifies the SASL mechanism to use for authentication. Use `SCRAM-SHA-256` or `SCRAM-SHA-512`. -<5> `authorization.roleBindings`: Defines the role bindings that grant permissions to users. -+ -The role binding in the configuration does not need to match the static Kafka user. In practice, most users log in using their own identity, not the static Kafka credentials. The static credentials are used only for authenticating Kafka API calls when impersonation is disabled, while role bindings govern access within Redpanda Console. This separation allows you to use a generic Kafka identity (`static-kafka-user`) without tying it to the individual login identities that benefit from personalized role-based permissions. -+ -For more information on role bindings, see xref:console:config/security/authorization.adoc[]. -=== Schema Registry API +.Static credentials with OIDC +[,yaml] +---- +kafka: + brokers: ["broker1:9092"] + sasl: + enabled: true + impersonateUser: false + mechanism: OAUTHBEARER + oauth: + clientId: "" + clientSecret: "" + tokenEndpoint: "https://login.microsoftonline.com//oauth2/v2.0/token" + scope: "api:///.default" +authorization: + roleBindings: + - roleName: viewer + users: + - loginType: oidc + name: "" # such as "ae775e64-xxxx-xxxx-xxxx-xxxxxxxxxxxx" +---- -With impersonation enabled, the Schema Registry API uses the logged-in user's credentials. +[NOTE] +==== +When using OIDC without impersonation, Redpanda Console authenticates to Redpanda as the OIDC client itself (usually a service principal). In this case, Redpanda evaluates access based on the `sub` claim in the token. Be sure to set `oidc_principal_mapping: "$.sub"` in your Redpanda configuration and grant ACLs for that value. For detailed steps to create ACLs, see xref:manage:security/authorization/acl.adoc[] +==== -User impersonation example: +=== Schema Registry API examples -[source,yaml] +.User impersonation +[,yaml] ---- schemaRegistry: - urls: ["http://broker1.example.com:8081"] + urls: ["http://broker1:8081"] authentication: enabled: true impersonateUser: true -authentication: - jwtSigningKey: "secret-key" - basic: - enabled: true ---- -When impersonation is disabled and the Schema Registry API in Redpanda requires authentication, you must supply static credentials and role bindings to define the access permissions. - -Static credentials example: - -[source,yaml] +.Static credentials with basic auth +[,yaml] ---- schemaRegistry: - urls: ["http://broker1.example.com:8081"] + urls: ["http://broker1:8081"] authentication: enabled: true impersonateUser: false - username: "static-sr-user" - password: "static-sr-pass" -authentication: - jwtSigningKey: "secret-key" - basic: - enabled: true + basic: + username: "static-sr-user" + password: "static-sr-pass" authorization: roleBindings: - roleName: editor @@ -302,49 +317,53 @@ authorization: name: "static-sr-user" ---- -Use xref:console:config/configure-console.adoc#environment-variables[environment variables] or command-line flags for sensitive data. - -For more information on role bindings, see xref:console:config/security/authorization.adoc[]. - -=== Admin API +.Static credentials with OIDC bearer token +[,yaml] +---- +schemaRegistry: + urls: ["http://broker1:8081"] + authentication: + enabled: true + impersonateUser: false + bearerToken: "" +authorization: + roleBindings: + - roleName: editor + users: + - loginType: oidc + name: "" +---- -When impersonation is enabled, Admin API calls are made using the logged-in user's credentials. +[NOTE] +==== +You can supply a static bearer token here, but this token must be refreshed manually before it expires. For automatic token acquisition, configure a background token refresher or consider using impersonation where possible. +==== -User impersonation example: +=== Admin API examples -[source,yaml] +.User impersonation +[,yaml] ---- redpanda: adminApi: enabled: true - urls: ["http://broker1.example.com:9644"] + urls: ["http://broker1:9644"] authentication: impersonateUser: true -authentication: - jwtSigningKey: "secret-key" - basic: - enabled: true ---- -When impersonation is disabled and the Admin API in Redpanda requires authentication, you must supply static credentials and role bindings to define the access permissions. - -Static credentials example: - -[source,yaml] +.Static credentials with basic auth +[,yaml] ---- redpanda: adminApi: enabled: true - urls: ["http://broker1.example.com:9644"] + urls: ["http://broker1:9644"] authentication: impersonateUser: false basic: username: "static-admin-user" password: "static-admin-pass" -authentication: - jwtSigningKey: "secret-key" - basic: - enabled: true authorization: roleBindings: - roleName: admin @@ -353,11 +372,30 @@ authorization: name: "static-admin-user" ---- -Use xref:console:config/configure-console.adoc#environment-variables[environment variables] or command-line flags for sensitive data. +.Static credentials with OIDC bearer token +[,yaml] +---- +redpanda: + adminApi: + enabled: true + urls: ["http://broker1:9644"] + authentication: + impersonateUser: false + bearerToken: "" +authorization: + roleBindings: + - roleName: admin + users: + - loginType: oidc + name: "" +---- -For more information on role bindings, see xref:console:config/security/authorization.adoc[]. +[NOTE] +==== +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. +==== == Next steps -- xref:console:config/security/authorization.adoc[Redpanda Console Authorization] - +- xref:console:config/security/authorization.adoc[Configure role-based access control (RBAC) in Redpanda Console] +- xref:manage:security/authentication.adoc[Configure authentication for Redpanda APIs] diff --git a/modules/console/pages/config/security/authorization.adoc b/modules/console/pages/config/security/authorization.adoc index 6b1d19276b..afc7f6b24f 100644 --- a/modules/console/pages/config/security/authorization.adoc +++ b/modules/console/pages/config/security/authorization.adoc @@ -2,20 +2,37 @@ :description: Redpanda Console uses role-based access control (RBAC) to restrict system access to authorized users. :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 -Redpanda Console uses role-based access control (RBAC) to manage and restrict access to features in the user interface. RBAC allows you to control access to different resources in Redpanda Console by binding roles (admin, editor, viewer) to users. These role bindings determine the permissions that users have when interacting with Redpanda Console. - [NOTE] ==== include::shared:partial$enterprise-and-console.adoc[] ==== -RBAC behavior depends on your authentication configuration in Redpanda Console. When using static credentials, you must give users permissions to use Redpanda Console by defining RBAC rules in the Redpanda Console configuration file. If authentication for an API is configured to impersonate users, Redpanda Console RBAC rules are ignored for that API and permissions are derived only from the roles assigned in Redpanda. For more information, see the xref:console:config/security/authentication.adoc[]. +Redpanda Console supports two authorization modes, depending on whether *user impersonation* is enabled in the authentication configuration: + +[cols="1,2", options="header"] +|=== +| Mode | Who evaluates permissions? + +| **Impersonation enabled** (`impersonateUser: true`) +| Redpanda authorizes requests based on internal RBAC and ACLs. +`roleBindings` in the Console config are ignored. + +| **Impersonation disabled** (`impersonateUser: false`) +| Redpanda Console enforces access using static `roleBindings` from the configuration file. +Redpanda treats all requests as coming from a single service account. +|=== + +Even when using Redpanda Console roles, users must still have ACLs in Redpanda if they are interacting with Redpanda through the UI. + +For more information about authentication options, see the xref:console:config/security/authentication.adoc[authentication configuration]. == Roles -Roles defined in Redpanda Console are separate from roles in Redpanda. Roles in Redpanda Console control what a user can see and do within the Console interface and only apply to endpoints where user impersonation is disabled. For example, while an admin user in Redpanda Console can generate debug bundles, the user must also have the corresponding `MANAGE_DEBUG_BUNDLE` ACL in Redpanda to execute the operation. +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. + +Redpanda Console provides the following predefined roles: [cols="1a,3a,3a", options="header"] |=== @@ -27,7 +44,7 @@ Redpanda Console comes with the following roles: * View consumer group data (consumer groups, group offsets, lags) * View Schema Registry data (registered schemas with contents) * View Kafka Connect data (configured clusters, connectors including status and configs) -| Does not include permission to view the list of users +| Cannot view the list of users | Editor | Inherits all Viewer permissions, plus: @@ -36,25 +53,26 @@ Redpanda Console comes with the following roles: * Manage cluster configurations (edit node or cluster settings) * Manage consumer groups (edit or delete group offsets) * Manage Kafka Connect (create, update, delete, start, pause, or stop connectors) -| Does not include permission to create/remove ACLs or to create/remove service accounts +| Cannot create or remove ACLs or service accounts | Admin | Inherits all Editor permissions, plus: * View and manage all users and ACLs * xref:console:ui/generate-bundle.adoc[Generate debug bundles] -| None +| No limitations |=== -NOTE: Redpanda Console roles do not appear in the *Roles* tab on the Security page. This page displays only the roles defined in Redpanda. +[NOTE] +==== +Redpanda Console roles are not visible in the *Roles* tab on the Security page. That section displays only roles managed by Redpanda. +==== == Grant permissions through role bindings -To grant users the permissions defined in a role, you must bind the role to a non-impersonated user. Each role binding defines the role being granted and a list of users to assign that role. +To assign roles when impersonation is disabled, define `roleBindings` in the Redpanda Console configuration. Each binding associates one or more users with a specific role. -For example, this role binding gives the Admin role to the Google account `john.doe@redpanda.com` and the Viewer role to the user `Alice`: - -.Example role bindings +.Example: Assign the Viewer role to a user [,yaml] ---- kafka: @@ -62,35 +80,28 @@ kafka: sasl: enabled: true impersonateUser: false <1> -authentication: <2> - jwtSigningKey: secret-key - useSecureCookies: false - oidc: - enabled: true - issuerUrl: https://accounts.google.com - clientId: "example-client-id" - clientSecret: "example-client-secret" - redirectUrl: http://localhost:9090/auth/callbacks/oidc - basic: - enabled: true <2> -authorization: <3> - roleBindings: - - roleName: admin - users: - - loginType: OIDC - name: john.doe@redpanda.com # Refers to the sub claim in the JWT token + username: "static-kafka-user" + password: "static-pass" + mechanism: "SCRAM-SHA-256" +authorization: + roleBindings: <2> - roleName: viewer users: - loginType: basic - name: Alice # Refers to the SASL/SCRAM username for the Kafka API or the basic auth username for the HTTP APIs. + name: static-kafka-user ---- -<1> The `impersonateUser` flag is set to `false`, which means Redpanda Console does not impersonate the user who is logged in when making requests to the Kafka API. -<2> The `authentication` block enables users to log into Redpanda Console using OIDC or basic authentication. -<3> The `authorization` block defines the role bindings that grant permissions to users. If this user logs into Redpanda Console as either `john.doe@redpanda.com` or Alice, they will have the permissions of an Admin or Viewer, respectively. +<1> User impersonation is disabled, so role bindings are used for authorization. +<2> The roleBindings section maps users to roles using their login type and username. + +== When impersonation is enabled -If the user is impersonated, like in the following example, the role binding is ignored, and the user's permissions are determined by the roles assigned to them in Redpanda: +When impersonation is enabled, Redpanda Console does not evaluate any role bindings defined in the configuration. Instead, the user identity is forwarded to Redpanda, and Redpanda authorizes the request based on its own RBAC rules and access control lists (ACLs). To access Redpanda Console in this mode, the user must be registered in Redpanda and have ACLs that permit access to the Kafka API. Without these permissions, the user cannot successfully log into Redpanda Console. -.Role bindings ignored +To access all functionality in Redpanda Console, such as generating debug bundles, the user must also have superuser permissions assigned in Redpanda. + +For detailed steps to create ACLs, see xref:manage:security/authorization/acl.adoc[]. + +.Example: Role bindings ignored when impersonating users [,yaml] ---- kafka: @@ -98,48 +109,46 @@ kafka: sasl: enabled: true impersonateUser: true <1> -authentication: <2> +authentication: jwtSigningKey: secret-key useSecureCookies: false basic: enabled: true <2> -# Role bindings are ignored because the user is impersonated for the Kafka API. authorization: roleBindings: - roleName: admin users: - loginType: basic - name: name: Peter <3> + name: Peter <3> ---- +<1> User impersonation is enabled for Kafka API requests. +<2> Users authenticate with basic authentication. +<3> This role binding has no effect because Redpanda authorizes the request. -<1> The `impersonateUser` flag is set to `true`, which means Redpanda Console impersonates the user who is logged in when making requests to the Kafka API. -<2> The `authentication` block enables users to log into Redpanda Console using basic authentication. -<3> The role binding is ignored because the user is impersonated for the Kafka API. +== Multiple roles and duplicate bindings -[[union]] -=== Multiple roles and duplicate role 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. -Redpanda Console allows you to assign multiple roles to users through role bindings. When a user is associated with more than one role, the user is granted all the permissions defined in each role they are assigned. - -For example, if a user is assigned both the `viewer` and `editor` roles, they will have all the permissions of a `viewer` as well as the additional permissions of an `editor`. Here is an example of a role binding that assigns both the `viewer` and `editor` roles to the user `john.doe@redpanda.com`: +For example, if a user is assigned both `viewer` and `editor`, they can perform all actions granted to each role. +.Example: User with multiple role assignments [,yaml] ---- authorization: roleBindings: - - roleName: admin + - roleName: viewer users: - loginType: OIDC name: john.doe@redpanda.com - - roleName: viewer + - roleName: editor users: - loginType: OIDC name: john.doe@redpanda.com ---- -Duplicate role bindings do not cause errors or conflicts. If a user is assigned the same role multiple times through role bindings, the duplicate role bindings do not affect the user's final set of permissions, which are the same as if the role was assigned once. +Duplicate role assignments do not cause errors. If the same role is assigned more than once to a user, the user receives the permissions only once. == Suggested reading -* xref:console:config/configure-console.adoc[Redpanda Console configuration guide] * xref:manage:security/authorization/rbac.adoc[Redpanda RBAC] + diff --git a/modules/manage/pages/console/index.adoc b/modules/manage/pages/console/index.adoc index 4dfa3812c5..e1386e507f 100644 --- a/modules/manage/pages/console/index.adoc +++ b/modules/manage/pages/console/index.adoc @@ -1,4 +1,5 @@ = Redpanda Console :description: Learn how to manage Redpanda using Redpanda Console. :page-layout: index +:page-aliases: console:config/index.adoc diff --git a/modules/manage/partials/authentication.adoc b/modules/manage/partials/authentication.adoc index 290c0814b2..bcbc153ce3 100644 --- a/modules/manage/partials/authentication.adoc +++ b/modules/manage/partials/authentication.adoc @@ -819,7 +819,7 @@ but can instead rely on the trusted authentication capabilities of established I Redpanda's implementation of OIDC provides SASL/OAUTHBEARER support for the Kafka API, and supports standard OIDC authentication across all other HTTP APIs, including Schema Registry, HTTP Proxy, and the Admin API. -NOTE: OIDC is not supported by `rpk` or Redpanda Cloud. While `rpk` does not support OIDC, it does support configuring Redpanda with OIDC as a SASL mechanism. +include::manage:partial$security/oidc/limitations.adoc[leveloffset=+3] ===== OIDC credentials flow and access token validation diff --git a/modules/manage/partials/security/oidc/limitations.adoc b/modules/manage/partials/security/oidc/limitations.adoc new file mode 100644 index 0000000000..79b2697cdd --- /dev/null +++ b/modules/manage/partials/security/oidc/limitations.adoc @@ -0,0 +1,10 @@ +== OIDC limitations + +* `rpk` does not support OIDC login yet. +* Redpanda Console uses `sub` by default unless overridden. +* Assigning roles to OIDC principals is only supported through `rpk`. Redpanda Console does not yet support assigning roles to OIDC principals. +* Access to the Admin API is only possible if the OIDC principal is set as a +superuser in your Redpanda configuration. Redpanda does not yet support granular +authorization enforcement for the Admin API. +* Data transforms can only be deployed using SASL/SCRAM users because `rpk` does not yet +support using the `SASL/OAUTHBEARER` mechanism. \ No newline at end of file From ec0103b203bb85c9ff305c29b7895a765ed4db46 Mon Sep 17 00:00:00 2001 From: JakeSCahill Date: Wed, 7 May 2025 17:43:23 +0100 Subject: [PATCH 03/24] Fix typos --- .github/workflows/test-docs.yml | 2 ++ modules/console/pages/config/security/authorization.adoc | 6 +++--- modules/migrate/pages/console-v3.adoc | 2 +- 3 files changed, 6 insertions(+), 4 deletions(-) diff --git a/.github/workflows/test-docs.yml b/.github/workflows/test-docs.yml index 24f92ce2c0..ce2a160c0f 100644 --- a/.github/workflows/test-docs.yml +++ b/.github/workflows/test-docs.yml @@ -59,6 +59,7 @@ jobs: uses: doc-detective/github-action@v1 with: input: ../../modules + version: 2.19.1 working_directory: redpanda-docs/tests/setup-tests exit_on_fail: true # create a PR/issue only if the workflow wasn't already triggered by a PR @@ -70,6 +71,7 @@ jobs: if: ${{ needs.setup.outputs.quickstart == 'true' || needs.setup.outputs.console == 'true' }} uses: doc-detective/github-action@v1 with: + version: 2.19.1 input: ../../modules/get-started/pages/quick-start.adoc working_directory: redpanda-docs/tests/setup-tests exit_on_fail: true diff --git a/modules/console/pages/config/security/authorization.adoc b/modules/console/pages/config/security/authorization.adoc index afc7f6b24f..83948aabcf 100644 --- a/modules/console/pages/config/security/authorization.adoc +++ b/modules/console/pages/config/security/authorization.adoc @@ -9,13 +9,13 @@ include::shared:partial$enterprise-and-console.adoc[] Redpanda Console supports two authorization modes, depending on whether *user impersonation* is enabled in the authentication configuration: -[cols="1,2", options="header"] +[cols="1,2"] |=== -| Mode | Who evaluates permissions? +| Mode | Who Evaluates Permissions? | **Impersonation enabled** (`impersonateUser: true`) | Redpanda authorizes requests based on internal RBAC and ACLs. -`roleBindings` in the Console config are ignored. +`roleBindings` in the Redpanda Console configuration are ignored. | **Impersonation disabled** (`impersonateUser: false`) | Redpanda Console enforces access using static `roleBindings` from the configuration file. diff --git a/modules/migrate/pages/console-v3.adoc b/modules/migrate/pages/console-v3.adoc index 2a0a44772b..f07eecb71c 100644 --- a/modules/migrate/pages/console-v3.adoc +++ b/modules/migrate/pages/console-v3.adoc @@ -255,7 +255,7 @@ rpk cluster config set superusers "['alice@example.com']" | `read`, `write`, `describe` on topics and `describe` on groups | Admin -| All of the above, plus `superuser` role using the cluster configuation +| All of the above, plus `superuser` role using the cluster configuration |=== For details, see: From 666006df59818a0975fcf6352c6471a7c801c14e Mon Sep 17 00:00:00 2001 From: Jake Cahill <45230295+JakeSCahill@users.noreply.github.com> Date: Wed, 7 May 2025 18:36:18 +0100 Subject: [PATCH 04/24] Update nav.adoc --- modules/ROOT/nav.adoc | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index 66e055d5d3..30f1c02b4c 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -89,18 +89,6 @@ *** xref:deploy:deployment-option/self-hosted/manual/sizing.adoc[Sizing Guidelines] *** xref:deploy:deployment-option/self-hosted/manual/linux-system-tuning.adoc[System Tuning] ** xref:deploy:deployment-option/self-hosted/docker-image.adoc[Connectors] -* xref:upgrade:index.adoc[Upgrade] -** xref:upgrade:rolling-upgrade.adoc[Upgrade Redpanda in Linux] -** xref:upgrade:k-rolling-upgrade.adoc[Upgrade Redpanda in Kubernetes] -** xref:upgrade:k-upgrade-operator.adoc[Upgrade the Redpanda Operator] -** xref:upgrade:k-compatibility.adoc[] -** xref:manage:kubernetes/k-upgrade-kubernetes.adoc[Migrate Node Pools] -** xref:upgrade:deprecated/index.adoc[Deprecated Features] -* xref:migrate:index.adoc[Migrate] -** xref:migrate:console-v3.adoc[Migrate to Redpanda Console v3.0.x] -** xref:migrate:data-migration.adoc[] -** xref:migrate:kubernetes/helm-to-operator.adoc[] -** xref:migrate:kubernetes/strimzi.adoc[] * xref:manage:index.adoc[Manage] ** xref:manage:kubernetes/index.adoc[Kubernetes] *** xref:manage:kubernetes/k-configure-helm-chart.adoc[Customize the Helm Chart] @@ -212,6 +200,18 @@ ** xref:manage:monitoring.adoc[] ** xref:manage:io-optimization.adoc[] ** xref:manage:raft-group-reconfiguration.adoc[Raft Group Reconfiguration] +* xref:upgrade:index.adoc[Upgrade] +** xref:upgrade:rolling-upgrade.adoc[Upgrade Redpanda in Linux] +** xref:upgrade:k-rolling-upgrade.adoc[Upgrade Redpanda in Kubernetes] +** xref:upgrade:k-upgrade-operator.adoc[Upgrade the Redpanda Operator] +** xref:upgrade:k-compatibility.adoc[] +** xref:manage:kubernetes/k-upgrade-kubernetes.adoc[Migrate Node Pools] +** xref:upgrade:deprecated/index.adoc[Deprecated Features] +* xref:migrate:index.adoc[Migrate] +** xref:migrate:console-v3.adoc[Migrate to Redpanda Console v3.0.x] +** xref:migrate:data-migration.adoc[] +** xref:migrate:kubernetes/helm-to-operator.adoc[] +** xref:migrate:kubernetes/strimzi.adoc[] * xref:troubleshoot:index.adoc[Troubleshoot] ** xref:troubleshoot:cluster-diagnostics/index.adoc[Cluster Diagnostics] *** xref:troubleshoot:cluster-diagnostics/diagnose-issues.adoc[Linux] From a7a957bb47216a52d9f7dddcf676cd1bc1aae244 Mon Sep 17 00:00:00 2001 From: JakeSCahill Date: Mon, 12 May 2025 15:49:53 +0100 Subject: [PATCH 05/24] Improve HTTP APIs authentication documentation --- modules/manage/partials/authentication.adoc | 116 +++++++++++++++++--- 1 file changed, 102 insertions(+), 14 deletions(-) diff --git a/modules/manage/partials/authentication.adoc b/modules/manage/partials/authentication.adoc index bcbc153ce3..c3123e2a6c 100644 --- a/modules/manage/partials/authentication.adoc +++ b/modules/manage/partials/authentication.adoc @@ -1295,23 +1295,111 @@ endif::[] == Authentication for the HTTP APIs -The following HTTP APIs support basic authentication and OIDC authentication: +Redpanda provides three HTTP APIs that support authentication: -- Admin API -- Schema Registry -- HTTP Proxy +- Admin API: Management and monitoring of the Redpanda cluster +- Schema Registry API: Management of schemas and schema evolution +- HTTP Proxy API: RESTful interface for Kafka clients -=== Basic authentication +=== Permission models -Basic authentication provides a method for securing HTTP endpoints. With basic authentication enabled, HTTP user agents, such as web browsers, must provide a username and password when making a request. +Each of the HTTP APIs implements its own permission model with different levels of access control. This section lists what permissions are available to different user types, and how to enable authentication. + +==== Admin API permissions + +The Admin API primarily requires superuser privileges, with a few exceptions for read-only status endpoints. + +[cols="3,1,1"] +|=== +|API Category / Operation |Regular Authenticated User |Superuser +|*Authentication* +| +| + +|Verify identity of current user +|✅ +|✅ + +|Reload keys from identity provider +|❌ +|✅ + +|Reload keys and disconnect clients +|❌ +|✅ + +|*Recovery status* +| +| + +|Get Raft recovery status +|✅ +|✅ + +|Get transaction manager migration status +|✅ +|✅ + +|*All other Admin API operations* +|❌ +|✅ +|=== -Before you can enable basic authentication for these HTTP APIs, you must <>. Then, both SCRAM users and superusers can use their credentials to access them: +For a complete list of all Admin API endpoints, see see xref:api:ROOT:admin-api.adoc[]. -* *HTTP Proxy*: Access to the Kafka API impersonates the user whose credentials were used to authenticate to HTTP Proxy, and the user is subject to authorization restrictions by Redpanda ACLs. To support this design, Redpanda passes the username/password in memory to a SASL-enabled Kafka client. -* *Schema Registry*: Authorization is "all or nothing": if the user presents a valid user account, then they have full read/write access. +==== Schema Registry API permissions + +The Schema Registry implements a granular permission model. + +Most read operations require only user-level authentication, while write operations that affect the global state or mode typically require superuser privileges. + +==== HTTP Proxy permissions + +The HTTP Proxy API impersonates the authenticated user when making Kafka API calls: + +[cols="3,1,1"] +|=== +|Operation |Regular Authenticated User |Superuser +|Get brokers +|❌ +|✅ + +|List topics +|❌ +|✅ + +|Produce to topic +|Subject to ACLs +|✅ + +|Fetch from topic +|Subject to ACLs +|✅ + +|Consumer operations +|Subject to ACLs +|✅ +|=== + +Regular users are subject to the same ACL restrictions as they would be when using the Kafka API directly. + +=== Enable authentication + +Redpanda supports authentication for the HTTP APIs using either basic authentication or OIDC (OpenID Connect). + +==== Prerequisites + +Before enabling authentication for the HTTP APIs, you must <>. This creates the credential store that HTTP authentication will use. + +==== Basic authentication + +Basic authentication provides a method for securing HTTP endpoints. With basic authentication enabled, HTTP user agents, such as web browsers, must provide a username and password when making a request. To add users to the Redpanda credential store that HTTP basic authentication uses, create users with xref:reference:rpk/rpk-acl/rpk-acl-user-create.adoc[`rpk security user create`]. +Both SCRAM users and superusers can use their credentials to access them. The HTTP Proxy API and the Schema Registry API use the same credential store as the Kafka API, so you can use the same credentials for all three APIs. +The Admin API uses the same credential store as the Kafka API, but it requires superuser credentials to access it. + ifdef::env-kubernetes[] When you <> in the Redpanda Helm chart, the Schema Registry API and the HTTP Proxy API are configured with basic authentication by default. @@ -1423,7 +1511,7 @@ schema_registry: ---- endif::[] -==== Connect to the HTTP API +===== Connect to the HTTP API ifdef::env-kubernetes[By default, the Redpanda Helm chart configures an internal and external listener for the HTTP Proxy API.] @@ -1463,7 +1551,7 @@ endif::[] For all available endpoints, see xref:api:ROOT:pandaproxy-rest.adoc[]. -==== Connect to the Schema Registry API +===== Connect to the Schema Registry API ifdef::env-kubernetes[By default, the Redpanda Helm chart configures an internal and external listener for the Schema Registry API.] @@ -1504,7 +1592,7 @@ endif::[] For all available endpoints, see xref:api:ROOT:pandaproxy-schema-registry.adoc[]. [[oidc-http]] -=== OIDC +==== OIDC You can configure the HTTP APIs to authenticate users with the OIDC bearer token. By using OIDC, you can centralize credentials and provide a password-free SSO experience. @@ -1615,7 +1703,7 @@ schema_registry: ---- endif::[] -==== Connect to the HTTP API +===== Connect to the HTTP API ifdef::env-kubernetes[By default, the Redpanda Helm chart configures an internal and external listener for the HTTP Proxy API.] @@ -1655,7 +1743,7 @@ endif::[] For all available endpoints, see xref:api:ROOT:pandaproxy-rest.adoc[]. -==== Connect to the Schema Registry API +===== Connect to the Schema Registry API ifdef::env-kubernetes[By default, the Redpanda Helm chart configures an internal and external listener for the Schema Registry API.] From eabb5f71c1fc9110240bcd092625d7a7790d0fc0 Mon Sep 17 00:00:00 2001 From: JakeSCahill Date: Mon, 12 May 2025 16:04:39 +0100 Subject: [PATCH 06/24] clarify limitations with Google OIDC and impersonation --- .../console/pages/config/security/authentication.adoc | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/modules/console/pages/config/security/authentication.adoc b/modules/console/pages/config/security/authentication.adoc index 271d756465..d000058dd0 100644 --- a/modules/console/pages/config/security/authentication.adoc +++ b/modules/console/pages/config/security/authentication.adoc @@ -39,6 +39,10 @@ Redpanda Console can authenticate to Redpanda APIs in two ways: Upon login, 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. +For OIDC-based login flows, Redpanda Console reuses the OAuth 2.0 access token from the identity provider (IdP) to authenticate to Redpanda's Kafka and HTTP APIs. These access tokens must be in JWT format to be compatible with Redpanda's SASL/OAUTHBEARER authentication. + +Some IdPs, such as Google, issue opaque access tokens that are not JWTs. While these tokens work for logging in to Redpanda Console (the ID token is a JWT), they cannot be used for impersonation with the Kafka API. In such cases, impersonation must be disabled, and Console must be configured to use static credentials instead. + [mermaid,width=450px] .... flowchart TD @@ -150,9 +154,6 @@ You can use any OIDC-compliant IdP with Redpanda Console. Here are common provid |=== | Provider | Example `issuerUrl` -| Google -| `\https://accounts.google.com` - | Okta | `\https:///oauth2/default` @@ -166,6 +167,8 @@ You can use any OIDC-compliant IdP with Redpanda Console. Here are common provid | `\https://github.com/login/oauth` |=== +Some IdPs, such as Google, issue opaque access tokens that are not JWTs. While these tokens work for logging in to Redpanda Console (the ID token is a JWT), they cannot be used for impersonation with the Kafka API. In such cases, impersonation must be disabled, and Console must be configured to use static credentials instead. + For example, this is how to configure Redpanda Console with Entra ID: [,yaml] From 85011e86acd20436a5d284d3580369ef0fac4d61 Mon Sep 17 00:00:00 2001 From: JakeSCahill Date: Mon, 12 May 2025 16:20:59 +0100 Subject: [PATCH 07/24] Clarify OIDC limitations and token requirements for Kafka API --- modules/manage/partials/authentication.adoc | 1 + .../partials/security/oidc/limitations.adoc | 18 ++++++++++-------- 2 files changed, 11 insertions(+), 8 deletions(-) diff --git a/modules/manage/partials/authentication.adoc b/modules/manage/partials/authentication.adoc index c3123e2a6c..3d9fb8abf0 100644 --- a/modules/manage/partials/authentication.adoc +++ b/modules/manage/partials/authentication.adoc @@ -813,6 +813,7 @@ To upgrade, contact https://redpanda.com/try-redpanda?section=enterprise-trial[R When you enable https://openid.net/developers/how-connect-works/[OIDC^], Redpanda and Redpanda Console can delegate the authentication process to an external identity provider (IdP) such as Okta, Microsoft Entra ID, or on-premise Active Directory Federation Service (AD FS). + With OIDC enabled, Redpanda does not need to manage user credentials directly, but can instead rely on the trusted authentication capabilities of established IdPs. diff --git a/modules/manage/partials/security/oidc/limitations.adoc b/modules/manage/partials/security/oidc/limitations.adoc index 79b2697cdd..8c8926378c 100644 --- a/modules/manage/partials/security/oidc/limitations.adoc +++ b/modules/manage/partials/security/oidc/limitations.adoc @@ -1,10 +1,12 @@ == OIDC limitations -* `rpk` does not support OIDC login yet. -* Redpanda Console uses `sub` by default unless overridden. -* Assigning roles to OIDC principals is only supported through `rpk`. Redpanda Console does not yet support assigning roles to OIDC principals. -* Access to the Admin API is only possible if the OIDC principal is set as a -superuser in your Redpanda configuration. Redpanda does not yet support granular -authorization enforcement for the Admin API. -* Data transforms can only be deployed using SASL/SCRAM users because `rpk` does not yet -support using the `SASL/OAUTHBEARER` mechanism. \ No newline at end of file +- Redpanda requires JWT-formatted access tokens (not ID tokens) for Kafka API authentication using SASL/OAUTHBEARER. Access tokens issued by some IdPs, such as Google, are opaque and not supported. + +- The `rpk` CLI does not support OIDC login. + +- Redpanda Console cannot assign roles to OIDC principals. Roles must be assigned through `rpk`. + +- Redpanda requires OIDC principals to be set as superusers to access the Admin API. Granular authorization is not yet supported. + +- The `rpk` CLI does not support the SASL/OAUTHBEARER mechanism for deploying data transforms. Use SASL/SCRAM instead. + From 2a844ad2612687f10ee7211ecefca3c4fcf924ea Mon Sep 17 00:00:00 2001 From: JakeSCahill Date: Mon, 12 May 2025 16:22:06 +0100 Subject: [PATCH 08/24] Increase screenshot variation --- modules/get-started/pages/quick-start.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/get-started/pages/quick-start.adoc b/modules/get-started/pages/quick-start.adoc index 93ad59034c..bd18f650fb 100644 --- a/modules/get-started/pages/quick-start.adoc +++ b/modules/get-started/pages/quick-start.adoc @@ -173,7 +173,7 @@ To view details about a specific broker, click *View* at the end of the row in t // (step {"action":"find", "selector": ".chakra-table tbody tr:last-child td:last-child button", "matchText": "View", "click": true}) // (step {"action":"wait", "duration": 15000}) -// (step {"action":"saveScreenshot", "path": "broker-overview.png", "directory": "../../modules/console/images", "overwrite": "byVariation"}) +// (step {"action":"saveScreenshot", "path": "broker-overview.png", "directory": "../../modules/console/images", "overwrite": "byVariation", "maxVariation": 10}) image::console:broker-overview.png[] From b42dfcccafc982dad95dbe6dd7fed0ba14477022 Mon Sep 17 00:00:00 2001 From: JakeSCahill Date: Wed, 14 May 2025 10:55:07 +0100 Subject: [PATCH 09/24] Explain users vs principals and update admin API table --- modules/manage/partials/authentication.adoc | 90 ++++++++++++++------- 1 file changed, 60 insertions(+), 30 deletions(-) diff --git a/modules/manage/partials/authentication.adoc b/modules/manage/partials/authentication.adoc index 3d9fb8abf0..1e57cac227 100644 --- a/modules/manage/partials/authentication.adoc +++ b/modules/manage/partials/authentication.adoc @@ -34,6 +34,37 @@ ifndef::env-kubernetes[- mTLS] - OIDC |=== +== Users, principals, and superusers + +When you configure authentication and authorization in Redpanda, it's important to understand the distinction between *users*, *principals*, and *superusers*: + +- A user refers to a stored credential within Redpanda, typically a username/password stored in the internal SASL credential store. These are created using commands such as `rpk security user create`. + +- A principal is the authenticated identity string associated with a client session. It's what Redpanda uses for access control, ACLs, and superuser assignment. + +- A superuser is a privileged principal that has unrestricted access to xref:manage:security/authorization/index.adoc#operations[all operations] in a Redpanda cluster. + +Superusers can: + +- Grant or revoke permissions to other users through ACLs. +- Access all Admin API endpoints. +- Create, modify, or delete topics and consumer groups. +- View and manage the cluster's internal state. + +Depending on how a client authenticates, the principal might be: + +- The SCRAM username +- A claim from a JWT +- A certificate DN +- A Kerberos identity + +You assign ACLs and superuser roles to principals, not users. Even if a user exists, it has no access unless its associated principal is granted permissions. + +For example, with OIDC: + +- If your token's `sub` claim is `example@company.com`, then your principal is `user:OIDC:example@company.com`. +- This value must appear in the `superusers` list or ACL rules to have access. + ifdef::env-kubernetes[] == Prerequisites @@ -61,9 +92,7 @@ When you enable authentication in the Redpanda Helm chart: - Basic authentication is enabled for the HTTP Proxy and Schema Registry listeners - Authorization is enabled -When enabling authentication, you must create at least one superuser. A superuser is a special user that has xref:manage:security/authorization/index.adoc#operations[all permissions] in the cluster. They can grant permissions to other users through access control lists (ACLs). - -Without a superuser, you can create other users, but you can't grant them permissions to the cluster. +When enabling authentication, you must create at least one superuser. Without a superuser, you can create other users, but you can't grant them permissions to the cluster. CAUTION: Do not enable authorization without a superuser. Without a superuser, you may be locked out of the cluster and lose the ability to manage cluster settings or users. @@ -370,9 +399,7 @@ endif::[] ifndef::env-kubernetes[] === Create superusers -Before enabling authorization in Redpanda, which can happen implicitly when you enable authentication, you must create a superuser. A superuser is a special user that has xref:manage:security/authorization/index.adoc#operations[all permissions] on the cluster. They can grant permissions to other users through access control lists (ACLs). - -Without a superuser, you can create other users, but you can't grant them permissions to the cluster. +Before enabling authorization in Redpanda, which can happen implicitly when you enable authentication, you must create a superuser. Without a superuser, you can create other users, but you can't grant them permissions to the cluster. IMPORTANT: Enabling authorization without a superuser can result in being locked out of the cluster, as you would not have the necessary permissions to manage the cluster's settings or users. @@ -1310,42 +1337,44 @@ Each of the HTTP APIs implements its own permission model with different levels The Admin API primarily requires superuser privileges, with a few exceptions for read-only status endpoints. +==== Admin API permissions + +The Admin API primarily requires superuser privileges, with a few exceptions for specific user-accessible endpoints. + [cols="3,1,1"] |=== |API Category / Operation |Regular Authenticated User |Superuser -|*Authentication* -| -| -|Verify identity of current user -|✅ -|✅ +|*Transaction management* | | -|Reload keys from identity provider -|❌ -|✅ +|Get all transactions |✅ |✅ -|Reload keys and disconnect clients -|❌ -|✅ +|Find transaction coordinator |✅ |✅ -|*Recovery status* -| -| +|Delete partition from transaction |✅ |✅ -|Get Raft recovery status -|✅ -|✅ +|Unsafe abort group transaction |✅ |✅ -|Get transaction manager migration status -|✅ -|✅ +|*Topic management* | | -|*All other Admin API operations* -|❌ -|✅ +|List mountable topics |❌ |✅ + +|Mount topics |❌ |✅ + +|Unmount topics |❌ |✅ + +|*Security management* | | + +|Create, delete, or update users |❌ |✅ + +|List user roles |✅ |✅ + +|Create, delete, or update roles |❌ |✅ + +|*All other Admin API operations* |❌ |✅ |=== + For a complete list of all Admin API endpoints, see see xref:api:ROOT:admin-api.adoc[]. ==== Schema Registry API permissions @@ -1361,6 +1390,7 @@ The HTTP Proxy API impersonates the authenticated user when making Kafka API cal [cols="3,1,1"] |=== |Operation |Regular Authenticated User |Superuser + |Get brokers |❌ |✅ From a0b66723afd9747febd31dba97286742cb976565 Mon Sep 17 00:00:00 2001 From: JakeSCahill Date: Thu, 15 May 2025 16:53:28 +0100 Subject: [PATCH 10/24] Use consistent method of passing arrays to CLI commands --- modules/manage/partials/authentication.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/manage/partials/authentication.adoc b/modules/manage/partials/authentication.adoc index 1e57cac227..c9070d3c0c 100644 --- a/modules/manage/partials/authentication.adoc +++ b/modules/manage/partials/authentication.adoc @@ -409,7 +409,7 @@ A superuser can either be a SCRAM user or it can be provided by external authent + [,bash] ---- -rpk cluster config set superusers [''] +rpk cluster config set superusers '["superuser-username"]' ---- + This can be a new user or an existing user. For example, if you use the superuser named `admin`, then Redpanda allows the `admin` user to do anything, but Redpanda does not create the `admin` user. From 03f8bc099fed6a3e9072eb3205524b410e8ee281 Mon Sep 17 00:00:00 2001 From: Jake Cahill <45230295+JakeSCahill@users.noreply.github.com> Date: Thu, 15 May 2025 17:18:35 +0100 Subject: [PATCH 11/24] Update authentication.adoc --- modules/manage/partials/authentication.adoc | 38 --------------------- 1 file changed, 38 deletions(-) diff --git a/modules/manage/partials/authentication.adoc b/modules/manage/partials/authentication.adoc index c9070d3c0c..9b496a94cd 100644 --- a/modules/manage/partials/authentication.adoc +++ b/modules/manage/partials/authentication.adoc @@ -1337,44 +1337,6 @@ Each of the HTTP APIs implements its own permission model with different levels The Admin API primarily requires superuser privileges, with a few exceptions for read-only status endpoints. -==== Admin API permissions - -The Admin API primarily requires superuser privileges, with a few exceptions for specific user-accessible endpoints. - -[cols="3,1,1"] -|=== -|API Category / Operation |Regular Authenticated User |Superuser - -|*Transaction management* | | - -|Get all transactions |✅ |✅ - -|Find transaction coordinator |✅ |✅ - -|Delete partition from transaction |✅ |✅ - -|Unsafe abort group transaction |✅ |✅ - -|*Topic management* | | - -|List mountable topics |❌ |✅ - -|Mount topics |❌ |✅ - -|Unmount topics |❌ |✅ - -|*Security management* | | - -|Create, delete, or update users |❌ |✅ - -|List user roles |✅ |✅ - -|Create, delete, or update roles |❌ |✅ - -|*All other Admin API operations* |❌ |✅ -|=== - - For a complete list of all Admin API endpoints, see see xref:api:ROOT:admin-api.adoc[]. ==== Schema Registry API permissions From 6519808f53e84715845b600c22f718be2b3efd85 Mon Sep 17 00:00:00 2001 From: Jake Cahill <45230295+JakeSCahill@users.noreply.github.com> Date: Thu, 15 May 2025 17:21:02 +0100 Subject: [PATCH 12/24] Update console-v3.adoc --- modules/migrate/pages/console-v3.adoc | 34 +++++++++++++-------------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/modules/migrate/pages/console-v3.adoc b/modules/migrate/pages/console-v3.adoc index f07eecb71c..ba774247b7 100644 --- a/modules/migrate/pages/console-v3.adoc +++ b/modules/migrate/pages/console-v3.adoc @@ -220,16 +220,30 @@ If you previously assigned roles in Redpanda Console, you must now provision tho The following examples show how to map Console roles (`viewer`, `editor`, `admin`) to Redpanda ACLs. +[cols="1,3", options="header"] +|=== +| Console Role | Equivalent ACLs in Redpanda + +| Viewer +| `read`, `describe` on topics and groups + +| Editor +| `read`, `write`, `describe` on topics and `describe` on groups + +| Admin +| All of the above, plus add the user as a `superuser` principal using the cluster configuration +|=== + [,bash] ---- -# Allow a viewer to read topics and consumer groups +# Viewer role in Redpanda Console -> Redpanda ACLs rpk security acl create \ --allow-principal User:alice@example.com \ --operation read,describe \ --topic '*' \ --group '*' -# Allow an editor to produce and consume +# Editor role in Redpanda Console -> Redpanda ACLs rpk security acl create \ --allow-principal User:alice@example.com \ --operation read,write,describe \ @@ -240,24 +254,10 @@ rpk security acl create \ --operation describe \ --group '*' -# Grant admin access (needs separate superuser assignment for Admin API) +# Admin role in Redpanda Console -> Redpanda superuser rpk cluster config set superusers "['alice@example.com']" ---- -[cols="1,3", options="header"] -|=== -| Console Role | Equivalent ACLs in Redpanda - -| Viewer -| `read`, `describe` on topics and groups - -| Editor -| `read`, `write`, `describe` on topics and `describe` on groups - -| Admin -| All of the above, plus `superuser` role using the cluster configuration -|=== - For details, see: - xref:manage:security/authorization/acl.adoc[] From 45e14073b76e597b13e97a0080b92b2e543ff6ca Mon Sep 17 00:00:00 2001 From: Jake Cahill <45230295+JakeSCahill@users.noreply.github.com> Date: Thu, 15 May 2025 17:23:59 +0100 Subject: [PATCH 13/24] Apply suggestions from code review --- modules/console/pages/config/security/authorization.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/console/pages/config/security/authorization.adoc b/modules/console/pages/config/security/authorization.adoc index 83948aabcf..0ab29e3617 100644 --- a/modules/console/pages/config/security/authorization.adoc +++ b/modules/console/pages/config/security/authorization.adoc @@ -18,7 +18,7 @@ Redpanda Console supports two authorization modes, depending on whether *user im `roleBindings` in the Redpanda Console configuration are ignored. | **Impersonation disabled** (`impersonateUser: false`) -| Redpanda Console enforces access using static `roleBindings` from the configuration file. +| Redpanda Console enforces access using static `roleBindings` from the Redpanda Console configuration file. Redpanda treats all requests as coming from a single service account. |=== From 21b306dae898f5d3d18ed3e837156434f359b7c9 Mon Sep 17 00:00:00 2001 From: JakeSCahill Date: Fri, 16 May 2025 09:35:45 +0100 Subject: [PATCH 14/24] Apply suggestions from review --- .../pages/config/security/authentication.adoc | 21 +- .../pages/config/security/authorization.adoc | 211 +++++++++++++----- modules/manage/partials/authentication.adoc | 1 + 3 files changed, 177 insertions(+), 56 deletions(-) diff --git a/modules/console/pages/config/security/authentication.adoc b/modules/console/pages/config/security/authentication.adoc index d000058dd0..7a74b3c57e 100644 --- a/modules/console/pages/config/security/authentication.adoc +++ b/modules/console/pages/config/security/authentication.adoc @@ -35,14 +35,15 @@ 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 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 RBAC needs to be separated from Redpanda identities. Upon login, 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. For OIDC-based login flows, Redpanda Console reuses the OAuth 2.0 access token from the identity provider (IdP) to authenticate to Redpanda's Kafka and HTTP APIs. These access tokens must be in JWT format to be compatible with Redpanda's SASL/OAUTHBEARER authentication. -Some IdPs, such as Google, issue opaque access tokens that are not JWTs. While these tokens work for logging in to Redpanda Console (the ID token is a JWT), they cannot be used for impersonation with the Kafka API. In such cases, impersonation must be disabled, and Console must be configured to use static credentials instead. +Some IdPs, such as Google, issue opaque access tokens that are not JWTs. While these tokens work for logging in to Redpanda Console (the ID token is a JWT), they cannot be used for impersonation with the Kafka API. In such cases, impersonation must be disabled, and Redpanda Console must be configured to use static service account credentials instead. +.Redpanda Console authenticates users and then authorizes their access based on the impersonation mode and configured RBAC or ACLs. [mermaid,width=450px] .... flowchart TD @@ -167,7 +168,7 @@ You can use any OIDC-compliant IdP with Redpanda Console. Here are common provid | `\https://github.com/login/oauth` |=== -Some IdPs, such as Google, issue opaque access tokens that are not JWTs. While these tokens work for logging in to Redpanda Console (the ID token is a JWT), they cannot be used for impersonation with the Kafka API. In such cases, impersonation must be disabled, and Console must be configured to use static credentials instead. +Some IdPs, such as Google, issue opaque access tokens that are not JWTs. While these tokens work for logging in to Redpanda Console (the ID token is a JWT), they cannot be used for impersonation with the Kafka API. In such cases, impersonation must be disabled, and Redpanda Console must be configured to use static service account credentials instead. For example, this is how to configure Redpanda Console with Entra ID: @@ -398,6 +399,20 @@ 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] diff --git a/modules/console/pages/config/security/authorization.adoc b/modules/console/pages/config/security/authorization.adoc index 0ab29e3617..d365217469 100644 --- a/modules/console/pages/config/security/authorization.adoc +++ b/modules/console/pages/config/security/authorization.adoc @@ -1,5 +1,5 @@ = Authorization -:description: Redpanda Console uses role-based access control (RBAC) to restrict system access to authorized users. +:description: Redpanda Console uses 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 [NOTE] @@ -7,30 +7,120 @@ include::shared:partial$enterprise-and-console.adoc[] ==== +{description} + Redpanda Console supports two authorization modes, depending on whether *user impersonation* is enabled in the authentication configuration: [cols="1,2"] |=== | Mode | Who Evaluates Permissions? -| **Impersonation enabled** (`impersonateUser: true`) -| Redpanda authorizes requests based on internal RBAC and ACLs. -`roleBindings` in the Redpanda Console configuration are ignored. +| Impersonation disabled (`impersonateUser: false`) +| Redpanda Console evaluates permissions using roleBindings defined in its configuration. Redpanda sees all requests as coming from a static service account. -| **Impersonation disabled** (`impersonateUser: false`) -| Redpanda Console enforces access using static `roleBindings` from the Redpanda Console configuration file. -Redpanda treats all requests as coming from a single service account. +| Impersonation enabled (`impersonateUser: true`) +| Redpanda evaluates permissions using its internal RBAC and ACLs. The `roleBindings` section of the Redpanda Console configuration is ignored. |=== -Even when using Redpanda Console roles, users must still have ACLs in Redpanda if they are interacting with Redpanda through the UI. +For more information about authentication options, see the xref:console:config/security/authentication.adoc[Redpanda Console authentication]. + +== Modes of service account usage + +When impersonation is disabled, Redpanda Console uses a static service account to connect to Redpanda APIs. This service account must be listed as a superuser principal in the Redpanda `superusers` configuration. + +In Redpanda, a principal is the authenticated identity (such as a username or OIDC subject) used for access control. For details, see xref:manage:security/authentication.adoc#principals[Users, Principals, and Superusers]. + +There are two ways to use this service account: + +=== Static service account only (no login) + +Use this mode to connect Redpanda Console to Redpanda with a static account and *no user login*. + +- No login screen. +- All users share the same access level. +- Redpanda Console roles and RBAC are not enforced. +- Useful for internal tools. + +.Example +[source,yaml] +---- +authentication: + basic: + enabled: false + oidc: + enabled: false + +kafka: + sasl: + enabled: true + impersonateUser: false + username: "console-superuser" + password: "secret" +---- + +=== Static service account with user login -For more information about authentication options, see the xref:console:config/security/authentication.adoc[authentication configuration]. +Use this mode to allow users to log in, while still having all API calls executed under a single service account. + +- Users authenticate to the UI using basic or OIDC login. +- All backend communication to Redpanda APIs uses the service account. +- Redpanda Console roles (`roleBindings`) determine what users can see or do in the UI. +- Redpanda authorization is evaluated against the service account. + +.Example +[source,yaml] +---- +authentication: + basic: + enabled: true + +kafka: + sasl: + enabled: true + impersonateUser: false + username: "console-superuser" + password: "secret" + +authorization: + roleBindings: + - roleName: admin + users: + - loginType: basic + name: alice +---- + +This model is recommended if you want to manage RBAC in Redpanda Console, but still want to use a service account for API calls. == Roles -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. +Roles in Redpanda Console determine which UI features users can access. These roles are configured in the `roleBindings` stanza of the Redpanda Console configuration file and are evaluated only when impersonation is disabled. + +.When impersonation is enabled, Redpanda authorizes requests, not Redpanda Console +[%collapsible] +==== +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 in this mode. + +To successfully log in and access the UI, users must have valid Redpanda credentials and ACLs that permit access to the Kafka API. + +To access full Redpanda Console functionality (for example, downloading debug bundles or viewing broker configs), the user must also be a superuser in Redpanda. + +For information on assigning ACLs and superuser status, see xref:manage:security/authorization/acl.adoc[]. +==== + +When impersonation is disabled, Redpanda Console authorizes access to features in the UI based on the configured roles in `roleBindings`. However: + +- Redpanda Console roles are not shown in the *Roles* tab on the *Security* page. + +- Redpanda Console roles do not grant access to Redpanda APIs (such as the Kafka API). + +- A Redpanda Console Admin is not a Redpanda superuser by default. + +To perform protected actions (for example, creating topics, managing ACLs, or accessing the Admin API), users must be granted corresponding permissions in Redpanda. -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. +[IMPORTANT] +==== +If you're running Console with impersonation disabled, ensure the Redpanda Console service account is listed as a superuser in Redpanda. Otherwise, Redpanda Console cannot perform administrative actions on behalf of logged in users. +==== Redpanda Console provides the following predefined roles: @@ -63,67 +153,78 @@ Redpanda Console provides the following predefined roles: | No limitations |=== -[NOTE] -==== -Redpanda Console roles are not visible in the *Roles* tab on the Security page. That section displays only roles managed by Redpanda. -==== - == Grant permissions through role bindings -To assign roles when impersonation is disabled, define `roleBindings` in the Redpanda Console configuration. Each binding associates one or more users with a specific role. +When impersonation is disabled, Redpanda Console connects to Redpanda APIs using the service account defined in: -.Example: Assign the Viewer role to a user -[,yaml] +- `kafka.sasl`: For the Kafka API +- `schemaRegistry.authentication`: For the Schema Registry API +- `redpanda.adminApi.authentication`: For the Admin API + +The Redpanda Console service account must be a superuser principal in Redpanda. Without superuser privileges, Redpanda Console is unable to perform actions such as listing topics, retrieving cluster metrics, managing ACLs, or accessing administrative endpoints. + +To grant superuser permissions to the service account: + +[,bash] ---- -kafka: - brokers: ["broker1.example.com:9092"] - sasl: - enabled: true - impersonateUser: false <1> - username: "static-kafka-user" - password: "static-pass" - mechanism: "SCRAM-SHA-256" -authorization: - roleBindings: <2> - - roleName: viewer - users: - - loginType: basic - name: static-kafka-user +rpk cluster config set superusers '["console-superuser"]' \ + -X user= -X pass= ---- -<1> User impersonation is disabled, so role bindings are used for authorization. -<2> The roleBindings section maps users to roles using their login type and username. -== When impersonation is enabled +Before login, Redpanda Console authenticates the user by validating their credentials against the Kafka API. If the user does not exist in Redpanda (for example, if they have not been created or their identity is not mapped through OIDC), login fails. -When impersonation is enabled, Redpanda Console does not evaluate any role bindings defined in the configuration. Instead, the user identity is forwarded to Redpanda, and Redpanda authorizes the request based on its own RBAC rules and access control lists (ACLs). To access Redpanda Console in this mode, the user must be registered in Redpanda and have ACLs that permit access to the Kafka API. Without these permissions, the user cannot successfully log into Redpanda Console. +After login, all API communication is performed using the service account's credentials, not the end-user's. This ensures Redpanda Console can act on the user's behalf. As such, the service account must have sufficient privileges to cover the actions users are allowed to perform in the UI. -To access all functionality in Redpanda Console, such as generating debug bundles, the user must also have superuser permissions assigned in Redpanda. +=== Example: Assign the Viewer role -For detailed steps to create ACLs, see xref:manage:security/authorization/acl.adoc[]. +This example grants the Viewer role to a user named `matt`. The Redpanda Console service account (`console-superuser`) is used to authenticate to all Redpanda services. -.Example: Role bindings ignored when impersonating users [,yaml] ---- kafka: brokers: ["broker1.example.com:9092"] sasl: enabled: true - impersonateUser: true <1> + impersonateUser: false + username: "console-superuser" # <1> + password: "secret-password" + mechanism: "SCRAM-SHA-256" +schemaRegistry: + enabled: true + urls: + - "http://broker1.example.com:8081" + - "http://broker2.example.com:8081" + authentication: + impersonateUser: false + basic: + username: "console-superuser" # <1> + password: "secret-password" +redpanda: + adminApi: + enabled: true + urls: + - "http://broker1.example.com:9644" + - "http://broker2.example.com:9644" + authentication: + impersonateUser: false + basic: + username: "console-superuser" # <1> + password: "secret-password" authentication: - jwtSigningKey: secret-key - useSecureCookies: false + jwtSigningKey: "" basic: - enabled: true <2> + enabled: true authorization: - roleBindings: - - roleName: admin - users: - - loginType: basic - name: Peter <3> + roleBindings: # <2> + - roleName: viewer + users: + - loginType: basic + name: matt ---- -<1> User impersonation is enabled for Kafka API requests. -<2> Users authenticate with basic authentication. -<3> This role binding has no effect because Redpanda authorizes the request. +<1> With impersonation disabled, Redpanda Console uses the static service account (`console-superuser`) to connect to the Redpanda APIs. +<2> Role bindings map UI users to Redpanda Console roles. This does not grant Redpanda-level permissions. The user (`matt`) must also exist in Redpanda. + +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. == Multiple roles and duplicate bindings @@ -150,5 +251,9 @@ Duplicate role assignments do not cause errors. If the same role is assigned mor == Suggested reading -* xref:manage:security/authorization/rbac.adoc[Redpanda RBAC] +For details on how to assign Redpanda-level permissions through ACLs or RBAC, see: + +- xref:manage:security/authorization/acl.adoc[] +- xref:manage:security/authorization/rbac.adoc[] + diff --git a/modules/manage/partials/authentication.adoc b/modules/manage/partials/authentication.adoc index 9b496a94cd..a2a3b309e2 100644 --- a/modules/manage/partials/authentication.adoc +++ b/modules/manage/partials/authentication.adoc @@ -34,6 +34,7 @@ ifndef::env-kubernetes[- mTLS] - OIDC |=== +[[principals]] == Users, principals, and superusers When you configure authentication and authorization in Redpanda, it's important to understand the distinction between *users*, *principals*, and *superusers*: From 7bc537b7b3ea1219933153679a6fa0dc454aa8ec Mon Sep 17 00:00:00 2001 From: Jake Cahill <45230295+JakeSCahill@users.noreply.github.com> Date: Fri, 16 May 2025 14:55:14 +0100 Subject: [PATCH 15/24] Update authentication.adoc --- modules/console/pages/config/security/authentication.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/modules/console/pages/config/security/authentication.adoc b/modules/console/pages/config/security/authentication.adoc index 7a74b3c57e..74bef6a995 100644 --- a/modules/console/pages/config/security/authentication.adoc +++ b/modules/console/pages/config/security/authentication.adoc @@ -114,12 +114,12 @@ authentication: prompt: "consent" # <11> ---- -<1> Required. Secret key for signing JWTs. Must be at least 32 characters. Store securely. +<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. +<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]. From 8e3961ef604020c16a8877a91b9a7fea872662c9 Mon Sep 17 00:00:00 2001 From: Jake Cahill <45230295+JakeSCahill@users.noreply.github.com> Date: Fri, 16 May 2025 14:56:54 +0100 Subject: [PATCH 16/24] Update authorization.adoc --- modules/console/pages/config/security/authorization.adoc | 2 ++ 1 file changed, 2 insertions(+) diff --git a/modules/console/pages/config/security/authorization.adoc b/modules/console/pages/config/security/authorization.adoc index d365217469..ea5ee77bf1 100644 --- a/modules/console/pages/config/security/authorization.adoc +++ b/modules/console/pages/config/security/authorization.adoc @@ -222,6 +222,8 @@ authorization: name: matt ---- <1> With impersonation disabled, Redpanda Console uses the static service account (`console-superuser`) to connect to the Redpanda APIs. ++ +NOTE: For security, store private data such as passwords in environment variables. For example: `KAFKA_SASL_PASSWORD`. <2> Role bindings map UI users to Redpanda Console roles. This does not grant Redpanda-level permissions. The user (`matt`) must also exist in Redpanda. 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. From 726cd729f09e0500594e0957e959289ad74e7386 Mon Sep 17 00:00:00 2001 From: JakeSCahill Date: Mon, 19 May 2025 09:01:12 +0100 Subject: [PATCH 17/24] Add mention of enviornment variables for secure data --- .../pages/config/security/authentication.adoc | 26 ++++++++++--------- .../pages/config/security/authorization.adoc | 8 +++--- 2 files changed, 18 insertions(+), 16 deletions(-) diff --git a/modules/console/pages/config/security/authentication.adoc b/modules/console/pages/config/security/authentication.adoc index 74bef6a995..a040af27af 100644 --- a/modules/console/pages/config/security/authentication.adoc +++ b/modules/console/pages/config/security/authentication.adoc @@ -89,6 +89,8 @@ Redpanda and Redpanda Console require OAuth 2.0-compliant JWT tokens for user au include::manage:partial$security/oidc/limitations.adoc[leveloffset=+2] +IMPORTANT: For any secret values, xref:console:config/configure-console.adoc[use environment variables] instead of hardcoding them in the configuration file. For example, use `AUTHENTICATION_OIDC_CLIENTSECRET` for the client secret. + ==== Enable runtime acquisition mode [,yaml] @@ -114,7 +116,7 @@ authentication: prompt: "consent" # <11> ---- -<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). @@ -145,7 +147,7 @@ authentication: prompt: "consent" ---- -<1> A pre-acquired OIDC token. Keep this secure. +<1> A pre-acquired OIDC token. Keep this secure. You can also use the `AUTHENTICATION_OIDC_TOKEN` environment variable. ==== Supported identity providers @@ -230,7 +232,7 @@ You must configure how Redpanda Console authenticates to each Redpanda API: Kafk Choose one method per API: * **User impersonation:** Uses the login credentials of the current user. -* **Static credentials:** Uses preconfigured credentials and role bindings. +* **Static credentials:** Uses preconfigured credentials of a superuser to communicate with Redpanda and role bindings to control access in Redpanda Console for logged in users. === Kafka API examples @@ -252,15 +254,15 @@ kafka: sasl: enabled: true impersonateUser: false - username: "static-kafka-user" - password: "static-pass" + username: "console-superuser" + password: "superuser-password" mechanism: "SCRAM-SHA-256" authorization: roleBindings: - roleName: viewer users: - loginType: basic - name: "static-kafka-user" + name: "matt" ---- .Static credentials with OIDC @@ -311,14 +313,14 @@ schemaRegistry: enabled: true impersonateUser: false basic: - username: "static-sr-user" - password: "static-sr-pass" + username: "console-superuser" + password: "superuser-password" authorization: roleBindings: - roleName: editor users: - loginType: basic - name: "static-sr-user" + name: "matt" ---- .Static credentials with OIDC bearer token @@ -366,14 +368,14 @@ redpanda: authentication: impersonateUser: false basic: - username: "static-admin-user" - password: "static-admin-pass" + username: "console-superuser" + password: "superuser-password" authorization: roleBindings: - roleName: admin users: - loginType: basic - name: "static-admin-user" + name: "matt" ---- .Static credentials with OIDC bearer token diff --git a/modules/console/pages/config/security/authorization.adoc b/modules/console/pages/config/security/authorization.adoc index ea5ee77bf1..399ff47faf 100644 --- a/modules/console/pages/config/security/authorization.adoc +++ b/modules/console/pages/config/security/authorization.adoc @@ -26,10 +26,12 @@ For more information about authentication options, see the xref:console:config/s == Modes of service account usage -When impersonation is disabled, Redpanda Console uses a static service account to connect to Redpanda APIs. This service account must be listed as a superuser principal in the Redpanda `superusers` configuration. +*When impersonation is disabled*, Redpanda Console uses a static service account to connect to Redpanda APIs. This service account must be listed as a superuser principal in the Redpanda `superusers` configuration. In Redpanda, a principal is the authenticated identity (such as a username or OIDC subject) used for access control. For details, see xref:manage:security/authentication.adoc#principals[Users, Principals, and Superusers]. +IMPORTANT: For any secret values, xref:console:config/configure-console.adoc[use environment variables] instead of hardcoding them in the configuration file. For example, use `KAFKA_SASL_PASSWORD` for the service account password. + There are two ways to use this service account: === Static service account only (no login) @@ -221,9 +223,7 @@ authorization: - loginType: basic name: matt ---- -<1> With impersonation disabled, Redpanda Console uses the static service account (`console-superuser`) to connect to the Redpanda APIs. -+ -NOTE: For security, store private data such as passwords in environment variables. For example: `KAFKA_SASL_PASSWORD`. +<1> With impersonation disabled, Redpanda Console uses the static service account (`console-superuser`) to connect to the Redpanda APIs. For security, store private data such as passwords in environment variables. For example: `KAFKA_SASL_PASSWORD`. <2> Role bindings map UI users to Redpanda Console roles. This does not grant Redpanda-level permissions. The user (`matt`) must also exist in Redpanda. 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. From 051060b7253bfeb48204b88defedd935e0e0acf5 Mon Sep 17 00:00:00 2001 From: Jake Cahill <45230295+JakeSCahill@users.noreply.github.com> Date: Thu, 22 May 2025 11:25:26 +0100 Subject: [PATCH 18/24] Apply suggestions from code review --- .../pages/config/security/authorization.adoc | 2 +- modules/manage/partials/authentication.adoc | 24 ------------------- 2 files changed, 1 insertion(+), 25 deletions(-) diff --git a/modules/console/pages/config/security/authorization.adoc b/modules/console/pages/config/security/authorization.adoc index 399ff47faf..4ee861f140 100644 --- a/modules/console/pages/config/security/authorization.adoc +++ b/modules/console/pages/config/security/authorization.adoc @@ -97,7 +97,7 @@ This model is recommended if you want to manage RBAC in Redpanda Console, but st Roles in Redpanda Console determine which UI features users can access. These roles are configured in the `roleBindings` stanza of the Redpanda Console configuration file and are evaluated only when impersonation is disabled. -.When impersonation is enabled, Redpanda authorizes requests, not Redpanda Console +.When impersonation is enabled, Redpanda Console uses the identity of the logged-in user to send requests to Redpanda [%collapsible] ==== 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 in this mode. diff --git a/modules/manage/partials/authentication.adoc b/modules/manage/partials/authentication.adoc index a2a3b309e2..2918455dee 100644 --- a/modules/manage/partials/authentication.adoc +++ b/modules/manage/partials/authentication.adoc @@ -1350,30 +1350,6 @@ Most read operations require only user-level authentication, while write operati The HTTP Proxy API impersonates the authenticated user when making Kafka API calls: -[cols="3,1,1"] -|=== -|Operation |Regular Authenticated User |Superuser - -|Get brokers -|❌ -|✅ - -|List topics -|❌ -|✅ - -|Produce to topic -|Subject to ACLs -|✅ - -|Fetch from topic -|Subject to ACLs -|✅ - -|Consumer operations -|Subject to ACLs -|✅ -|=== Regular users are subject to the same ACL restrictions as they would be when using the Kafka API directly. From 32d8cac9562427ded521a4176c64916a6581b26a Mon Sep 17 00:00:00 2001 From: JakeSCahill Date: Thu, 22 May 2025 11:52:03 +0100 Subject: [PATCH 19/24] Apply suggestions --- .../console/pages/config/security/authentication.adoc | 10 ++++++---- .../console/pages/config/security/authorization.adoc | 6 +++--- 2 files changed, 9 insertions(+), 7 deletions(-) diff --git a/modules/console/pages/config/security/authentication.adoc b/modules/console/pages/config/security/authentication.adoc index a040af27af..0bee681eed 100644 --- a/modules/console/pages/config/security/authentication.adoc +++ b/modules/console/pages/config/security/authentication.adoc @@ -26,7 +26,7 @@ Authentication in Redpanda Console lets users log in and optionally forward thei Redpanda Console supports the following authentication methods: * **OIDC (OpenID Connect):** Integrates with external identity providers (IdPs) for single sign-on (SSO). -* **basic authentication:** Uses traditional username and password credentials. +* **Basic authentication:** Uses traditional username and password credentials. image::console:login.png[] @@ -37,7 +37,7 @@ 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. -Upon login, 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. +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. For OIDC-based login flows, Redpanda Console reuses the OAuth 2.0 access token from the identity provider (IdP) to authenticate to Redpanda's Kafka and HTTP APIs. These access tokens must be in JWT format to be compatible with Redpanda's SASL/OAUTHBEARER authentication. @@ -63,7 +63,7 @@ flowchart TD == Prerequisites -* Your credentials must match an existing user in your Redpanda cluster. +* You must have at least one superuser in Redpanda. * The authentication method used in Redpanda Console must match the configuration of the Kafka API: **If using OIDC:** @@ -227,13 +227,15 @@ Most Kafka client libraries support SASL/SCRAM out of the box. You must configur == Configure API authentication -You must configure how Redpanda Console authenticates to each Redpanda API: Kafka, Admin, and Schema Registry. +After enabling authentication, you must configure how Redpanda Console authenticates to each Redpanda API: Kafka, Admin, and Schema Registry. Choose one method per API: * **User impersonation:** Uses the login credentials of the current user. * **Static credentials:** Uses preconfigured credentials of a superuser to communicate with Redpanda and role bindings to control access in Redpanda Console for logged in users. +TIP: Redpanda Data recommends user impersonation so that access control is fine-grained and centralized within Redpanda. This way, audit logs are also more accurate, as they reflect the actual user identity. + === Kafka API examples .User impersonation diff --git a/modules/console/pages/config/security/authorization.adoc b/modules/console/pages/config/security/authorization.adoc index 4ee861f140..0b2b6664cf 100644 --- a/modules/console/pages/config/security/authorization.adoc +++ b/modules/console/pages/config/security/authorization.adoc @@ -1,5 +1,5 @@ = Authorization -:description: Redpanda Console uses 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. +: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 [NOTE] @@ -16,10 +16,10 @@ Redpanda Console supports two authorization modes, depending on whether *user im | Mode | Who Evaluates Permissions? | Impersonation disabled (`impersonateUser: false`) -| Redpanda Console evaluates permissions using roleBindings defined in its configuration. Redpanda sees all requests as coming from a static service account. +| 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. The `roleBindings` section of the Redpanda Console configuration is ignored. +| Redpanda evaluates permissions using its internal RBAC and ACLs. The 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]. From 195afdc0d5ac9899d7ddfa82dbca0b1e7e5e9942 Mon Sep 17 00:00:00 2001 From: JakeSCahill Date: Thu, 22 May 2025 14:21:49 +0100 Subject: [PATCH 20/24] Allow 10% variation --- modules/get-started/pages/quick-start.adoc | 10 +++++----- tests/setup-tests/.doc-detective.json | 2 +- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/modules/get-started/pages/quick-start.adoc b/modules/get-started/pages/quick-start.adoc index bd18f650fb..0cdba4893f 100644 --- a/modules/get-started/pages/quick-start.adoc +++ b/modules/get-started/pages/quick-start.adoc @@ -197,7 +197,7 @@ Suppose you're asked to find all transactions related to the `.edu` domain. You // (step {"action":"goTo", "url": "http://localhost:8080/topics/transactions"}) // (step {"action":"wait"}) . Click *Add filter* > *JavaScript Filter*. -// (step {"action":"saveScreenshot", "path": "topic.png", "directory": "../../modules/console/images", "overwrite": "byVariation"}) +// (step {"action":"saveScreenshot", "path": "topic.png", "directory": "../../modules/console/images", "overwrite": "byVariation", "maxVariation": 10}) // (step {"action":"find", "selector": "[data-testid='add-topic-filter']", "matchText": "Add filter", "click": true, "timeout": 10000}) // (step {"action":"find", "selector": "[data-testid='add-topic-filter-javascript']", "matchText": "JavaScript Filter", "click": true, "timeout": 10000}) . Give your filter a name, such as "Find .edu domains". @@ -268,7 +268,7 @@ Suppose you're onboarding a new team member who needs access to specific topics. // (step {"action":"find", "selector": "[data-testid='test_field']", "setVariables": [{"name": "password","regex": ".*"}], "click": true}) // (step {"action":"find", "selector": "[data-testid='password-input-toggle']", "click": true}) // (step {"action":"wait"}) -// (step {"action":"saveScreenshot", "path": "user.png", "directory": "../../modules/console/images", "overwrite": "byVariation"}) +// (step {"action":"saveScreenshot", "path": "user.png", "directory": "../../modules/console/images", "overwrite": "byVariation", "maxVariation": 10}) . Click *Create*. image::console:user.png[] @@ -376,7 +376,7 @@ In the menu, click *Transforms*. On the *Transforms* page, you see your transform. You can use Redpanda Console to manage and monitor your transforms. // (step {"action":"wait"}) -// (step {"action":"saveScreenshot", "path": "transforms.png", "directory": "../../modules/console/images", "overwrite": "byVariation"}) +// (step {"action":"saveScreenshot", "path": "transforms.png", "directory": "../../modules/console/images", "overwrite": "byVariation", "maxVariation": 10}) NOTE: The source code for the data transform function is in the {test-source}docker-compose/transform/transform.go[`docker-compose/transform/transform.go` file] that you downloaded. This file is commented to explain how it works. @@ -389,7 +389,7 @@ See also: // (step {"action":"goTo", "url": "http://localhost:8080/upload-license"}) // (step {"action":"wait"}) -// (step {"action":"saveScreenshot", "path": "license.png", "directory": "../../modules/console/images", "overwrite": "byVariation"}) +// (step {"action":"saveScreenshot", "path": "license.png", "directory": "../../modules/console/images", "overwrite": "byVariation", "maxVariation": 10}) === View audit logs @@ -404,7 +404,7 @@ Audit logs provide a record of all user actions. You can use these logs to track . Click the *_redpanda.audit_log* topic in the table. // (step {"action":"goTo", "url": "http://localhost:8080/topics/_redpanda.audit_log"}) // (step {"action":"wait"}) -// (step {"action":"saveScreenshot", "path": "audit-logs.png", "directory": "../../modules/console/images", "overwrite": "byVariation"}) +// (step {"action":"saveScreenshot", "path": "audit-logs.png", "directory": "../../modules/console/images", "overwrite": "byVariation", "maxVariation": 10}) image::console:audit-logs.png[] diff --git a/tests/setup-tests/.doc-detective.json b/tests/setup-tests/.doc-detective.json index cebe664d91..ceeebc3a12 100644 --- a/tests/setup-tests/.doc-detective.json +++ b/tests/setup-tests/.doc-detective.json @@ -53,7 +53,7 @@ "name": "saveScreenshot", "params": { "directory": "samples", - "maxVariation": 5, + "maxVariation": 10, "overwrite": "byVariation" } } From 102dce2146eaa14da71bdc04de20f82da91b404f Mon Sep 17 00:00:00 2001 From: Jake Cahill <45230295+JakeSCahill@users.noreply.github.com> Date: Fri, 23 May 2025 15:54:59 +0100 Subject: [PATCH 21/24] Apply suggestions from code review Co-authored-by: Joyce Fee <102751339+Feediver1@users.noreply.github.com> --- .../pages/config/security/authorization.adoc | 14 +++++++------- modules/manage/partials/authentication.adoc | 10 +++++----- .../manage/partials/security/oidc/limitations.adoc | 2 +- modules/migrate/pages/console-v3.adoc | 4 ++-- 4 files changed, 15 insertions(+), 15 deletions(-) diff --git a/modules/console/pages/config/security/authorization.adoc b/modules/console/pages/config/security/authorization.adoc index 0b2b6664cf..d8eb291f04 100644 --- a/modules/console/pages/config/security/authorization.adoc +++ b/modules/console/pages/config/security/authorization.adoc @@ -38,10 +38,10 @@ There are two ways to use this service account: Use this mode to connect Redpanda Console to Redpanda with a static account and *no user login*. -- No login screen. +- There is no login screen. - All users share the same access level. - Redpanda Console roles and RBAC are not enforced. -- Useful for internal tools. +- It can be useful for internal tools. .Example [source,yaml] @@ -62,7 +62,7 @@ kafka: === Static service account with user login -Use this mode to allow users to log in, while still having all API calls executed under a single service account. +Use this mode to allow users to log in, while still having all API calls executed under a single service account. When using static service accounts with user login: - Users authenticate to the UI using basic or OIDC login. - All backend communication to Redpanda APIs uses the service account. @@ -97,10 +97,10 @@ This model is recommended if you want to manage RBAC in Redpanda Console, but st Roles in Redpanda Console determine which UI features users can access. These roles are configured in the `roleBindings` stanza of the Redpanda Console configuration file and are evaluated only when impersonation is disabled. -.When impersonation is enabled, Redpanda Console uses the identity of the logged-in user to send requests to Redpanda +.Do you have user impersonation enabled? [%collapsible] ==== -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 in this mode. +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. @@ -179,7 +179,7 @@ After login, all API communication is performed using the service account's cred === Example: Assign the Viewer role -This example grants the Viewer role to a user named `matt`. The Redpanda Console service account (`console-superuser`) is used to authenticate to all Redpanda services. +This example shows how to grant the Viewer role to a user named `matt`. The Redpanda Console service account (`console-superuser`) is used to authenticate to all Redpanda services. [,yaml] ---- @@ -187,7 +187,7 @@ kafka: brokers: ["broker1.example.com:9092"] sasl: enabled: true - impersonateUser: false + impersonateUser: false # <1> username: "console-superuser" # <1> password: "secret-password" mechanism: "SCRAM-SHA-256" diff --git a/modules/manage/partials/authentication.adoc b/modules/manage/partials/authentication.adoc index 2918455dee..8ae9df3214 100644 --- a/modules/manage/partials/authentication.adoc +++ b/modules/manage/partials/authentication.adoc @@ -39,11 +39,11 @@ ifndef::env-kubernetes[- mTLS] When you configure authentication and authorization in Redpanda, it's important to understand the distinction between *users*, *principals*, and *superusers*: -- A user refers to a stored credential within Redpanda, typically a username/password stored in the internal SASL credential store. These are created using commands such as `rpk security user create`. +- A user refers to a stored credential within Redpanda, typically a username and password stored in the internal SASL credential store. These are created using commands such as `rpk security user create`. - A principal is the authenticated identity string associated with a client session. It's what Redpanda uses for access control, ACLs, and superuser assignment. -- A superuser is a privileged principal that has unrestricted access to xref:manage:security/authorization/index.adoc#operations[all operations] in a Redpanda cluster. +- A superuser is a privileged principal who has unrestricted access to xref:manage:security/authorization/index.adoc#operations[all operations] in a Redpanda cluster. Superusers can: @@ -59,7 +59,7 @@ Depending on how a client authenticates, the principal might be: - A certificate DN - A Kerberos identity -You assign ACLs and superuser roles to principals, not users. Even if a user exists, it has no access unless its associated principal is granted permissions. +You assign ACLs and superuser roles to principals, not users. Even if a user exists, they have no access unless its associated principal is granted permissions. For example, with OIDC: @@ -1324,7 +1324,7 @@ endif::[] == Authentication for the HTTP APIs -Redpanda provides three HTTP APIs that support authentication: +Redpanda provides the following HTTP APIs that support authentication: - Admin API: Management and monitoring of the Redpanda cluster - Schema Registry API: Management of schemas and schema evolution @@ -1367,7 +1367,7 @@ Basic authentication provides a method for securing HTTP endpoints. With basic a To add users to the Redpanda credential store that HTTP basic authentication uses, create users with xref:reference:rpk/rpk-acl/rpk-acl-user-create.adoc[`rpk security user create`]. -Both SCRAM users and superusers can use their credentials to access them. The HTTP Proxy API and the Schema Registry API use the same credential store as the Kafka API, so you can use the same credentials for all three APIs. +The HTTP Proxy API and the Schema Registry API use the same credential store as the Kafka API, so you can use the same credentials for all three APIs. The Admin API uses the same credential store as the Kafka API, but it requires superuser credentials to access it. ifdef::env-kubernetes[] diff --git a/modules/manage/partials/security/oidc/limitations.adoc b/modules/manage/partials/security/oidc/limitations.adoc index 8c8926378c..26a429b0b6 100644 --- a/modules/manage/partials/security/oidc/limitations.adoc +++ b/modules/manage/partials/security/oidc/limitations.adoc @@ -6,7 +6,7 @@ - Redpanda Console cannot assign roles to OIDC principals. Roles must be assigned through `rpk`. -- Redpanda requires OIDC principals to be set as superusers to access the Admin API. Granular authorization is not yet supported. +- Redpanda requires OIDC principals to be set as superusers to access the Admin API. Granular authorization is not supported. - The `rpk` CLI does not support the SASL/OAUTHBEARER mechanism for deploying data transforms. Use SASL/SCRAM instead. diff --git a/modules/migrate/pages/console-v3.adoc b/modules/migrate/pages/console-v3.adoc index ba774247b7..028073847e 100644 --- a/modules/migrate/pages/console-v3.adoc +++ b/modules/migrate/pages/console-v3.adoc @@ -173,7 +173,7 @@ Redpanda requires a JWT-encoded access token for authentication. While most iden === Role bindings -In v2, role bindings could be configured in a separate file. In v3, role bindings are configured directly in the `authorization.roleBindings` stanza of the main configuration file. +In Console v2, role bindings could be configured in a separate file. In v3, role bindings are configured directly in the `authorization.roleBindings` stanza of the main configuration file. If you do **not** use impersonation, you can continue to use role bindings to control access within Redpanda Console. Each role binding maps users to roles in Redpanda Console using their login type and identity. @@ -216,7 +216,7 @@ However, if you are using *impersonation* in v3, `roleBindings` are ignored. Ins ==== Migrate Console roles to Redpanda ACLs -If you previously assigned roles in Redpanda Console, you must now provision those users in Redpanda and grant them the appropriate permissions. +If you previously assigned roles in Redpanda Console, you must provision those users in Redpanda and grant them the appropriate permissions. The following examples show how to map Console roles (`viewer`, `editor`, `admin`) to Redpanda ACLs. From 0a44fdaeb017cbabcac36375b6de8982d4e57a2e Mon Sep 17 00:00:00 2001 From: Jake Cahill <45230295+JakeSCahill@users.noreply.github.com> Date: Fri, 23 May 2025 15:59:18 +0100 Subject: [PATCH 22/24] Apply suggestions from code review Co-authored-by: Joyce Fee <102751339+Feediver1@users.noreply.github.com> --- .../console/pages/config/security/authentication.adoc | 10 +++++----- .../console/pages/config/security/authorization.adoc | 4 ++-- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/modules/console/pages/config/security/authentication.adoc b/modules/console/pages/config/security/authentication.adoc index 0bee681eed..0b061314ee 100644 --- a/modules/console/pages/config/security/authentication.adoc +++ b/modules/console/pages/config/security/authentication.adoc @@ -66,10 +66,10 @@ flowchart TD * You must have at least one superuser in Redpanda. * The authentication method used in Redpanda Console must match the configuration of the Kafka API: -**If using OIDC:** +* **If using OIDC:** You must have SASL/OAUTHBEARER authentication configured for the Kafka API. -**If using basic authentication:** +* **If using basic authentication:** You must have SASL/SCRAM authentication configured for the Kafka API. xref:manage:security/authentication.adoc[Learn how to configure authentication for Redpanda]. @@ -124,9 +124,9 @@ authentication: <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]. +<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. +<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. ==== Enable static token mode @@ -232,7 +232,7 @@ After enabling authentication, you must configure how Redpanda Console authentic Choose one method per API: * **User impersonation:** Uses the login credentials of the current user. -* **Static credentials:** Uses preconfigured credentials of a superuser to communicate with Redpanda and role bindings to control access in Redpanda Console for logged in users. +* **Static credentials:** Uses preconfigured credentials of a superuser to communicate with Redpanda, and role bindings to control access in Redpanda Console for logged in users. TIP: Redpanda Data recommends user impersonation so that access control is fine-grained and centralized within Redpanda. This way, audit logs are also more accurate, as they reflect the actual user identity. diff --git a/modules/console/pages/config/security/authorization.adoc b/modules/console/pages/config/security/authorization.adoc index d8eb291f04..ca6c50bb10 100644 --- a/modules/console/pages/config/security/authorization.adoc +++ b/modules/console/pages/config/security/authorization.adoc @@ -19,7 +19,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. The role bindings in the Redpanda Console configuration are ignored. +| Redpanda evaluates permissions using its internal 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]. @@ -36,7 +36,7 @@ There are two ways to use this service account: === Static service account only (no login) -Use this mode to connect Redpanda Console to Redpanda with a static account and *no user login*. +Use this mode to connect Redpanda Console to Redpanda with a static service account and *no user login*. When using the static service account (no login) mode: - There is no login screen. - All users share the same access level. From 85e282548d683a15d42872954f603c47949a2c60 Mon Sep 17 00:00:00 2001 From: Jake Cahill <45230295+JakeSCahill@users.noreply.github.com> Date: Fri, 23 May 2025 16:39:12 +0100 Subject: [PATCH 23/24] Update authentication.adoc --- modules/console/pages/config/security/authentication.adoc | 1 + 1 file changed, 1 insertion(+) diff --git a/modules/console/pages/config/security/authentication.adoc b/modules/console/pages/config/security/authentication.adoc index 0b061314ee..d5b7e53b53 100644 --- a/modules/console/pages/config/security/authentication.adoc +++ b/modules/console/pages/config/security/authentication.adoc @@ -1,6 +1,7 @@ = Authentication :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 // ========================AUTOMATED TESTS=================================== // The comments in this file are used to run automated tests of the documented steps. Tests are run using GitHub Actions on each pull request that changes this file in the upstream repository. For more details about the testing tool we use, see https://doc-detective.com/. From 5cdb5674ca399712b3dbdfb64e0ecb9dc7537779 Mon Sep 17 00:00:00 2001 From: Jake Cahill <45230295+JakeSCahill@users.noreply.github.com> Date: Fri, 23 May 2025 16:39:31 +0100 Subject: [PATCH 24/24] Update authorization.adoc --- modules/console/pages/config/security/authorization.adoc | 1 + 1 file changed, 1 insertion(+) diff --git a/modules/console/pages/config/security/authorization.adoc b/modules/console/pages/config/security/authorization.adoc index ca6c50bb10..49ece3aca5 100644 --- a/modules/console/pages/config/security/authorization.adoc +++ b/modules/console/pages/config/security/authorization.adoc @@ -1,6 +1,7 @@ = Authorization :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 [NOTE] ====