docs: rewrite SAML SSO guide and split into dedicated sub-pages by eedugon · Pull Request #7484 · elastic/docs-content

eedugon · 2026-07-21T13:35:37Z

Closes elastic/docs-content-internal#427

Main preview link: https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/7484/deploy-manage/users-roles/cluster-or-deployment-auth/saml

Summary

The original saml.md had grown into a single monolithic page with 43 sections covering every aspect of SAML configuration — prerequisites, configuration steps, advanced features, reference details, and edge cases — with no clear separation between required and optional content, and no logical ordering that reflected an actual configuration workflow.

This PR restructures the guide into an actionable how-to and moves some parts to dedicated sub-pages.

Scope of changes

saml.md (main guide) has been significantly reworked: restructured as a stepper-based how-to, language improved for clarity, redundancies removed, technical inaccuracies corrected, and advanced sections reordered by relevance.

Sub-pages extracted from the original content have been left with the original text largely intact. They are a starting point and will be improved in follow-up work:

saml-attribute-mapping.md — full attribute mapping reference
saml-signing-encryption.md — signing and encryption guide with certificate generation examples
saml-without-kibana.md — SAML REST API flow for custom applications

Structural changes to `saml.md`

Core configuration wrapped in a stepper with 5 explicit steps: configure IdP → create ES realm → configure Kibana → configure role mappings → test authentication
Advanced configuration section introduced with a framing paragraph so users understand upfront that its subsections are optional and situational
Advanced sections reordered by relevance: signing and encryption first, then SLO, then authentication context, then SP metadata

Notable content corrections

Multiple Kibana instances — Rewritten to make the actual condition explicit: each distinct public URL requires its own SAML realm, regardless of how many nodes or replicas exist behind it. Correctly scoped to self-managed and ECK deployments.

req_authn_context section — Now includes an MFA example using the Entra ID URI with a footnote clarifying that exact values are IdP-specific.

SP metadata curl command — Fixed from http://localhost:9200 (incorrect, SAML requires HTTPS) to https://elasticsearch.example.com:9200 with a footnote.

SLO section — Simplified by removing redundant sub-headings that duplicated content already in the IdP requirements section.

Rewrites saml.md as a streamlined how-to using the stepper component. Moves advanced content (attribute mapping, signing/encryption, SAML without Kibana) to dedicated sub-pages. Updates toc.yml accordingly. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

github-actions · 2026-07-21T13:36:14Z

Elastic Docs AI PR menu

Check the box to run an AI review for this pull request.

Review docs changes (docs-review). Status: not started.

Powered by GitHub Agentic Workflows and docs-actions. For more information, reach out to the docs team.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

- Update saml-entra.md, cloud-enterprise-orchestrator/saml.md and trb-security-saml.md to point to saml-attribute-mapping.md for anchors that moved there (saml-es-user-properties, saml-attribute-mapping-nameid) - Add [saml-kibana-basic] anchor to saml.md for backward compatibility Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

github-actions · 2026-07-21T13:45:30Z

🔍 Preview links for changed docs

github-actions · 2026-07-21T13:45:32Z

Elastic Docs Style Checker (Vale)

Summary: 3 suggestions found

💡 Suggestions (3): Optional style improvements. Apply when helpful.

File	Line	Rule	Message
deploy-manage/users-roles/cluster-or-deployment-auth/saml-attribute-mapping.md	39	Elastic.WordChoice	Consider using 'deactivated, deselected, hidden, turned off, unavailable' instead of 'disabled', unless the term is in the UI.
deploy-manage/users-roles/cluster-or-deployment-auth/saml.md	350	Elastic.WordChoice	Consider using 'deactivate, deselect, hide, turn off' instead of 'disable', unless the term is in the UI.
deploy-manage/users-roles/cluster-or-deployment-auth/saml.md	372	Elastic.Semicolons	Use semicolons sparingly. Consider splitting the sentence or using a comma or conjunction.

The Vale linter checks documentation changes against the Elastic Docs style guide. To use Vale locally or report issues, refer to Elastic style guide for Vale.

