From 3b523ce01ad2b7e46fd9807e7aef7675e3c9e0ab Mon Sep 17 00:00:00 2001 From: David Yu Date: Wed, 24 Jun 2026 14:56:12 -0700 Subject: [PATCH] manage: document rpk OAUTHBEARER (OIDC) for Kafka/Admin/SR APIs [v/25.2 backport] Ports the rpk OAUTHBEARER docs from main (the OIDC work that #1762 refines) to v/25.2, since rpk OAUTHBEARER support (redpanda-data/redpanda#30169) was backported to the v25.2.x release line: - rpk -X reference: OAUTHBEARER sasl.mechanism note + user/pass guidance. - authentication partial: add the "Connect to Redpanda with OIDC using rpk" section (incl. a "Validate OIDC authentication" step); correct three stale "rpk only supports basic auth for the Admin API" notes. GBAC and sasl_mechanisms_overrides xrefs are dropped, as neither exists on v/25.2 (sasl_mechanisms_overrides is a v25.3+ property). - netlify.toml: pin NODE_VERSION=20 so the new Netlify build image builds the preview. Co-Authored-By: Claude Opus 4.8 (1M context) --- modules/manage/partials/authentication.adoc | 81 ++++++++++++++++++- .../reference/pages/rpk/rpk-x-options.adoc | 10 ++- netlify.toml | 3 + 3 files changed, 87 insertions(+), 7 deletions(-) create mode 100644 netlify.toml diff --git a/modules/manage/partials/authentication.adoc b/modules/manage/partials/authentication.adoc index 1b7c57edad..533a1608e0 100644 --- a/modules/manage/partials/authentication.adoc +++ b/modules/manage/partials/authentication.adoc @@ -405,7 +405,7 @@ Before enabling authorization in Redpanda, which can happen implicitly when you 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. -A superuser can either be a SCRAM user or it can be provided by external authentication mechanisms, such as OIDC. However, `rpk` can only communicate with the Admin API using HTTP basic authentication, which requires a SCRAM user. This means that for administrative tasks executed through `rpk`, you must have a SCRAM user with superuser privileges. +A superuser can either be a SCRAM user or it can be provided by external authentication mechanisms, such as OIDC. For administrative tasks executed through `rpk`, you can authenticate to the Admin API either with a SCRAM superuser (HTTP basic authentication) or, starting with `rpk` v26.1.7, with an OIDC access token (`-X sasl.mechanism=OAUTHBEARER`) whose principal has superuser privileges. . Specify the username of a superuser. + @@ -1130,6 +1130,81 @@ rpk cluster config set oidc_keys_refresh_interval 3600 ---- endif::[] +[[oidc-rpk]] +===== Connect to Redpanda with OIDC using rpk + +Starting with `rpk` v26.1.7 (also available in v25.3.x and v25.2.x patches), `rpk` supports the `OAUTHBEARER` SASL mechanism for Kafka API authentication. After you enable OIDC on a Kafka listener, you can authenticate `rpk` to Kafka with an OIDC access token issued by your IdP instead of a SASL/SCRAM username and password. + +NOTE: Confirm your `rpk` version with `rpk version`. Earlier versions reject `-X sasl.mechanism=OAUTHBEARER` as an unknown mechanism. + +Before you connect, make sure that: + +* `OAUTHBEARER` is in xref:reference:properties/cluster-properties.adoc#sasl_mechanisms[`sasl_mechanisms`]. +* You have an access token from your IdP whose claims satisfy `oidc_token_audience`, `oidc_discovery_url`, and `oidc_principal_mapping`. For the claims that Redpanda validates, see <>. +* xref:manage:security/authorization/index.adoc#acls[ACLs] grant the principal extracted from the token the operations you intend to run. + +[[oidc-rpk-token]] +Pass the token using xref:reference:rpk/rpk-x-options.adoc[`-X` options]. Set `sasl.mechanism=OAUTHBEARER` and supply the token through `pass`, either as a raw value or in `token:` form: + +[,bash] +---- +export OIDC_TOKEN="" + +rpk topic list \ + -X brokers=: \ + -X tls.enabled=true \ + -X tls.ca= \ + -X sasl.mechanism=OAUTHBEARER \ + -X pass="token:$OIDC_TOKEN" +---- + +The same `-X sasl.mechanism` and `-X pass` options work for any `rpk` command that talks to the Kafka API (for example, `rpk topic create`, `rpk topic produce`, `rpk topic consume`, `rpk group list`, `rpk cluster info`, and `rpk security acl list`). + +Because `rpk` applies the same SASL configuration to its Admin API and Schema Registry clients, the same OIDC token also authenticates Admin API requests (for example, `rpk cluster health`) and Schema Registry requests when those listeners have OIDC enabled. + +To avoid repeating connection flags, store them in an xref:reference:rpk/rpk-profile/rpk-profile-create.adoc[`rpk profile`]: + +[,bash] +---- +rpk profile create oidc \ + --set kafka_api.brokers=: \ + --set kafka_api.tls.ca_file= \ + --set kafka_api.sasl.mechanism=OAUTHBEARER \ + --set kafka_api.sasl.password="token:$OIDC_TOKEN" + +rpk topic list +---- + +[[oidc-rpk-validate]] +===== Validate OIDC authentication + +To confirm that OIDC authentication works end to end, run a read-only command against the OIDC listener and verify that it succeeds: + +[,bash] +---- +rpk cluster info \ + -X brokers=: \ + -X tls.enabled=true \ + -X tls.ca= \ + -X sasl.mechanism=OAUTHBEARER \ + -X pass="token:$OIDC_TOKEN" +---- + +A successful response lists the cluster's brokers and topics, which confirms that Redpanda validated the token's signature and claims, mapped it to a principal, and authorized the request. + +If the command fails instead, use these checks: + +If `rpk` returns `OAUTHBEARER requires a token`, the password is empty or contains only the `token:` prefix with no value. + +If the broker rejects the token, verify that: + +* The `aud` claim matches `oidc_token_audience` +* The `iss` claim matches the issuer at `oidc_discovery_url` +* `exp` is in the future within `oidc_clock_skew_tolerance` +* The signature is valid against the JWK set published at the discovery URL + +See <> for the full list of validated claims. + ifndef::env-kubernetes[] [[kerberos]] ==== GSSAPI (Kerberos) @@ -1467,7 +1542,7 @@ To enable basic authentication for the Admin API: . <> so that you can use `rpk` to create ACLs. + -`rpk` supports only basic authentication for the Admin API. +`rpk` v26.1.7+ can authenticate to the Admin API with an OIDC access token (`-X sasl.mechanism=OAUTHBEARER`); earlier versions support only HTTP basic authentication, which requires a SCRAM user. . Enable authentication for the Admin API: + @@ -1589,7 +1664,7 @@ You can configure the HTTP APIs to authenticate users with the OIDC bearer token See <> to configure the required OIDC cluster configuration properties before enabling OIDC for the HTTP APIs. You can configure OIDC without enabling it for the Kafka API. -NOTE: If you enable OIDC authentication for the Admin API, you must also <> so that you can use `rpk` to create ACLs. `rpk` supports only basic authentication for the Admin API. See <>. +NOTE: To run administrative `rpk` commands against the Admin API when OIDC is enabled, either use an OIDC access token whose principal is a superuser (`rpk` v26.1.7+ supports `-X sasl.mechanism=OAUTHBEARER` for the Admin API) or <>. See <>. To enable OIDC for the HTTP API listeners as well as basic authentication, include OIDC in the `http_authentication` cluster property list: diff --git a/modules/reference/pages/rpk/rpk-x-options.adoc b/modules/reference/pages/rpk/rpk-x-options.adoc index 5fef740d1b..273c918db8 100644 --- a/modules/reference/pages/rpk/rpk-x-options.adoc +++ b/modules/reference/pages/rpk/rpk-x-options.adoc @@ -238,13 +238,15 @@ The SASL mechanism to use for authentication. *Default*: "" -*Acceptable values*: `SCRAM-SHA-256`, `SCRAM-SHA-512`, `PLAIN` +*Acceptable values*: `SCRAM-SHA-256`, `SCRAM-SHA-512`, `PLAIN`, `OAUTHBEARER` NOTE: With Redpanda, the Admin API can be configured to require basic authentication with your Kafka API SASL credentials. This defaults to `SCRAM-SHA-256` if no mechanism is specified. +For `OAUTHBEARER`, set `pass` to an OIDC access token (raw value, or prefixed with `token:`) instead of a SASL password, and leave `user` unset. `rpk` uses this mechanism and token for its Kafka API, Admin API, and Schema Registry clients, so the same token authenticates all three when the corresponding listeners have OIDC enabled. Support for `OAUTHBEARER` was added in rpk v26.1.7 (also backported to v25.3.x and v25.2.x). For end-to-end steps, see xref:manage:security/authentication.adoc#oidc-rpk[Connect to Redpanda with OIDC using rpk]. + *Example*: `sasl.mechanism=SCRAM-SHA-256` -*Usage*: +*Usage*: ``` rpk topic list -X sasl.mechanism= ``` @@ -253,7 +255,7 @@ rpk topic list -X sasl.mechanism= === user -The SASL username to use for authentication. It's also used for the Admin API if you have configured it to require basic authentication. +The SASL username to use for authentication. It's also used for the Admin API if you have configured it to require basic authentication. The `OAUTHBEARER` mechanism does not use `user`; leave it unset and pass the token through <>. *Type*: string @@ -270,7 +272,7 @@ rpk topic list -X user= === pass -The SASL password to use for authentication. It's also used for the Admin API if you have configured it to require basic authentication. +The SASL password to use for authentication. It's also used for the Admin API if you have configured it to require basic authentication. For the `OAUTHBEARER` mechanism, set `pass` to an OIDC access token (a raw token, or one prefixed with `token:`) rather than a SASL password. See <>. *Type*: string diff --git a/netlify.toml b/netlify.toml new file mode 100644 index 0000000000..7adb8e7d8b --- /dev/null +++ b/netlify.toml @@ -0,0 +1,3 @@ +[build.environment] +NODE_VERSION = "20" +NODE_OPTIONS = "--max-old-space-size=6144"