From dc5ff0965b6280e10d27aa24d41962e0064fb0a9 Mon Sep 17 00:00:00 2001 From: David Yu Date: Wed, 24 Jun 2026 09:20:52 -0700 Subject: [PATCH] manage/rpk: document OAUTHBEARER (OIDC) for Admin API + Schema Registry, add validation step redpanda-data/redpanda#30169 added the OAUTHBEARER SASL mechanism to rpk's Kafka, Admin API, and Schema Registry clients. The OIDC docs covered only the Kafka API, and two notes still claimed rpk can use only HTTP basic auth for the Admin API. - authentication partial: note OAUTHBEARER also authenticates Admin API and Schema Registry requests; correct the two stale "rpk supports only basic auth for the Admin API" claims; add a "Validate OIDC authentication" step (rpk cluster info + success criteria, with the existing troubleshooting as the failure branch). - rpk -X reference: broaden the sasl.mechanism note to all three clients; cross-reference OAUTHBEARER token handling from the user and pass options. Co-Authored-By: Claude Opus 4.8 (1M context) --- modules/manage/partials/authentication.adoc | 27 ++++++++++++++++--- .../reference/pages/rpk/rpk-x-options.adoc | 6 ++--- 2 files changed, 27 insertions(+), 6 deletions(-) diff --git a/modules/manage/partials/authentication.adoc b/modules/manage/partials/authentication.adoc index 7d7d89044c..54fa6dcd50 100644 --- a/modules/manage/partials/authentication.adoc +++ b/modules/manage/partials/authentication.adoc @@ -598,7 +598,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. + @@ -1456,6 +1456,8 @@ rpk topic list \ 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] @@ -1469,7 +1471,26 @@ rpk profile create oidc \ rpk topic list ---- -If `rpk` returns `OAUTHBEARER requires a token`, the password is empty or contains only the `token:` prefix with no value. +[[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: @@ -1939,7 +1960,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 6286a8db33..273c918db8 100644 --- a/modules/reference/pages/rpk/rpk-x-options.adoc +++ b/modules/reference/pages/rpk/rpk-x-options.adoc @@ -242,7 +242,7 @@ The SASL mechanism to use for authentication. 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. 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]. +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` @@ -255,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 @@ -272,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