manage/rpk: document OAUTHBEARER (OIDC) for Admin API + Schema Registry, add validation step

[david-yu]

What

Builds on the recently-added OIDC + rpk OAUTHBEARER docs to cover the rest of redpanda-data/redpanda#30169, and adds an explicit validation step on the OIDC page.

#30169 added the OAUTHBEARER SASL mechanism to rpk's Kafka, Admin API, and Schema Registry clients (token passed via --password / -X pass, as token:<TOKEN> or a raw token). The existing OIDC docs described only the Kafka API, and two notes still claimed rpk can use only HTTP basic auth for the Admin API.

Changes

modules/manage/partials/authentication.adoc (shared partial — renders on both the standard and Kubernetes authentication pages):

• Note that the same -X sasl.mechanism=OAUTHBEARER / -X pass token also authenticates Admin API and Schema Registry requests when those listeners have OIDC enabled.
• Add a "Validate OIDC authentication" subsection ([[oidc-rpk-validate]]): run rpk cluster info against the OIDC listener, what a successful response confirms, with the existing token-rejection checklist reframed as the failure branch.
• Correct two now-stale claims that "rpk supports only basic authentication for the Admin API." #30169 lets rpk send an OIDC bearer token to the Admin API (rpadmin.BearerToken), and the Admin API supports OIDC server-side (per the "Authentication for the HTTP APIs" section).

modules/reference/pages/rpk/rpk-x-options.adoc:

• Broaden the sasl.mechanism OAUTHBEARER note to state rpk uses the mechanism and token for its Kafka, Admin API, and Schema Registry clients.
• Cross-reference OAUTHBEARER token handling from the user (leave unset) and pass (holds the OIDC token) options.

Validation

• Delimited blocks balanced; the <<sasl-mechanism>> and <<pass>> xrefs are already used in the page's -X options table.
• Wording reflects the verified behavior in #30169 (adminapi/admin.go, kafka/client_franz.go, schemaregistry/client.go).

Preview pages

• Configure Authentication (updated)
• Configure Authentication for Redpanda in Kubernetes (updated)
• rpk -X (updated)

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Auto incremental reviews are disabled on this repository.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: d056e62a-0f6c-4b32-a5fd-b35ff3515de4

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Documentation in modules/manage/partials/authentication.adoc and modules/reference/pages/rpk/rpk-x-options.adoc is updated to reflect that rpk v26.1.7+ can authenticate to the Admin API and Schema Registry using OIDC access tokens via OAUTHBEARER, in addition to SCRAM. A new "Validate OIDC authentication" section is added with an rpk cluster info command, success/failure diagnostics including the OAUTHBEARER requires a token case, and token claim verification guidance. The rpk -X reference is updated to specify that pass holds the OIDC token, user should be left unset, and the same token applies across Kafka API, Admin API, and Schema Registry listeners.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• redpanda-data/docs#1696: Directly precedes this PR — both update the same authentication.adoc and rpk-x-options.adoc sections for OIDC/OAUTHBEARER rpk usage, setting pass to the token and leaving user unset.
• redpanda-data/docs#1562: Updates the same authentication.adoc file with OIDC and HTTP API authentication guidance, overlapping with the OIDC rpk sections modified here.
• redpanda-data/docs#1115: Touches OIDC limitations and rpk handling in authentication.adoc, the same file and topic area as this PR.

Suggested reviewers

• kbatuigas
• micheleRP
• rockwotj

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The PR description is clear, but it omits required template fields like the Jira ticket, review deadline, and checklist items.	Add the missing template sections: a Jira ticket link, review deadline, page previews in the requested format, and the checks checklist.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the main change: expanding OAUTHBEARER/OIDC docs and adding validation guidance.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch dyu/rpk-oidc-oauthbearer-docs

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[netlify]

✅ Deploy Preview for redpanda-docs-preview ready!

Name	Link
🔨 Latest commit	72499d1
🔍 Latest deploy log	https://app.netlify.com/projects/redpanda-docs-preview/deploys/6a3c4c28ee40a80008505bd9
😎 Deploy Preview	https://deploy-preview-1762--redpanda-docs-preview.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[micheleRP]

Review — LGTM with one follow-up

Content is accurate and well-scoped. It correctly covers the rest of redpanda-data/redpanda#30169 (OAUTHBEARER for the Kafka, Admin API, and Schema Registry clients) and fixes the two now-stale "rpk supports only basic authentication for the Admin API" claims. The new validation step and `-X` option cross-references read cleanly, `#oidc-rpk` resolves on `main`, and the changed content passes a docs-team-standards check (xref syntax, terminology, active voice, heading case all clean).

Follow-up (not blocking): this PR's own text notes OAUTHBEARER "was added in rpk v26.1.7 (also backported to v25.3.x and v25.2.x)." Since the feature ships on `v/25.3` and `v/25.2`, this Admin API + Schema Registry coverage should be backported to both branches too (same as #1761 → #1763). Worth opening those backport PRs so older-version users get the corrected guidance.

[micheleRP]

lgtm