yvgude--lean-ctx/docs/guides/org-sso-setup.md

Org Single Sign-On (OIDC) Setup

Let your team sign in to lean-ctx Cloud through your own identity provider (Okta, Microsoft Entra ID, Google Workspace, or any OIDC-compliant OP). Self-serve, no support ticket. Configure it once on the billing page, verify your domain via DNS, and optionally require SSO for everyone in the org.

Plan: Self-serve OIDC SSO is available on Business ($149/mo) and Enterprise plans. SAML SSO with SCIM provisioning is Enterprise-only. The org owner configures it; members just sign in.

Grandfather note: orgs that configured OIDC while it was Team-gated (pre-GL #533) keep their existing SSO working. New SSO setup requires the sso_oidc entitlement (Business or Enterprise).

---

How it works

1. You register a lean-ctx app in your IdP and paste the issuer, client ID and client secret into Account → Billing → Single sign-on.
2. You prove you own the email domain by adding one DNS-TXT record.
3. Members go to the login page, click Continue with SSO, enter their work email, and get redirected to your IdP. On return they have a normal lean-ctx session — no password, account auto-provisioned and added to your org (just-in-time).
4. Optional: flip Require SSO so password logins for your domain are refused. The org owner always keeps password access (break-glass) so a misconfigured IdP can never lock you out.

The redirect URI to register in every IdP is:

https://api.leanctx.com/api/auth/sso/callback

Required scopes: openid email profile. Response type: code (Authorization Code flow with PKCE — lean-ctx adds PKCE automatically).

---

Step 1 — Create the app in your IdP

Okta

1. Admin → Applications → Create App Integration.
2. Sign-in method: OIDC – OpenID Connect. Application type: Web Application.
3. Sign-in redirect URI: https://api.leanctx.com/api/auth/sso/callback.
4. Assign the people/groups who should have access.
5. Copy Client ID and Client secret. Your issuer is https://<your-org>.okta.com (Okta → Security → API → Authorization Servers; use the Issuer URI).

Microsoft Entra ID (Azure AD)

1. Entra admin → App registrations → New registration.
2. Redirect URI (type Web): https://api.leanctx.com/api/auth/sso/callback.
3. Certificates & secrets → New client secret, copy the value.
4. Overview → copy the Application (client) ID.
5. Issuer: https://login.microsoftonline.com/<tenant-id>/v2.0.

Google Workspace

1. Google Cloud Console → APIs & Services → Credentials → Create Credentials → OAuth client ID.
2. Application type: Web application.
3. Authorized redirect URI: https://api.leanctx.com/api/auth/sso/callback.
4. Copy Client ID and Client secret.
5. Issuer: https://accounts.google.com.

Any spec-compliant OIDC provider works. lean-ctx reads the issuer's /.well-known/openid-configuration for endpoints and JWKS, so you only need the issuer URL — not individual endpoint URLs.

---

Step 2 — Configure lean-ctx

1. Sign in as the org owner and open Account → Billing.
2. In Single sign-on (OIDC), fill in:
   • Email domain — e.g. acme.com (the domain of your members' work email).
   • Issuer URL — from step 1.
   • Client ID / Client secret — from step 1.
3. Save configuration. The secret is sealed (encrypted at rest) and never shown again; leave the field blank on later edits to keep the stored one.

---

Step 3 — Verify your domain

After saving, lean-ctx shows a DNS-TXT record. Add it at your DNS provider:

Field	Value
Type	TXT
Name / Host	_leanctx-sso.acme.com
Value	leanctx-sso-verify=<token shown in the dashboard>

Then click Verify domain. lean-ctx checks the record over DNS-over-HTTPS (Cloudflare, then Google). DNS can take a few minutes to propagate — if it isn't visible yet, wait and retry.

Domain verification is required before SSO accepts any login. It guarantees that only the org which controls a domain can authenticate its addresses, and that no two orgs can claim the same domain.

---

Step 4 (optional) — Require SSO

Once the domain is verified, toggle Require SSO for everyone in the org. While enabled:

• Password login and registration for your domain are refused.
• The org owner is always exempt (break-glass) — you can still sign in with your password if the IdP is down.

Turn it off any time to re-enable passwords.

---

What members experience

1. Login page → Continue with SSO → enter work email.
2. Redirect to your IdP, authenticate (and MFA, if your IdP enforces it).
3. Back on lean-ctx, signed in. First-time users are created automatically (email pre-verified, no password) and added to your org.
4. They run lean-ctx login / configure the MCP key exactly as a password user would — the session is identical.

---

Security model

• Authorization Code + PKCE (S256) on every flow, even with a confidential client secret.
• ID-token verification: JWKS signature, iss, aud, exp, and a per-flow nonce. Tokens signed with HS*/none are rejected outright (alg-confusion defense) — only RSA/PS/ECDSA are accepted.
• Asserted email must be under your verified domain, re-checked at the callback. email_verified:false from the IdP is rejected.
• Client secret is encrypted at rest (ChaCha20-Poly1305), decrypted only for the token exchange, never cached on the edge.
• No API keys in URLs: after a successful login the browser exchanges a single-use, 60-second handoff code for the session key.
• Owner break-glass: enforcement never applies to the owner's email.

Full protocol contract: docs/contracts/org-sso-oidc-v1.md.

---

Troubleshooting

Symptom	Cause / fix
Continue with SSO says no IdP found	Domain not configured or not verified yet. Finish steps 2–3.
sso_error=verify_failed after IdP	ID token failed validation. Check the issuer URL is exact and the client ID matches the IdP app.
sso_error=idp_denied	The IdP rejected the user (not assigned to the app, or consent denied). Assign the user/group.
sso_error=expired	The login took longer than 10 minutes, or the handoff code expired. Just start again.
Domain won't verify	TXT record not yet propagated, wrong host (_leanctx-sso.<domain>), or wrong value. Re-check and retry — DoH reads can lag your DNS edit by minutes.
A user can't sign in but others can	Their email domain differs from the verified domain, or the IdP reports email_verified:false.
Owner locked out with SSO required	Owners are exempt by design — use your password. If a non-owner needs in, turn off Require SSO temporarily.

Still stuck? hello@leanctx.com or the Discord community.