Distinguish between the two ways to enable SASL

[vuldin]

Description

This PR makes it clear there are two ways to enable SASL, explains what they are, when to choose one or the other, and why we even have two ways to begin with (why not just one?), and which is the recommended path for new clusters.

Page previews

https://deploy-preview-1562--redpanda-docs-preview.netlify.app/current/manage/security/authentication/

Checks

• New feature
• Content gap
• Support Follow-up
• Small fix (typos, links, copyedits, etc)

[netlify]

✅ Deploy Preview for redpanda-docs-preview ready!

Name	Link
🔨 Latest commit	1a809fc
🔍 Latest deploy log	https://app.netlify.com/projects/redpanda-docs-preview/deploys/6a0f422c6620ee0008cef9a8
😎 Deploy Preview	https://deploy-preview-1562--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]

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: d1b67495-a128-4641-86fb-a8af3eda9b78

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 change updates the authentication documentation in modules/manage/partials/authentication.adoc. It restructures the SASL authentication section to explicitly present two distinct methods with separate prerequisites, commands, and warnings. A new troubleshooting chapter is added to address Schema Registry 403 Forbidden errors with diagnosis and resolution steps. The OIDC and HTTP API authentication sections are expanded with conditional guidance based on deployment environment and additional examples. A security reporting section is appended referencing a cluster-wide reporting endpoint.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Suggested reviewers

• rpdevmp
• kbatuigas

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Description check	❓ Inconclusive	The PR description addresses the content gap and provides clear context about the changes, but lacks the JIRA ticket reference and page preview URL.	Fill in the JIRA ticket ID (currently placeholder) and confirm the page preview URL is accurate for the authentication documentation changes.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title directly matches the main change: clarifying two distinct methods to enable SASL authentication, which is the central focus of the documentation rework.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

Warning

Review ran into problems

🔥 Problems

Errors were encountered while retrieving linked issues.

Errors (1)

• PREVIEW-487: Request failed with status code 404

---

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 and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@modules/manage/partials/authentication.adoc`:
- Around line 548-554: The cross-reference to enable-sasl-authentication is
broken because that anchor isn’t present; fix it by either adding the missing
anchor id "enable-sasl-authentication" immediately above the relevant heading
(so the xref resolves) or update the xref to point to an existing anchor/ID used
in this document (for example the actual heading ID for SASL enablement or the
authentication section); ensure the xref text remains
"enable-sasl-authentication" or change it to the correct existing ID and verify
the xref renders.

[Feediver1]

Hi @vuldin,
Are you okay with me pushing these updates from the review? Thinking I need to do another pass, but would like to see the first pass comments resolved first. thx

[vuldin]

Hi @Feediver1 , I think I've handled all feedback up to this point (with one minor question in a comment above).

[mattschumpert]

@vuldin @Feediver1 the only thing not clear to me here is emphatically saying "the cluster configuration enable_sasl:true". It's all about these 'two methods' but WHERE do I set enable_sasl. That's a cluster config. It says it in the rpk command but in a bunch of other places it doesn't.

Specifically, one method is setting a cluster config. The other is editing the redpanda.yaml I think (listener method). Can we be even clearer about that

[Feediver1]

Pushed a follow-up commit (e557ceb) applying the style fixes from my earlier review. Summary of changes — all in the new SASL sections, no existing content touched:

Accessibility

• Replaced ✅ / ❌ emoji with explicit *Advantages:* / *Limitations:* labels in both trade-off lists. Screen readers announce emoji inconsistently across platforms, and the labels carry the same meaning.

Style

• Sentence-cased the decision-table column headers (Use case / Recommended authentication method / Reasons to use).
• Dropped the (s) parenthetical in the column header.
• Provides you the flexibility → Lets you configure (more direct).
• Present tense in the "Use this option when:" bullets (will use → use).
• Added end punctuation to bullet lists for consistency.
• Fixed the double space after the leading * on the first bullet.

Formatting

• Normalized new [source,bash|yaml|json|text] blocks to the [,lang] shorthand that the rest of this partial already uses.
• [source,log] → [,text] (log isn't a recognized Rouge highlighter, would cause a build warning).

Structure

• Renamed == Troubleshooting authentication → == Authentication and authorization troubleshooting since the new entry is actually about Schema Registry authorization (ACL initialization for the schema_registry_internal role).
• Added an intro sentence under the H2 so it isn't an empty parent section above its one child.

I did not touch the Schema Registry troubleshooting entry's location — it stays in this partial. If the team decides later that it belongs in manage/schema-reg/schema-reg-authorization.adoc instead, that's a separate move.

Co-authored-by: Claude Code (Opus 4.7 1M).

[micheleRP]

Final-pass review

Two items worth resolving before merge. Skipping smaller style nits since the content has already had many review rounds.

Critical — Schema Registry 403 section also renders on the Kubernetes page

This partial is included by both modules/manage/pages/security/authentication.adoc (Linux) and modules/manage/pages/kubernetes/security/authentication/k-authentication.adoc (Kubernetes — sets :env-kubernetes: true).

In the final file, the new troubleshooting block sits outside any ifndef::env-kubernetes[] gate:

2057: endif::[]                                          <-- closes the prior ifndef
2058:
2059: == Authentication and authorization troubleshooting
2063: === Schema Registry 403 Forbidden errors
...
2157: == Generate security report                        <-- still no gate

Result: the K8s docs page will also show the section, with a resolution that ends in systemctl restart redpanda. That command doesn't apply on Kubernetes (where restarts happen via kubectl rollout restart or the Redpanda Operator).

Fix options:

• Wrap the new H2 in ifndef::env-kubernetes[] … endif::[] if this is binary-install–only guidance, or
• Rewrite the resolution to be platform-agnostic (e.g., "restart the cluster" with xrefs to both the Linux and Kubernetes restart procedures).

Suggestion — be explicit about where each method is configured

@mattschumpert raised this in March and I don't think the current wording fully addresses it. The intro list says what the two options are, but not where each one lives — the reader has to infer from the rpk command vs. the redpanda.yaml snippet later.

Consider tightening the intro bullets so the location is in the definition:

* *`enable_sasl`*: A cluster-configuration property (set with `rpk cluster config set enable_sasl true`). A legacy (not deprecated) approach maintained for backwards compatibility…
* *Per-listener configuration*: Listener settings in each broker's `redpanda.yaml`. A more flexible approach that lets you configure different authentication methods on different listeners.

That makes the "cluster config vs. broker config file" distinction land before the reader gets into the per-method sections.