System Design: [Identity provider name]

Reference design for an identity provider (IdP) that offers single sign-on to first-party and third-party applications as an OAuth 2.0 authorization server and OpenID Connect issuer. It covers the authorization code flow with PKCE, token formats and lifetimes, refresh token rotation with reuse detection, signing key rotation and the JWKS endpoint, browser sessions and logout, multi-factor authentication with passkeys (WebAuthn), account recovery and multi-tenant issuers. It is based on OpenID Connect Core 1.0 incorporating errata set 2, RFC 6749, RFC 7636 (PKCE), RFC 9700 (OAuth 2.0 Security Best Current Practice, January 2025), NIST SP 800-63-4 (July 2025) and W3C Web Authentication Level 3. It follows the 12-section structure of the System Design Document template. Replace every [bracketed] value and every row marked Example.

Document control

Approvals

Revision history

Contents

1. Overview
2. Requirements
3. Capacity estimation
4. API design
5. Data model
6. High-level design
7. Detailed design
8. Scalability and performance
9. Reliability, security and operations
10. Trade-offs and alternatives
11. Delivery plan and risks
12. Appendices

1. Overview

1.1 Problem statement

[Example: Six products each run their own login, password storage and "remember me" cookies. Users hold several passwords for one company, a credential-stuffing attack last quarter succeeded against the oldest product, and enterprise customers ask for SSO with their own identity provider. Mobile apps still use the resource owner password grant, which current OAuth security guidance forbids.]

1.2 Proposed solution

[Example: One identity provider per region serves every product as an OpenID Connect issuer. Applications redirect to it with the authorization code flow and PKCE; it authenticates the user with a passkey, or a password plus a second factor, keeps a browser session, and issues a short ID token, a 10-minute JWT access token and a rotating refresh token. Keys are rotated on a schedule and published at the JWKS endpoint ahead of use. Enterprise tenants get their own issuer and can federate to their own IdP.]

1.3 Decisions requested from reviewers

1.4 45-minute interview path

2. Requirements

2.1 Core functional requirements

2.2 Non-functional requirements

2.3 Below the line (out of scope)

• [Example: implicit flow and resource owner password credentials grant (not offered; RFC 9700 §2.1.2 and §2.4)]
• [Example: device authorization grant for TVs (phase 2)]
• [Example: identity proofing of real-world identity (handled by a proofing vendor if ever needed)]
• [Example: fine-grained permissions (the authorization service decides; the IdP only authenticates)]
• [Example: SCIM user provisioning from enterprise directories (phase 2)]
• [Item deferred, with the release that will take it]

3. Capacity estimation

3.1 Assumptions

3.2 Interactive logins

Consequence: the login front end is small; capacity planning focuses on the hashing pool below.

3.3 Password hashing CPU

Consequence: with 40% headroom, about 24 cores at peak. A credential stuffing attack at 10 times the normal rate would need 240 cores, so rate limiting and bot detection run before the hash, not after it, and the hashing pool is isolated so an attack cannot starve token refreshes.

3.4 Token refreshes

Consequence: each refresh with rotation is a conditional write (mark the old token used, insert the new one). Over 4 000 writes/s needs a store that handles conditional writes at that rate per region, so refresh tokens get their own table keyed by token hash (5.3).

3.5 State size

3.6 Signing and key distribution

Peak signatures are about $580 + 4\,170 \approx 4\,750$/s (one ID or access token set per login or refresh, counted once). Elliptic-curve signatures take well under a millisecond each, so a handful of cores suffice. Consequence: sign in the token service process with keys unwrapped from KMS at start-up, rather than calling a remote KMS per token, which would add latency and hit KMS rate limits. JWKS fetches by resource servers are cached for minutes and served from a CDN.

3.7 Summary

4. API design

4.1 Endpoints

Grant types offered: authorization_code (PKCE required, S256 only), refresh_token, client_credentials. Not offered: implicit and resource owner password credentials, per RFC 9700 §2.1.2 and §2.4. Redirect URIs are compared by exact string match (RFC 9700 §2.1), with the loopback port exception for native apps.

4.2 Request and response examples

The authorization request carries a PKCE challenge, state for CSRF protection and nonce to bind the ID token to the browser session.

GET /authorize?response_type=code&client_id=web-app
  &redirect_uri=https%3A%2F%2Fapp.example.com%2Fcallback
  &scope=openid%20profile%20email&state=af0ifjsldkj&nonce=n-0S6_WzA2Mj
  &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
  &code_challenge_method=S256 HTTP/1.1
Host: id.example.com

POST /token HTTP/1.1
Host: id.example.com
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA
&redirect_uri=https%3A%2F%2Fapp.example.com%2Fcallback&client_id=web-app
&code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store

{"access_token": "eyJhbGciOiJFUzI1NiIsImtpZCI6IjIwMjYtMTAifQ...",
 "token_type": "Bearer", "expires_in": 600,
 "refresh_token": "rt_8xLOxBtZp8", "id_token": "eyJhbGciOiJFUzI1NiJ9..."}

Example ID token payload (claims defined in OIDC Core §2):

{"iss": "https://id.example.com", "sub": "u_24400320", "aud": "web-app",
 "exp": 1792666800, "iat": 1792666500, "auth_time": 1792666490,
 "nonce": "n-0S6_WzA2Mj", "acr": "urn:example:aal2", "amr": ["hwk", "user"]}

4.3 Errors

Token endpoint errors use the codes from RFC 6749 §5.2 (invalid_grant, invalid_client, unauthorized_client, unsupported_grant_type, invalid_scope). Return invalid_grant for a reused refresh token and revoke its family (7.1); never reveal whether a code or token existed.