- Case-sensitivity warnings on idp.entity_id and sp.entity_id - Attribute URI mismatch warning (most common silent failure) - NameID transient vs persistent gotcha in attributes.principal callout - Clock skew note for assertion validation failures Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…gin section - Add URL/file path note and link to Create SAML realm in IdP requirements section - Remove 'Information to gather' subsection (redundant with Steps 1 and 2) - Convert ECH/ECE/ECK note to proper note admonition - Fix 'with security enabled' link to correct self-setup target - Expand Step 2 with definition list alternative layout (work in progress) - Add sp.acs link to Elasticsearch reference doc Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Make the description self-contained: include the exact URL format, clarify browser reachability, and add the reverse proxy gotcha. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…rsion Update idp.entity_id and sp.acs callout descriptions in the original Step 2 layout to match the improved wording in the alternative version. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…te mapping section - Remove V1 callout layout, promote V2 definition list as the canonical Step 2 - Add correct anchor and title to Step 2 - Rewrite Map SAML attributes subsection: add context paragraph explaining what attributes are, clarify principal (required) vs groups (recommended), keep warning in context rather than as the opening element, enumerate advanced use cases before linking to saml-attribute-mapping.md Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…ctions - Remove leftover eedugon note comment - Replace em-dashes with shorter sentences throughout - Mark attributes.principal (required) and attributes.groups (recommended) directly in definition list terms - Move full settings reference link above the definition list - Consolidate signing note into its own admonition after the order note - Replace "may" with "might" per technical writing conventions Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Use consistent pattern for both: "The URL of the X within Kibana..." with a concrete example URL instead of {kibana-url} placeholder. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

The `order` setting note was a standalone :::{note} block, but `order` is not SAML-specific. Moved it as a <1> footnote on the YAML `order: 2` line for tighter placement without breaking the prose flow. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

The YAML values are self-evidently examples, and the definition list below already explains what each setting requires. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

- Swap steps 3 and 4: Configure Kibana now comes before Configure role mappings - Add Step 5 "Test your configuration" with authenticate API, troubleshooting link - Remove standalone Troubleshooting section (single line, now absorbed into Step 5) - Add restart notes in intros of ES and Kibana steps - Move order footnote, remove redundant "replace example values" sentence - Make settings intro actionable: "Configure each setting as described below" - Link stack-settings to #configure-stack-settings anchor in both steps Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…ference Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

… 1 tip Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…nstances section Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

shainaraskas

super solid. probably most of my comments are on the old stuff - language nits you didn't introduce you can ignore, but we could also make AI quickly fix the tense issues and maybe some of the italics, unplain language, and parentheticals.

buuut imo largely shipit. thank you 👏 👏 👏 👏 👏

stray thoughts:

would be nice if this page linked up to its conceptual home: https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/7484/troubleshoot/elasticsearch/security/trb-security-saml

Co-authored-by: shainaraskas <58563081+shainaraskas@users.noreply.github.com>

- Add contextualization sentence linking to main SAML guide in saml-attribute-mapping.md and saml-signing-encryption.md - Add URN to SingleLogoutService bullet for consistency - Add applies_to tag to Prerequisites for self-managed clusters section - Add intro sentence before Configuration steps stepper - Frontload SP metadata tip in Configure IdP step; convert signing cert note to optional step 7 - Clarify realm settings intro as "most commonly used settings" - Clarify that lower order number means higher priority - Fix "confgired" typo - Improve session timeout sentence to mention per-provider context - Change "Kibana features" to "Kibana privileges" for accuracy - Improve req_authn_context_class_ref link text - Add nameid_format link in saml-attribute-mapping.md - Remove parentheses from saml-signing-encryption.md intro - Add TBD comment for reverse proxy basic auth paragraph Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Create deploy-manage/_snippets/es-file-path-tip.md with generic guidance on configuring file paths in Elasticsearch settings across deployment types (self-managed, ECH, ECE, ECK). Replace three duplicate tip blocks in saml.md and saml-signing-encryption.md with includes of the new snippet. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

- Rewrite TLS prerequisite to mention production mode requirement with link to bootstrap checks, reassure users TLS is enabled in most cases, and follow Shaina's suggestion to put reassurance before action link - Remove parenthetical in basic auth section intro Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…pping doc Add a reference to the full SAML realm settings at the end of the mappable user properties section, so readers can find type info and configuration details for attributes.* settings. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

eedugon requested a review from a team as a code owner July 21, 2026 13:35

eedugon marked this pull request as draft July 21, 2026 13:36

eedugon and others added 2 commits July 21, 2026 15:39

docs: revert H1 title to SAML authentication

554aa93

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

github-actions Bot deployed to docs-preview July 21, 2026 13:47 View deployment

github-actions Bot deployed to docs-preview July 21, 2026 14:05 View deployment

eedugon mentioned this pull request Jul 21, 2026

docs: enrich SAML realm settings in security reference elastic/elasticsearch#154598

Open

github-actions Bot deployed to docs-preview July 21, 2026 17:00 View deployment

eedugon and others added 2 commits July 21, 2026 19:03

docs(saml): improve sp.acs description in alternative Step 2 layout

cfa1570

Make the description self-contained: include the exact URL format, clarify browser reachability, and add the reverse proxy gotcha. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

docs(saml): align Step 2 callout descriptions with definition list ve…

