Add docs for rpk OIDC (OAUTHBEARER) client authentication by david-yu · Pull Request #1696 · redpanda-data/docs

david-yu · 2026-05-12T05:10:24Z

Summary

Document the client side of OIDC: rpk added OAUTHBEARER SASL mechanism support in v26.1.7 (also v25.3.x and v25.2.x) for the Kafka API, Admin API, and Schema Registry clients.
The existing OIDC section in manage:security/authentication.adoc only covered the broker-side configuration (enabling OAUTHBEARER, setting oidc_discovery_url, etc.) but never showed how a user actually connects with rpk. SCRAM has a "Connect to Redpanda" subsection; this PR adds the parallel one for OIDC.
Updated reference:rpk/rpk-x-options.adoc so OAUTHBEARER appears as an acceptable sasl.mechanism value, with a note about passing the token via pass (raw or token:<TOKEN>).

Source feature PR: redpanda-data/redpanda#30169 (merged 2026-04-22, released in 26.1.7).
Live link: https://deploy-preview-1696--redpanda-docs-preview.netlify.app/current/manage/security/authentication/#oidc-rpk

Changes

modules/manage/partials/authentication.adoc — new [[oidc-rpk]] subsection inside ==== OAUTHBEARER (OIDC) covering prerequisites, the --sasl-mechanism OAUTHBEARER + --password "token:..." invocation, the -X form, an rpk profile create example, and troubleshooting that cross-links back to the existing credentials-flow section.
modules/reference/pages/rpk/rpk-x-options.adoc — adds OAUTHBEARER to Acceptable values for sasl.mechanism and a one-paragraph note pointing to the new how-to.

No new pages, no nav changes.

Test plan

Local Antora build renders both pages without warnings.
[[oidc-rpk]] anchor resolves from the rpk -X reference xref.
Cross-link back to <<oidc, OIDC credentials flow and access token validation>> resolves.
Verify the version note (v26.1.7 / v25.3.x / v25.2.x) is accurate against the final backport landings.

🤖 Generated with Claude Code

rpk added OAUTHBEARER SASL mechanism support in v26.1.7 (also backported to v25.3.x and v25.2.x), letting users authenticate the Kafka, Admin, and Schema Registry clients with an OIDC access token. The existing OIDC section in the authentication guide only covered enabling OAUTHBEARER on the broker; this adds the matching client-side how-to and updates the rpk -X reference so OAUTHBEARER appears as an acceptable sasl.mechanism value. Ref: redpanda-data/redpanda#30169 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

netlify · 2026-05-12T05:10:30Z

✅ Deploy Preview for redpanda-docs-preview ready!

Name	Link
🔨 Latest commit	`8d0bb86`
🔍 Latest deploy log	https://app.netlify.com/projects/redpanda-docs-preview/deploys/6a0382c38232c10009b6565a
😎 Deploy Preview	https://deploy-preview-1696--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.

coderabbitai · 2026-05-12T05:10:39Z

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: 8b0d0782-a063-4322-930d-5683efec07d0

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

This PR updates documentation to support OIDC/OAUTHBEARER SASL authentication with rpk. It adds a comprehensive end-to-end setup guide in the authentication documentation covering rpk version requirements, cluster configuration, token passing syntax with the token:<TOKEN> format, command examples, and troubleshooting steps. It also updates the rpk-x-options reference to document OAUTHBEARER as a valid sasl.mechanism value and provides configuration details for using OIDC access tokens with the -X flag.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

redpanda-data/docs#1306: Both PRs modify rpk -X options documentation and document SASL configuration including sasl.mechanism and credential/token passing via -X and profiles.
redpanda-data/docs#1317: Both PRs modify authentication.adoc to add OIDC-related clarifications for rpk OAUTHBEARER usage and TLS/OIDC/basic-auth guidance.

Suggested reviewers

BenPope
paulohtb6
micheleRP

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The pull request description is well-structured with clear summary, changes, test plan, and context about the upstream feature. However, it lacks the required template sections: missing JIRA ticket link in 'Resolves' header, no page previews provided, and no checkboxes marked for change type.	Add the JIRA ticket reference in 'Resolves' field, include page preview links for both modified documentation files, and check the appropriate box(es) for change type (likely 'Content gap' and/or 'Support Follow-up').

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and specifically describes the main change: adding documentation for rpk OIDC client authentication with the OAUTHBEARER mechanism.
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 docs-rpk-oidc-oauthbearer

Tip

💬 Introducing Slack Agent: The best way for teams to turn conversations into code.

Slack Agent is built on CodeRabbit's deep understanding of your code, so your team can collaborate across the entire SDLC without losing context.

Generate code and open pull requests
Plan features and break down work
Investigate incidents and troubleshoot customer tickets together
Automate recurring tasks and respond to alerts with triggers
Summarize progress and report instantly

Built for teams:

Shared memory across your entire org—no repeating context
Per-thread sandboxes to safely plan and execute work
Governance built-in—scoped access, auditability, and budget controls

One agent for your entire SDLC. Right inside Slack.

👉 Get started

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

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

coderabbitai

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@modules/manage/partials/authentication.adoc`:
- Line 1140: The sentence currently claims that enabling OIDC on a Kafka
listener lets rpk authenticate to the Kafka API, Admin API, and Schema Registry
via OIDC; narrow or clarify this: update the sentence to state that enabling
OIDC on a Kafka listener enables rpk OAUTHBEARER authentication to the Kafka API
only, and either add a separate sentence or a cross-reference that describes the
additional/explicit OIDC requirements for the HTTP-based Admin API and Schema
Registry (e.g., different listener or token audience/configuration), mentioning
the terms rpk, OAUTHBEARER, OIDC, Kafka API, Admin API, and Schema Registry so
readers can find the relevant sections.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

Push a commit to this branch (recommended)
Create a new PR with the fixes

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 52c47a34-f7d2-4366-9089-d25d7dc854e0

📥 Commits

Reviewing files that changed from the base of the PR and between ed6ef56 and bd5d5c1.

📒 Files selected for processing (2)

modules/manage/partials/authentication.adoc
modules/reference/pages/rpk/rpk-x-options.adoc

Remove the paragraph showing -X sasl.mechanism / -X pass equivalents. The --sasl-mechanism / --password form earlier in the section plus the rpk profile example below it cover the relevant ways to pass the token. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>

The previous <<oidc,...>> xrefs jumped to the top of the OAUTHBEARER section instead of the OIDC credentials flow and access token validation subsection they reference. Use the auto-generated oidc-credentials-flow-and-access-token-validation anchor so the link lands at the validated-claims content. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

kbatuigas

One thing before I approve, does this need to go in https://deploy-preview-1696--redpanda-docs-preview.netlify.app/current/get-started/release-notes/redpanda/? If so, we could probably add a new entry after Schema Registry contexts

kbatuigas · 2026-05-12T19:29:05Z

+----
+export OIDC_TOKEN="<access-token>"
+
+rpk topic list \


Could we update this example so that it also uses rpk -X, since we do say that these flags are deprecated?

Co-authored-by: Kat Batuigas <36839689+kbatuigas@users.noreply.github.com>

david-yu requested a review from a team as a code owner May 12, 2026 05:10

coderabbitai Bot reviewed May 12, 2026

View reviewed changes

Comment thread modules/manage/partials/authentication.adoc Outdated

david-yu and others added 4 commits May 11, 2026 23:40

Merge branch 'main' into docs-rpk-oidc-oauthbearer

38d572a

Apply suggestion from @coderabbitai[bot]

e28b526

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>

kbatuigas reviewed May 12, 2026

View reviewed changes

Update modules/manage/partials/authentication.adoc

8d0bb86

Co-authored-by: Kat Batuigas <36839689+kbatuigas@users.noreply.github.com>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add docs for rpk OIDC (OAUTHBEARER) client authentication#1696

Add docs for rpk OIDC (OAUTHBEARER) client authentication#1696
david-yu wants to merge 6 commits into
mainfrom
docs-rpk-oidc-oauthbearer

david-yu commented May 12, 2026 •

edited

Loading

Uh oh!

netlify Bot commented May 12, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot commented May 12, 2026 •

edited

Loading

Review skipped

Walkthrough

Estimated code review effort

Possibly related PRs

Suggested reviewers

❌ Failed checks (1 warning)

Uh oh!

coderabbitai Bot left a comment

Uh oh!

Uh oh!

kbatuigas left a comment

Uh oh!

kbatuigas May 12, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

david-yu commented May 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

Test plan

Uh oh!

netlify Bot commented May 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for redpanda-docs-preview ready!

Uh oh!

coderabbitai Bot commented May 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review skipped

Walkthrough

Estimated code review effort

Possibly related PRs

Suggested reviewers

❌ Failed checks (1 warning)

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

kbatuigas left a comment

Choose a reason for hiding this comment

Uh oh!

kbatuigas May 12, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

david-yu commented May 12, 2026 •

edited

Loading

netlify Bot commented May 12, 2026 •

edited

Loading

coderabbitai Bot commented May 12, 2026 •

edited

Loading