SaaS & data, an interactive architecture walkthrough
Authentication and SSO service: how the architecture works
How an SSO service signs users in once with MFA and federation, issues short-lived signed tokens via OpenID Connect, and revokes access when needed.
This is a learning explainer based on public engineering writing and general design practice. It is simplified, it is not the actual architecture of any company, and it may be inaccurate.
Interactive diagram
Overview
An authentication and single sign-on (SSO) service verifies who a user is once and lets them use many applications without signing in again. Applications redirect users to a central identity provider using OAuth 2.0 and OpenID Connect; after login the provider issues signed tokens, and applications never handle passwords.
Logins pass a risk check and rate limits, passwords are verified against slow salted hashes, and a second factor is required, preferably a phishing-resistant passkey. Users from companies with their own identity provider are federated over SAML or OIDC, and those companies provision and remove users automatically through SCIM. A server-side SSO session sits behind a secure cookie, while short-lived signed access tokens let APIs check identity without calling the provider. This is a simplified learning design, not any specific product's implementation.
Trade-offs and what changes at scale
Self-contained signed tokens make API checks fast but cannot be revoked instantly, so access tokens are kept short and refresh tokens are revocable on the server. Stronger factors such as passkeys reduce phishing but need careful account recovery, which is often the weakest point. A central provider is a single point of failure for every login, so it is replicated across zones and its signing keys are rotated with overlap. At larger scale the main load is credential-stuffing traffic rather than real logins, so bot detection and rate limiting at the edge carry much of the work.
How it works, step by step
The walkthrough above, as text. Each step lights up the components named under it.
An app that needs a signed-in user redirects to the Authorization Server with an OAuth authorization request and a PKCE challenge. Apps never see the password; they only receive tokens.
When the user submits the Login UI, the Risk Engine scores the attempt by IP reputation, device and failure rate, and the gateway rate-limits per account and IP. Credential stuffing is blocked or challenged before any password is checked.
The Password Hasher compares the password with an Argon2id hash and per-user salt stored in the User DB. A slow, memory-hard hash makes a stolen database expensive to crack.
The MFA Service then asks for a second factor, preferring passkeys (WebAuthn), which cannot be phished, over TOTP codes, with SMS only as a restricted fallback. Changing factors later requires re-authenticating with an existing one.
If the email belongs to a company with SSO configured, the Federation Broker sends the user to that company's Corporate IdP over SAML or OIDC instead. The customer's own policies, including MFA, then apply.
After login, a new SSO session id is created in the Session Store and set as a Secure, HttpOnly, SameSite cookie. Regenerating the id at login prevents session fixation, and the session lets other apps sign in without a new password prompt.
The Authorization Server issues a short-lived access token and an ID token signed with the current key from Signing Keys, plus a refresh token. Short-lived access tokens limit the damage if one leaks.
Resource APIs check each access token's signature against the published public keys, its expiry and its audience, without calling the identity service. That keeps the identity provider off the path of every API request.
When a customer removes an employee in their directory, SCIM Provisioning deactivates the user and revokes their sessions and refresh tokens. Offboarding takes effect within minutes, not at the next token expiry days later.
A sign-in from a new device triggers an alert through the Email Service, as do password and MFA changes. Users are often the first to notice an account takeover.
Every login, failure, MFA change and admin action is written to the Audit Log. Enterprise customers ask for these records, and investigations depend on them.
Sequence diagram
The same walkthrough as a UML sequence diagram, one lane per layer or group (17 components in all), left to right in the order a request reaches them, numbered by step. A loop on a lane is a step that stays inside that group. Solid arrows are synchronous calls, dashed are asynchronous.
Key components
API Gateway
- API Gateway: TLS, login rate limits, bot checks
Clientslayer
- Mobile App: first-party native app
- Partner App: third-party OAuth client
- Web App: first-party browser app
Identity Providerboundary
one login for every app
- Authorization Server: OAuth 2.0 / OpenID Connect
- Login UI: sign-in, sign-up, recovery pages
- MFA Service: passkeys/WebAuthn, TOTP, recovery codes
- Password Hasher: Argon2id with per-user salt
- Risk Engine: credential stuffing, impossible travel
- Session Store: SSO sessions and refresh tokens (redis)
- Signing Keys: token signing keys, published as JWKS
- User DB: users, credentials, MFA factors (postgresql)
Enterprise SSOdomain
- Corporate IdP: a customer's own identity provider
- Federation Broker: SAML and OIDC with customer IdPs
- SCIM Provisioning: creates and removes users from the customer side
- Social Login: sign in with an existing account
Token Consumersdomain
- Audit Log: logins, MFA changes, admin actions (clickhouse)
- Email Service: verification, login alerts (sendgrid)
- Resource APIs: validate access tokens locally
Sources
Public writing this explainer draws on. Read these for what the real systems actually do.
- OWASP Cheat Sheet: Password Storage (Argon2id, salts, work factors)
- OWASP Cheat Sheet: Session Management (cookie attributes, regeneration, timeouts)
- OWASP Cheat Sheet: Multifactor Authentication (WebAuthn, TOTP, SMS limits, recovery)
- ory/hydra: OAuth 2.0 and OpenID Connect server with delegated login and consent
- keycloak/keycloak: open-source identity and access management (OIDC, SAML, federation)
Make it yours
Copy this diagram and its walkthrough into your own workspace, then change anything: swap Postgres for DynamoDB, add a cache, rewrite the narration. Free, and it uses no AI credits.
Related walkthroughs
- Multi-tenant SaaS analytics pipelineHow a SaaS product collects events from many customers, keeps each tenant's data isolated, and serves fast dashboards from a columnar store.
- Metrics and monitoring systemHow a monitoring system scrapes metrics from every service, alerts through grouped and routed notifications, and keeps years of data in object storage.
- Log aggregation pipelineHow a log pipeline collects lines from every host, buffers them in a topic, indexes only labels, and keeps compressed text in object storage.
This is a learning explainer based on public engineering writing and general design practice. It is simplified, it is not the actual architecture of any company, and it may be inaccurate. Real systems differ in the details. Browse the library.