d14297b

…rsion Update idp.entity_id and sp.acs callout descriptions in the original Step 2 layout to match the improved wording in the alternative version. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

github-actions Bot deployed to docs-preview July 21, 2026 17:13 View deployment

eedugon and others added 2 commits July 21, 2026 19:26

docs(saml): replace "via" with "through" throughout

b4203e6

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

github-actions Bot deployed to docs-preview July 21, 2026 17:32 View deployment

github-actions Bot deployed to docs-preview July 21, 2026 19:29 View deployment

docs(saml): align sp.acs and sp.logout descriptions in Step 2

a91b3f4

Use consistent pattern for both: "The URL of the X within Kibana..." with a concrete example URL instead of {kibana-url} placeholder. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

github-actions Bot deployed to docs-preview July 21, 2026 19:34 View deployment

eedugon and others added 3 commits July 22, 2026 14:32

docs(saml): remove redundant "replace example values" sentence

c20e85b

The YAML values are self-evidently examples, and the definition list below already explains what each setting requires. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

docs(saml): make settings intro sentence actionable

f9efa8b

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

github-actions Bot deployed to docs-preview July 22, 2026 12:39 View deployment

github-actions Bot deployed to docs-preview July 22, 2026 13:31 View deployment

github-actions Bot deployed to docs-preview July 22, 2026 21:13 View deployment

docs(saml): rename section to "Allow both SAML and basic authentication"

3f585f8

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

github-actions Bot deployed to docs-preview July 22, 2026 21:18 View deployment

docs(saml): improve attribute mapping link text to signal complete re…

8f22b1d

…ference Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

github-actions Bot deployed to docs-preview July 22, 2026 21:40 View deployment

docs(saml): improve SP metadata section intro, curl example, and step…

2cc3eb7

… 1 tip Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

github-actions Bot deployed to docs-preview July 23, 2026 10:24 View deployment

eedugon marked this pull request as ready for review July 23, 2026 10:34

docs(saml): convert mixed-auth paragraph to note in multiple Kibana i…

c273979

…nstances section Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

github-actions Bot deployed to docs-preview July 23, 2026 10:47 View deployment

eedugon and others added 2 commits July 27, 2026 14:23

docs(saml): fix Vale linter warnings and apply style suggestions

d0f9788

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Merge branch 'main' into saml_sso_refinement

fc68877

github-actions Bot deployed to docs-preview July 27, 2026 12:35 View deployment

shainaraskas approved these changes Jul 29, 2026

View reviewed changes

This comment was marked as duplicate.

Sign in to view

eedugon and others added 5 commits August 6, 2026 16:38

Apply suggestions from code review

e2daf88

Co-authored-by: shainaraskas <58563081+shainaraskas@users.noreply.github.com>

eedugon requested a review from a team August 6, 2026 16:54

Merge branch 'main' into saml_sso_refinement

e7aefe1

github-actions Bot deployed to docs-preview August 7, 2026 05:32 View deployment

n1v0lg requested review from n1v0lg and removed request for n1v0lg August 7, 2026 06:24

eedugon added 2 commits August 13, 2026 10:03

multiple providers refer to and refinement

8e519ef

Merge branch 'main' into saml_sso_refinement

0b60f42

github-actions Bot deployed to docs-preview August 13, 2026 08:10 View deployment

Merge branch 'main' into saml_sso_refinement

5ea8bba

github-actions Bot deployed to docs-preview September 9, 2026 08:01 View deployment

Navigation Menu

Uh oh!

docs: rewrite SAML SSO guide and split into dedicated sub-pages - #7484

docs: rewrite SAML SSO guide and split into dedicated sub-pages#7484
eedugon wants to merge 39 commits into
mainfrom
saml_sso_refinement

eedugon commented Jul 21, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Jul 21, 2026

Uh oh!

github-actions Bot commented Jul 21, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Jul 21, 2026 •

edited

Loading

Uh oh!

shainaraskas left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

This comment was marked as duplicate.

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

eedugon commented Jul 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Scope of changes

Structural changes to saml.md

Notable content corrections

Uh oh!

github-actions Bot commented Jul 21, 2026

Elastic Docs AI PR menu

Uh oh!

github-actions Bot commented Jul 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🔍 Preview links for changed docs

Uh oh!

github-actions Bot commented Jul 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Elastic Docs Style Checker (Vale)

Uh oh!

shainaraskas left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

This comment was marked as duplicate.

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

eedugon commented Jul 21, 2026 •

edited

Loading

Structural changes to `saml.md`

github-actions Bot commented Jul 21, 2026 •

edited

Loading

github-actions Bot commented Jul 21, 2026 •

edited

Loading