Phoenix SaaS Tenant Onboarding

Copy Markdown View Source

Scenario

A Phoenix SaaS app wants one safe Day-1 path for onboarding a new enterprise tenant. The host team needs to scaffold Relyra, prove a local login with FakeIdP, then connect exactly one first-class provider before the tenant is considered live.

Exact wiring and config

  • Run mix relyra.install --module MyApp --repo MyApp.Repo
  • Mount the ACS route and any host-specific router seams the installer prints
  • Prove the local path first with Relyra.TestSupport.FakeIdP
  • Pick one first-class provider runbook: guides/recipes/okta.md, guides/recipes/entra.md, or guides/recipes/google_workspace.md
  • Keep any non-preset tenant requests under an explicitly labeled custom/generic SAML path

Relyra owns

  • The preset contract for Okta, Microsoft Entra ID, and Google Workspace
  • The local-first proof helpers in Relyra.TestSupport
  • Strict protocol validation, trust-boundary enforcement, and typed rejection behavior

Host owns

  • Tenant provisioning workflow and authorization policy
  • Router mounting, session management, and downstream account linking
  • Deployment configuration, secrets, and domain ownership

Failure and recovery

  • Failure: the local FakeIdP proof fails before a real provider is involved Recovery: stop there and fix the host integration before touching provider admin work
  • Failure: the provider login fails due to entity ID, ACS, or certificate drift Recovery: return to the chosen runbook and reconcile the exact vendor fields
  • Failure: a tenant requests an unsupported provider and the team treats it like a shipped preset Recovery: relabel it as custom/generic SAML and scope the extra mapping and verification work explicitly

Evidence

  • Passing local proof based on Relyra.TestSupport.FakeIdP
  • One successful real-provider login for the tenant
  • The selected runbook's receipt and host-side configuration notes