docs: explain editable SAML audience (CUB-2546)

[MikeNitsenko]

Summary

• document the mapping between Cube's Single Sign-On URL, Audience, and IdP service-provider identifiers
• add explicit Amazon Federate guidance for its single Entity ID/Audience field
• correct Google Workspace guidance that previously instructed users to clear Audience
• update Okta and Microsoft Entra setup instructions and add migration-safe notes
• remove stale Cube settings screenshots instead of documenting obsolete UI

Compatibility

Existing working integrations are told not to change. Blank Audience remains documented as a compatibility mode that disables validation; enabling validation requires changing both sides and testing with a fallback authentication method enabled.

Ticket: https://linear.app/cube-d3/issue/CUB-2546/support-aws-federate-for-sso-setup

Validation

• git diff --check
• Mintlify dependency installation was attempted twice, but the registry timed out while fetching optional sharp platform packages; CI should run the docs build and link checker.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
cubed3	🟢 Ready	View Preview	Aug 31, 2026, 9:24 AM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[claude]

Claude finished @MikeNitsenko's task in 1m 42s —— View job

---

Docs review: SAML audience guidance

Verdict: looks good to merge after a few small edits — 0 blocking, 2 medium, 2 low. Content is accurate and internally consistent; findings are structure/wording only. 4 inline comments posted.

Full review

Checklist

• Gather context (diff vs origin/master, all 4 files, cross-references)
• Verify field-name consistency across the four SSO pages
• Check for broken anchors / removed-image references
• Post inline comments and summary

What works well

• Field labels on the Google page now match Okta (okta/saml.mdx:107-109) and Entra (microsoft-entra-id/saml.mdx:113-123): Entity ID / Issuer, SSO (Sign on) URL, Certificate. The old page used a third naming scheme (IdP Issuer, Identity Provider Login URL), so this is a real consistency fix.
• The reversal of "Delete the prefilled value and leave empty" is the substantive correction here, and the compatibility framing (blank Audience = validation disabled, existing integrations unaffected) is handled consistently on all four pages.
• Migration notes consistently advise keeping a fallback auth method and testing before cutover — good, that's the failure mode that locks admins out.
• Renaming the second Google ## Enable SAML in Cube Cloud to ## Complete SAML configuration in Cube Cloud removes a duplicate-anchor collision. I verified the surviving cross-reference at google-workspace.mdx:152 (#enable-saml-in-cube-cloud) still resolves to the first heading, which is the section that shows the SSO URL — so it points to the right place.
• No remaining references anywhere in docs-mintlify to the three removed ucarecdn.com screenshots.

Findings

#	Severity	File	Issue
1	Medium	admin/sso/index.mdx:63	New #### Match SAML service provider identifiers is inserted above "Check the following guides…" + <CardGroup>, so the provider cards now nest under that subsection in the page nav instead of under ### SAML.
2	Medium	microsoft-entra-id/saml.mdx:64	For a new integration the recommended values make Entity ID = Reply URL = Audience, so the audience claim override step becomes a no-op. Suggest scoping it to "only when the Audience differs from the Entity ID".
3	Low	google-workspace.mdx:25	Missing the "For a new integration, …" qualifier that Okta and Entra use; the caveat only appears at the bottom of the page.
4	Low	google-workspace.mdx:73	Pre-existing duplicate 5. in the ordered list, in a block this PR touched.

Verify with the product before merging

• The claim that a blank Audience disables audience validation (index.mdx:46) is Cube Cloud behavior not visible in this repo — worth a confirmation from whoever owns the SAML backend, since it's now stated as fact on four pages.
• The old Google page said the Audience field is prefilled. The new guidance tells users to set it to the SSO URL. If the UI still prefills something else, a one-line "overwrite the prefilled value" would save confusion.
• Cosmetic, out of scope: index.mdx:7 has a stray Authentication & SSO line (leading space, looks like a heading that lost its ##). Pre-existing.

Notes on the PR description

The Mintlify build/link check didn't run locally per the description. I did not run it either (dependency install is the same blocker); the anchor and image checks above were done by grep across docs-mintlify, not by the link checker. CI should still validate.

• branch `codex/cub-2546-saml-audience-docs`

[MikeNitsenko]

Implementation PR: https://github.com/cubedevinc/cubejs-enterprise/pull/14576

[claude]

Claude finished @MikeNitsenko's task in 47s —— View job

---

Re-review after 5a56182 — all 4 prior findings addressed, no new issues (0 blocking)

Full review

Checklist

• Diff the updated branch against origin/master
• Verify each of the 4 findings from the previous review
• Re-check anchors and removed-image references
• Resolve stale review threads

Findings from the previous review

#	Prior finding	Status
1	index.mdx — new #### subsection nested the provider cards under it	Fixed — #### Match SAML service provider identifiers now sits after the <CardGroup> (admin/sso/index.mdx:46), so the cards stay directly under ### SAML
2	Entra audience claim override was a no-op for new integrations	Fixed — step 3 is now conditional: "If the Audience (SP Entity ID) value from Cube differs from the Entity ID configured in the previous step… If the values match, no audience claim override is required." (microsoft-entra-id/saml.mdx:62-65)
3	Google page missing the "For a new integration" qualifier	Fixed — google-workspace.mdx:25; also picks up the prefill nuance I flagged separately ("replace any prefilled … value")
4	Duplicate 5. in the Google ordered list	Fixed — renumbered to 6. / 7. (google-workspace.mdx:72-74)

All four threads are now resolved (three were auto-resolved by the push; I resolved the outdated Entra one).

Verification I re-ran

• #enable-saml-in-cube-cloud at google-workspace.mdx:152 still resolves — the first ## Enable SAML in Cube Cloud heading (line 18) is intact; only the second duplicate heading was renamed to ## Complete SAML configuration in Cube Cloud.
• No remaining references anywhere in docs-mintlify to the three removed ucarecdn.com screenshots, nor to the old Service Provider Entity ID label.
• Ordered-list numbering is now sequential on all touched lists.
• Field labels are consistent across the four pages: Audience (SP Entity ID) / Single Sign-On URL on the Cube side, Entity ID / Issuer, SSO (Sign on) URL, Certificate on the IdP side.

Still worth a product confirmation before merge (unchanged from last review, not a code issue)

• "A blank Audience disables audience validation" is now stated as fact on four pages (index.mdx:55-58, google-workspace.mdx:108). That behavior lives in the enterprise repo, not here — worth a nod from whoever owns the SAML backend (implementation PR presumably covers it).
• Cosmetic and pre-existing, out of scope: admin/sso/index.mdx:7 has a stray Authentication & SSO line with a leading space that looks like a heading that lost its ##.

Not run

Mintlify build / link checker — dependency install is the same blocker described in the PR body. Anchor and image checks above were done by grep across docs-mintlify. CI should still validate.

• branch [`codex/cub-2546-saml-audience-docs`](https://github.com/cube-js/cube/tree/codex/cub-2546-saml-audience-docs)