Skip to content

docs: draft enterprise SSO via Ory section DEP-139#36958

Draft
bobbyiliev wants to merge 1 commit into
MaterializeInc:mainfrom
bobbyiliev:bobby/dep-139-ory-docs-draft
Draft

docs: draft enterprise SSO via Ory section DEP-139#36958
bobbyiliev wants to merge 1 commit into
MaterializeInc:mainfrom
bobbyiliev:bobby/dep-139-ory-docs-draft

Conversation

@bobbyiliev

Copy link
Copy Markdown
Contributor

Draft of the user-facing docs for the Ory-based enterprise SSO stack, the docs counterpart to DEP-19 and DEP-139. Marked draft because there are still open dependencies on:

  • The Polis follow-up PR (materialize-terraform-self-managed#223) landing, plus the three Ory-side asks tracked there (multi-arch image, public chart, TLS termination) so the docs don't ship temporary workarounds we'll remove next iteration.
  • GCP and AWS install pages, which are intentionally not yet drafted; gated on SAS-120 and SAS-121 landing so the docs match the actual example shape.
  • Migration guide (direct OIDC -> Ory) draft, blocked on a handful of questions about oidc_issuer flip semantics that need backend input first.

What's in this PR

self-managed-deployments/enterprise-sso/
  _index.md                    architecture + when to use the Ory path
  prerequisites.md             license key, OEL proxy, DNS, cert-manager, Polis caveats
  install-on-azure.md          end-to-end Azure walk-through (the tested path)
  identity-providers.md        Direct OIDC, SAML via Polis, SCIM via Polis
  operations.md                Day-2: add OAuth2 clients, rotate license key, manage identities
  troubleshooting.md           symptom -> cause -> fix table + detailed walkthroughs

security/self-managed/
  sso-ory.md                   user-facing SSO usage page, sibling to the existing sso.md

About 1300 lines across seven files. Mostly distilled from the end-to-end testing of the Azure enterprise example on bobby.sh, the SCIM + SAML smoke tests against Okta, and the workarounds documented in materialize-terraform-self-managed's ORY_SETUP_NOTES.md and OKTA_SETUP_NOTES.md.

What I'd love feedback on

  • Page split (overview / prerequisites / per-cloud install / identity providers / operations / troubleshooting): scopes feel right, but the boundary between identity-providers.md and sso-ory.md is a bit fuzzy. Open to consolidation if the split feels arbitrary.
  • Voice and depth: the docs lean technical, assume reader is the operator deploying the stack, not the end user. Matches the existing installation/install-on-* pages but worth a sanity check.
  • Cross-references to upstream Ory docs: I lean out for deep concepts (identity schemas, SCIM RFCs) but re-explain only what's needed for our setup. Right balance?
  • Anything missing that customers will hit. The troubleshooting table is lifted from real e2e debugging; if anyone has hit other failure modes when deploying Ory, drop them here and I'll fold them in.

Not in this PR yet

  • GCP and AWS install pages (placeholder; depends on SAS-120 / SAS-121)
  • Migration guide (sso-ory-migration.md); needs backend input on issuer-flip semantics
  • The sso.md limitations callout that should point at sso-ory.md once this lands

Render preview

[link to docs preview once Vercel build is up]

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant