SaaS Adoption Recipe

Use this when you are wiring Lockspire into a real Phoenix SaaS for the first time.

1. Install and mount

Run mix lockspire.install, import config/lockspire.exs, run migrations, and call the generated lockspire_routes/0 helper from your host router.

Keep three boundaries separate:

• Host account routes such as /verify and /authorized-apps stay inside your normal browser/session pipeline.
• Lockspire.Web.AdminRouter must be mounted behind your operator-auth pipeline.
• Lockspire.Web.Router exposes the public OAuth/OIDC protocol surface.

2. Resolve accounts and claims

Implement the generated AccountResolver before shipping.

• Read the signed-in user from host-owned assigns or session state, such as conn.assigns.current_user or conn.assigns.current_scope.user.
• Use a stable subject, for example "user:" <> to_string(user.id).
• Keep default claims narrow: email, name, and other low-risk profile facts only when your product wants to expose them.
• Keep tenant membership, billing, staff/admin status, and product authorization in the host app.

If the host uses Sigra, keep the integration in the generated resolver. Do not add a compile-time dependency from Lockspire to Sigra.

3. Create the first partner client

For a first local proof, use the admin UI, DCR with an initial access token, or:

mix lockspire.client.create \
  --client-type confidential \
  --name "Local Partner App" \
  --redirect-uri "https://partner.example.test/oauth/callback" \
  --scope openid \
  --scope profile \
  --grant-type authorization_code

Store the printed client_secret immediately. Lockspire stores only the secret hash and will not show the plaintext value again.

4. Prove the flow

Before giving credentials to a real integrator:

• Fetch discovery and JWKS from the mounted issuer.
• Complete authorization code + PKCE with the exact redirect URI.
• Confirm consent renders inside the host-owned UI.
• Exchange the code with the configured client authentication method.
• If exposing API routes, protect one host route with Lockspire.Plug.VerifyToken, Lockspire.Plug.EnforceSenderConstraints, and Lockspire.Plug.RequireToken.

Lockspire proves protocol facts. Your Phoenix app still owns tenant checks, business authorization, rate limiting, and response shaping.