Module 04 · API fundamentals · Lesson 15 of 15
Single sign-on (SSO)
One login for many applications through a central identity provider. How SSO works with OIDC and SAML, a federated login end to end, the logout and session-lifetime problems, and how enterprises wire it to their directory.
Why it matters
Every company with more than a few internal tools wants one login, and every business customer of a SaaS product eventually asks "do you support SSO with our identity provider?" It is a product requirement as much as a security one. Designing for SSO means accepting that authentication is not your system's job: a trusted identity provider does it, and your job is to consume the result safely and keep your sessions in step with it.
The idea
Single sign-on lets a user authenticate once with an identity provider (IdP) and then access many service providers (SPs, the applications) without logging in again. The applications trust assertions from the IdP instead of checking passwords themselves. It is federation: a trust relationship between the IdP and each application, established out of band by exchanging metadata and keys.
Two protocols
| OpenID Connect | SAML 2.0 | |
|---|---|---|
| Age and format | 2014, JSON and JWTs over HTTPS redirects | 2005, XML assertions, usually POSTed through the browser |
| Fits | Modern web, mobile, APIs; consumer and workforce | Enterprise IdPs (Okta, Entra ID, Ping) and legacy apps |
| Tokens | Id token (identity) and access token (API) | Signed assertion with attributes; no API token concept |
| Complexity | Lower; libraries everywhere | Higher; XML signatures and canonicalisation are error-prone |
| Pick when | Building new; you control both sides | The customer's IdP only speaks SAML (still common) |
A SaaS product that sells to businesses typically supports both, because the customer chooses the IdP. Many teams put an identity broker (Auth0, Clerk, Keycloak, WorkOS and similar) between their application and the customers' IdPs, so the application speaks one protocol (OIDC) and the broker handles SAML and the per-customer configuration.
Mapping identity into your system
The assertion carries a stable subject identifier and attributes (email, name, groups). Map the subject to a local user record on first login (just-in-time provisioning) and keep the mapping keyed on the stable id, never the email, which can change. For roles, either read group claims from the assertion or, better for enterprises, accept SCIM provisioning so the customer's directory pushes users, groups and deactivations to you directly. Deactivation through SCIM is what makes "they left the company" take effect immediately.
Sessions and logout
SSO creates two sessions: the IdP's and your application's. Your session should be no longer than the IdP's and ideally shorter, re-validating with a silent redirect so a user disabled at the IdP loses access quickly. Single logout is the hard part: logging out of the IdP does not automatically end every application session. OIDC offers back-channel logout (the IdP calls each app) and front-channel logout (hidden iframes); SAML has its own. Many systems settle for short application sessions and a logout that clears the local session and redirects to the IdP's logout endpoint.
Multi-tenant design
Business customers each bring their own IdP. Identify the tenant before authentication (by email domain, subdomain or an organisation picker), look up that tenant's IdP configuration, and start the flow against it. Enforce that assertions for tenant A cannot create or access users in tenant B, which means the tenant comes from your configuration lookup, never from a claim the IdP sends. Keep the IdP metadata, certificates and redirect URIs per tenant, with rotation handled when the customer rotates keys.
Trade-offs
SSO removes password handling from your system and gives enterprises the control they require, and it makes your login path depend on a third party you do not operate: if the IdP is down, nobody logs in. It adds per-customer configuration, certificate rotation, and the logout and session-sync problems above. A broker reduces protocol work and adds a vendor in the critical path.
In an interview
Show you understand the trust boundary: "Enterprise customers authenticate against their own IdP over OIDC or SAML through an identity broker; we map the stable subject id to a local user on first login, read groups for roles, and accept SCIM so deprovisioning is immediate. Our sessions are shorter than the IdP's and we support back-channel logout." For an internal platform: "All internal tools sit behind one OIDC provider, so engineers log in once and offboarding happens in one place."
Check yourself
A company removes an employee from its identity provider. The employee's browser still has an active session in your application for the next 12 hours. What design would have prevented this?