Workforce SSO Setup
Use this page when you need to configure or debug workforce SSO for platform sign-in.
What You Are Configuring
Section titled “What You Are Configuring”Workforce SSO is the Better Auth sign-in path for people using the web app. In this repo, it is configured in apps/auth and exposed on the web sign-in surface. The CMS apps use native Payload users in this slice.
Current Provider Examples
Section titled “Current Provider Examples”- Google workforce SSO uses the internal provider id
google-sso. - Microsoft workforce SSO uses the internal provider id
microsoft-sso. - Every workforce SSO provider id must stay separate from connector/social provider ids for the same provider family.
The Setup Flow
Section titled “The Setup Flow”- Add provider credentials in
apps/auth/.env. - Set the workforce provider id and provider-specific constraints.
- Decide whether the web sign-in surface should expose SSO.
- Register the correct workforce SSO callback URIs with the identity provider.
- Run
bun run setupso the auth app reconciles Better Auth SSO provider registration. - Verify the intended surface renders the provider button and issues a valid Better Auth session.
Env Groups That Matter
Section titled “Env Groups That Matter”Provider credentials
Section titled “Provider credentials”GOOGLE_CLIENT_ID/GOOGLE_CLIENT_SECRETMICROSOFT_CLIENT_ID/MICROSOFT_CLIENT_SECRET
Provider identity
Section titled “Provider identity”GOOGLE_SSO_PROVIDER_IDMICROSOFT_SSO_PROVIDER_ID
Every *_SSO_PROVIDER_ID value must resolve to a workforce SSO id, not a connector/social provider id. Current examples are google-sso and microsoft-sso, not google or microsoft.
Surface policy
Section titled “Surface policy”AUTH_WEB_ALLOWED_AUTH_METHODSAUTH_WEB_ALLOWED_SSO_PROVIDERS
Provider-specific guards
Section titled “Provider-specific guards”- Google uses
GOOGLE_SSO_ALLOWED_DOMAINSfor Workspace domain allowlisting. The auth service enforces this list against Google’s authoritativehdhosted-domain claim and fails closed when the claim is absent or mismatched; the email domain alone is not accepted as Workspace membership proof. - Microsoft uses
MICROSOFT_SSO_ISSUERand must be tenant-specific.
Practical Rules
Section titled “Practical Rules”- Do not reuse any connector/social provider id for workforce SSO. For example, use
google-ssorather thangoogle, andmicrosoft-ssorather thanmicrosoft. - Do not put connector/social provider ids in
AUTH_WEB_ALLOWED_SSO_PROVIDERS; that list must match registered workforce SSO ids exactly. - CMS operator login is native Payload auth. Do not use Better Auth workforce SSO provider ids as CMS login providers in this slice.
- After any workforce SSO env change, rerun
bun run setupinapps/auth. - Same-email workforce SSO auto-linking is allowed only for existing local credential users whose inbox ownership was already proven; approved web access completion is the canonical proof path in this repo.
Workforce SSO Callback URIs
Section titled “Workforce SSO Callback URIs”Workforce SSO callbacks use this pattern:
<auth-origin>/api/auth/sso/callback/<workforce-provider-id>
Examples:
- Google workforce SSO:
/api/auth/sso/callback/google-sso - Microsoft workforce SSO:
/api/auth/sso/callback/microsoft-sso
In local development, register the localhost auth origin you actually use, usually:
http://localhost:3001/api/auth/sso/callback/google-ssohttp://localhost:3001/api/auth/sso/callback/microsoft-sso
If you use a public tunnel or production auth domain for browser sign-in, register the same callback paths on that public origin too:
https://auth.example.com/api/auth/sso/callback/google-ssohttps://auth.example.com/api/auth/sso/callback/microsoft-sso
Read Next In Repo
Section titled “Read Next In Repo”| File | Why you would open it |
|---|---|
apps/auth/.env.example |
Full list of auth-side workforce SSO env vars and comments |
apps/cms-customer/README-auth-integration.md |
Native customer CMS login and web-user mirror notes |
docs/features/authentication/spec.md |
Full end-state auth model and policy constraints |