5. Data model

5.1 Entities

Accounts own credentials and sessions; clients own grants; signing keys are global per issuer.

5.2 Storage choices

5.3 Access patterns

6. High-level design

7. Detailed design

7.0 Authorization code flow with PKCE

Every client, public or confidential, uses this flow for user sign-in. The IdP stores the code challenge with the code and accepts the code only once, only from the same client, and only with the matching verifier.

7.1 Deep dive: token lifecycle and refresh rotation

Choice and reason. Every refresh returns a new refresh token and marks the old one used, in one conditional write on the family. If a used token is presented again, either an attacker or the legitimate client holds a stolen copy; the IdP cannot tell which, so it revokes the whole family and the session's other families for that client, forcing a new login. Allow a grace window of a few seconds in which the same old token returns the same new token, to tolerate a retry after a network failure without triggering revocation.

7.2 Deep dive: signing key rotation and JWKS

Choice and reason. Keys move through states: pending (published in JWKS, not used), active (signs new tokens), retired (still published, verifies tokens until they expire), removed. Publish a pending key at least one JWKS cache lifetime plus a margin before activation, so every resource server has fetched it. Keep the retired key published for at least the longest token lifetime it signed. Resource servers select the key by kid and refetch JWKS once when they see an unknown kid, with a rate limit on refetches. For a compromised key, skip the pending period, remove the key, and accept that tokens it signed are rejected.

7.3 Deep dive: sessions, MFA, passkeys and step-up

• Authenticators. Offer passkeys (WebAuthn) as the primary factor. NIST SP 800-63B-4 requires verifiers at AAL2 to offer at least one phishing-resistant option, allows syncable authenticators (synced passkeys) up to AAL2, and requires non-exportable keys at AAL3. Use device-bound keys (security keys or platform keys flagged as not backup eligible) for administrators who need AAL3.
• Passwords as fallback. Follow SP 800-63B-4 §3.1.1: minimum 15 characters when the password is the only factor, 8 when it is one factor of MFA, a blocklist of common and breached values, no composition rules, and no forced periodic changes. Hash with a memory-hard function; tune parameters to the CPU budget in 3.3.
• Throttling. Limit consecutive failures per account; SP 800-63B-4 §3.2.2 caps them at 100. Combine with per-IP and per-device limits at the edge so throttling does not become a lockout weapon.
• Sessions. The browser session cookie is Secure, HttpOnly, SameSite=Lax, host-only. Apply an idle timeout and an absolute timeout; for AAL2 SP 800-63B-4 recommends reauthentication at least every 24 hours and after at most 1 hour of inactivity. A 30-day refresh token outlives that window, so for clients that claim AAL2 for their own sessions, cap the refresh family at the same absolute limit or require reauthentication with max_age.
• Step-up. A client asks for a higher level with acr_values or max_age. The IdP compares the session's acr and auth_time with the request and reauthenticates if needed, then reports acr, amr and auth_time in the ID token so the client can verify.

7.4 Deep dive: account recovery

Choice and reason. Recovery must not be easier than login. On every recovery: notify all verified channels, revoke existing sessions and refresh families (AP-05), apply a cooling-off delay before sensitive changes such as adding a new passkey, and log the event for the security team.

7.5 Multi-tenancy and federation

Consumers share one issuer. Each enterprise tenant gets its own issuer URL (https://id.example.com/t/{tenant}), its own signing keys and its own client registrations, so a token from one tenant can never validate for another and a tenant's key can be rotated alone. For tenants that federate, the broker acts as a relying party to their IdP, maps claims to local accounts by a stable subject identifier (never by email alone), and applies the tenant's MFA policy. See Multi-Tenancy Design Template (architecture/multi-tenancy-design).

How real systems do it: Keycloak

The open-source Keycloak server organises identity into realms: each realm is an isolated space with its own users, credentials, roles and client applications, which is the same per-tenant isolation as 7.5. Its Server Administration Guide (version 26.8.1) explains that each realm signs with one active key pair while older passive keys stay available to verify earlier signatures, which lets administrators rotate without downtime. The guide's suggested procedure is to add a new key with a higher priority so it becomes active, keep the previous key passive for a transition period, and remove it later; it suggests rotation every few months and warns that sessions signed with a removed key need reauthentication. This box paraphrases the public documentation; read it for the exact settings.

8. Scalability and performance

Latency budget for POST /token with refresh grant (target p99 150 ms):

9. Reliability, security and operations

9.1 Failure modes

9.2 Security

Run the full analysis in Threat Model Template (security/threat-model).

9.3 Observability

9.4 Cost estimate

10. Trade-offs and alternatives

11. Delivery plan and risks

11.1 Milestones

11.2 Migration and rollback

[Example: Existing password hashes are imported with their algorithm tag and re-hashed with the new function on next successful login. Each product switches login with a feature flag; rollback returns to its legacy login while keeping IdP accounts in sync for 30 days.]

11.3 Risks

12. Appendices

12.1 Traceability

12.2 Open questions

12.3 Glossary

12.4 References

Standard and licence note

Based on OpenID Connect Core 1.0 incorporating errata set 2, the IETF OAuth RFCs listed in 12.4 (including RFC 9700, January 2025), NIST SP 800-63-4 (July 2025) and W3C Web Authentication Level 3. This is a reference design with illustrative numbers; it is not a conformance claim. Specifications and NIST guidance are revised; check the current official versions, including the status of the OAuth 2.1 draft, before implementing. Original text written for this collection. Template licence: MIT.