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/ROOT/nav.adoc b/modules/ROOT/nav.adoc index 9c102a1f76..30f1c02b4c 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] @@ -86,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] @@ -193,27 +184,34 @@ *** 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[] ** 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] 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..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/. @@ -19,25 +20,31 @@ 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 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. -Redpanda Console can authenticate to the Kafka, Admin, and Schema Registry APIs (Redpanda APIs) using two methods: +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. -- *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 <>. +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. -- *Static credentials*: For services such as Kafka Connect and Git, or optionally for Redpanda APIs, Redpanda Console uses static credentials defined in the configuration. +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 @@ -55,88 +62,74 @@ 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: +== Prerequisites -* **Kafka authentication:** - The provided credentials are mapped to SASL-SCRAM, ensuring that Kafka operations execute with the correct user identity. +* You must have at least one superuser in Redpanda. +* The authentication method used in Redpanda Console must match the configuration of the Kafka API: -* **HTTP API authentication:** - The JWT supports HTTP Basic authentication for other APIs. +* **If using OIDC:** +You must have SASL/OAUTHBEARER authentication configured for the Kafka API. -== Prerequisites +* **If using basic authentication:** +You must have SASL/SCRAM authentication configured for the Kafka API. -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: +xref:manage:security/authentication.adoc[Learn how to configure authentication for Redpanda]. -- *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. +== Enable authentication -See xref:manage:security/authentication.adoc[Configure Authentication for Redpanda]. +Redpanda Console supports enabling both OIDC and basic authentication simultaneously. If both are enabled, users can choose how to log in. -[[enable-authentication]] -== Enable authentication for Redpanda Console +=== Enable OIDC authentication -Enable OIDC and basic authentication in Redpanda Console. OIDC offers secure single sign-on for production, while basic authentication provides a simple login option. +To configure OIDC, choose one of two modes: -You can enable both OIDC and basic authentication simultaneously. If you enable both, Redpanda Console presents users with a choice of login methods. +* *Runtime acquisition mode:* Redpanda Console obtains a token from the IdP. +* *Static token mode:* You provide a pre-acquired OIDC token. -=== Enable OIDC authentication +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. -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: +include::manage:partial$security/oidc/limitations.adoc[leveloffset=+2] -* **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. +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. -Here is an example configuration for **runtime acquisition mode**: +==== 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. You can also use the `AUTHENTICATION_JWTSIGNINGKEY`environment variable. +<2> Recommended in production. Marks cookies as secure. +<3> Required. Enables OIDC authentication. +<4> Required. URL of the OIDC identity provider (IdP). +<5> Required. The client ID from your IdP. +<6> Required. The client secret from your IdP. You can also use the `AUTHENTICATION_OIDC_CLIENTSECRET` environment variable. +<7> Requested scopes. Some IdPs such as Azure Entra ID require additional scopes to request OAuth 2.0-compliant tokens. +<8> Optional. TLS configuration for secure connections to the IdP. Configure TLS only if you require mTLS or if you use a self-signed certificate for your identity provider. +<9> Optional. Redirect URI registered with the IdP. This URL must be registered with your IdP and must point to the `/auth/callbacks/oidc` path in Redpanda Console. If this URL is not configured, Redpanda Console constructs the URL by using the base URL from the request and adding the `/auth/callbacks/oidc` path. You may want to configure this URL if you use xref:console:config/http-path-rewrites.adoc[HTTP path rewrites]. +<10> Optional. Controls whether a refresh token is requested. A value of `offline` (default) requests a refresh token for long-lived sessions. Set it to `online` if you don't want a refresh token. +<11> Optional. Determines how the authorization prompt is displayed. Use `consent` (default) to force the consent screen to appear even if the user has previously authorized the application. Alternatives include `none` (no prompt) or `select_account` to allow the user to choose an account. Some IdPs require `consent` to issue a refresh token. -Here is an example configuration for **static token mode**: +==== Enable static token mode [,yaml] ---- @@ -146,218 +139,286 @@ 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. You can also use the `AUTHENTICATION_OIDC_TOKEN` environment variable. -Then, <> for specific APIs. +==== Supported identity providers + +You can use any OIDC-compliant IdP with Redpanda Console. Here are common providers: + +[cols="1,3"] +|=== +| Provider | Example `issuerUrl` + +| 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` +|=== + +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: + +[,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. + +==== 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 + +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. -After you <> for Redpanda Console, you must configure how Redpanda Console authenticates to the following APIs in your Redpanda cluster: +Most Kafka client libraries support SASL/SCRAM out of the box. You must configure the client with: -* **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. +- `sasl.mechanism`: One of `SCRAM-SHA-256` or `SCRAM-SHA-512` +- `sasl.username`: The Redpanda username +- `sasl.password`: The corresponding password -Choose one of the following authentication methods for each API: +== Configure API authentication -* **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. +After enabling authentication, you must configure how Redpanda Console authenticates to each Redpanda API: Kafka, Admin, and Schema Registry. -* **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. +Choose one method per API: -=== Kafka 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. -When user impersonation is enabled, the logged-in user's credentials are used for authentication. +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. -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: "console-superuser" + password: "superuser-password" + mechanism: "SCRAM-SHA-256" authorization: - roleBindings: <5> + roleBindings: - roleName: viewer users: - loginType: basic - name: "static-kafka-user" + name: "matt" ---- -<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: "console-superuser" + password: "superuser-password" authorization: roleBindings: - roleName: editor users: - loginType: basic - name: "static-sr-user" + name: "matt" ---- -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 + 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 +[,yaml] +---- +redpanda: + adminApi: + enabled: true + urls: ["http://broker1:9644"] + authentication: + impersonateUser: false + bearerToken: "" +authorization: + roleBindings: + - roleName: admin + users: + - loginType: oidc + name: "" ---- -Use xref:console:config/configure-console.adoc#environment-variables[environment variables] or command-line flags for sensitive data. +[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. +==== + +== Authorization overview -For more information on role bindings, see xref:console:config/security/authorization.adoc[]. +Authentication allows users to log in, but authorization determines what they can do once authenticated. -== Next steps +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. -- xref:console:config/security/authorization.adoc[Redpanda Console Authorization] +[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] +- 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..49ece3aca5 100644 --- a/modules/console/pages/config/security/authorization.adoc +++ b/modules/console/pages/config/security/authorization.adoc @@ -1,21 +1,131 @@ = Authorization -:description: Redpanda Console uses role-based access control (RBAC) to restrict system access to authorized users. +: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 - -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. +:page-categories: Security, Management, 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[]. +{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 disabled (`impersonateUser: false`) +| Redpanda Console evaluates permissions using role bindings defined in its configuration. Redpanda sees all requests as coming from a static service account. + +| Impersonation enabled (`impersonateUser: true`) +| Redpanda evaluates permissions using its internal RBAC and ACLs. Any role bindings in the Redpanda Console configuration are ignored. +|=== + +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]. + +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) + +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. +- Redpanda Console roles and RBAC are not enforced. +- It can be 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 + +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. +- 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 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 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. -Redpanda Console comes with the following roles: +.Do you have user impersonation enabled? +[%collapsible] +==== +Redpanda Console roles are not used when user impersonation is enabled for an API. When impersonation is enabled, the user's identity is forwarded to Redpanda, which then authorizes access based on RBAC and ACL rules. + +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. + +[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: [cols="1a,3a,3a", options="header"] |=== @@ -27,7 +137,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,110 +146,117 @@ 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. - == 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. +When impersonation is disabled, Redpanda Console connects to Redpanda APIs using the service account defined in: -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`: +- `kafka.sasl`: For the Kafka API +- `schemaRegistry.authentication`: For the Schema Registry API +- `redpanda.adminApi.authentication`: For the Admin API -.Example role bindings -[,yaml] +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> -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 - - 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. +rpk cluster config set superusers '["console-superuser"]' \ + -X user= -X pass= ---- -<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. -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: +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. + +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. + +=== Example: Assign the Viewer role + +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. -.Role bindings ignored [,yaml] ---- kafka: brokers: ["broker1.example.com:9092"] sasl: enabled: true - impersonateUser: true <1> -authentication: <2> - jwtSigningKey: secret-key - useSecureCookies: false + impersonateUser: false # <1> + 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: "" basic: - enabled: true <2> -# Role bindings are ignored because the user is impersonated for the Kafka API. + enabled: true authorization: - roleBindings: - - roleName: admin - users: - - loginType: basic - name: name: Peter <3> + roleBindings: # <2> + - roleName: viewer + users: + - loginType: basic + name: matt ---- +<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. -<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. +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. -[[union]] -=== Multiple roles and duplicate role bindings +== Multiple roles and duplicate bindings -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. +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. -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] +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/get-started/pages/quick-start.adoc b/modules/get-started/pages/quick-start.adoc index 93ad59034c..0cdba4893f 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[] @@ -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/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..8ae9df3214 100644 --- a/modules/manage/partials/authentication.adoc +++ b/modules/manage/partials/authentication.adoc @@ -34,6 +34,38 @@ 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*: + +- 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 who 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, they have 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 +93,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 +400,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. @@ -382,7 +410,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. @@ -813,13 +841,14 @@ 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. 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 @@ -1295,23 +1324,52 @@ endif::[] == Authentication for the HTTP APIs -The following HTTP APIs support basic authentication and OIDC authentication: +Redpanda provides the following 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. -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: +==== Admin API permissions -* *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. +The Admin API primarily requires superuser privileges, with a few exceptions for read-only status endpoints. + +For a complete list of all Admin API endpoints, see see xref:api:ROOT:admin-api.adoc[]. + +==== 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: + + +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`]. +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 +1481,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 +1521,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 +1562,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 +1673,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 +1713,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.] diff --git a/modules/manage/partials/security/oidc/limitations.adoc b/modules/manage/partials/security/oidc/limitations.adoc new file mode 100644 index 0000000000..26a429b0b6 --- /dev/null +++ b/modules/manage/partials/security/oidc/limitations.adoc @@ -0,0 +1,12 @@ +== OIDC limitations + +- 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 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 cacb98e022..028073847e 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 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. 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 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. + +[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] +---- +# Viewer role in Redpanda Console -> Redpanda ACLs +rpk security acl create \ + --allow-principal User:alice@example.com \ + --operation read,describe \ + --topic '*' \ + --group '*' + +# Editor role in Redpanda Console -> Redpanda ACLs +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 '*' + +# Admin role in Redpanda Console -> Redpanda superuser +rpk cluster config set superusers "['alice@example.com']" +---- + +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. 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" } }