SSO and social login

Social login (Google, GitHub, Microsoft)

Users can sign up and sign in with Google, GitHub or Microsoft next to email + password. Accounts are matched by verified email: if you already have a verified account with the same email, signing in with a provider links it. If an email + password account exists for that address but its email was never verified, the provider-verified identity takes it over: the password is removed and its sessions are signed out (written to the audit log). New users create a workspace (or join the workspace whose invite link they followed).

Security: authorization-code flow with state (one-time, bound to your browser), PKCE (S256) and an OIDC nonce; Google and Microsoft id_tokens are verified against the provider's signing keys. Only verified emails are accepted (Google email_verified; Microsoft personal accounts or the xms_edov claim; GitHub the verified primary email).

Self-hosting: enable the providers

Each provider shows up only when both of its environment variables are set. The callback URL is <APP_URL>/api/auth/callback/<provider>.

Provider	Env vars	Callback URL (deployment-playbook.com)
Google	AUTH_GOOGLE_ID, AUTH_GOOGLE_SECRET	https://deployment-playbook.com/api/auth/callback/google
GitHub	AUTH_GITHUB_ID, AUTH_GITHUB_SECRET	https://deployment-playbook.com/api/auth/callback/github
Microsoft	AUTH_MICROSOFT_ID, AUTH_MICROSOFT_SECRET	https://deployment-playbook.com/api/auth/callback/microsoft

Google: Google Cloud Console → APIs & Services → OAuth consent screen (External, scopes openid, email, profile) → Credentials → Create credentials → OAuth client ID → Web application → add the callback URL under Authorized redirect URIs. Copy the client ID and secret.

GitHub: GitHub → Settings → Developer settings → OAuth Apps → New OAuth App (for an organisation: the org's Settings → Developer settings). Homepage URL = your app URL, Authorization callback URL = the callback URL. Generate a client secret.

Microsoft (Entra ID): Azure portal → Microsoft Entra ID → App registrations → New registration. Supported account types: Accounts in any organizational directory and personal Microsoft accounts (multi-tenant, uses the common endpoint). Redirect URI: platform Web, the callback URL. Then Certificates & secrets → New client secret (copy the Value). Token configuration → Add optional claim → ID token → email and xms_edov (so work-account emails count as verified). API permissions: openid, email, profile (Microsoft Graph, delegated).

Company SSO (SAML 2.0 or OIDC)

Available on Business and Enterprise (and Early access workspaces). An Admin configures it on Single sign-on (/w/<workspace>/sso).

1. Give your IdP our values (copy buttons on the page):
   • SAML: ACS (Reply) URL …/api/sso/saml/acs/<workspaceId>, Entity ID / Audience and metadata URL …/api/sso/saml/metadata/<workspaceId>. NameID format email address; send the email as NameID or as an email attribute, optionally displayName. Assertions must be signed.
   • OIDC: Redirect URI …/api/sso/oidc/callback, scopes openid email profile.
2. Connection: SAML → paste the IdP metadata URL or XML. OIDC → issuer/discovery URL, client ID and client secret (the secret is never shown again). Pick the default role for people who sign in for the first time (Viewer by default).
3. Verify your email domains: add example.com, create the DNS TXT record shown (_deployment-playbook.example.com = deployment-playbook-verify=…) and click Verify. Only users with an email on a verified domain can sign in through your SSO, and a domain can be verified by one workspace only.
4. Users sign in at /sso with their work email (or the workspace slug). First-time users are created and join the workspace with the default role (JIT provisioning); existing users with that email are linked.
5. Optional: Enforce SSO. Members whose email is on a verified domain can then no longer sign in with a password or social login. One break-glass Admin (must have a password) keeps password access in case your IdP is down.

IdP notes

• Okta: Applications → Create App Integration → SAML 2.0. Single sign-on URL = ACS URL, Audience URI = Entity ID, Name ID format EmailAddress, Application username Email. Copy the Metadata URL.
• Microsoft Entra ID: Enterprise applications → New application → Create your own → Non-gallery → Single sign-on → SAML. Identifier = Entity ID, Reply URL = ACS URL. Copy the App Federation Metadata Url. Or use OIDC with an app registration (redirect URI above; discovery https://login.microsoftonline.com/<tenant-id>/v2.0).
• Google Workspace: Admin console → Apps → Web and mobile apps → Add custom SAML app. ACS URL and Entity ID from above, Name ID format EMAIL, Name ID Basic Information → Primary email. Download the IdP metadata and paste it.

How it is secured

SP-initiated sign-in only: each AuthnRequest id is stored and the response must answer it (InResponseTo), so responses can't be replayed and unsolicited (IdP-initiated) responses are rejected. Signatures (assertion), audience, recipient and validity window are checked; RelayState is bound to your browser with a cookie. Configuration changes, domain verification, SSO sign-ins, failed SSO attempts and JIT memberships are written to the audit log.

SCIM user provisioning/deprovisioning is planned for Enterprise.