System Design (HLD)Authentication Patterns

Authentication Patterns in Distributed Systems

LevelIntermediate

Duration75 mins

TopicAuthentication Patterns

4 / 5

SSO and Federation

One Identity, Many Doors

Consider the modern enterprise employee: they access email, HR systems, expense reporting, CRM, development tools, and dozens of SaaS applications daily. Without Single Sign-On (SSO), each system requires a separate login—separate passwords to remember, separate sessions to manage, and separate security risks to monitor. Multiply this across thousands of employees, and you have a security and usability nightmare.

Single Sign-On (SSO) solves this by enabling users to authenticate once and access multiple applications without re-entering credentials. Identity Federation extends this across organizational boundaries—allowing employees to access partner systems, customers to use multiple related services, and developers to 'Sign in with GitHub' on third-party platforms.

These patterns have become table stakes for enterprise software and consumer applications alike. Understanding SSO and federation is essential for designing systems that integrate with the broader identity ecosystem.

What You Will Learn

This page covers SSO fundamentals and implementation patterns, the SAML protocol for enterprise federation, OAuth 2.0 and OpenID Connect for modern SSO, social login integration, architectural considerations for service providers, and security implications of federated identity.

Understanding SSO and Federation

Single Sign-On (SSO) and Identity Federation are related but distinct concepts:

SSO is the user experience: authenticate once, access many applications without re-authenticating.
Federation is the trust architecture: multiple independent organizations or services accept authentication performed by a trusted identity provider.

SSO can exist without cross-organization federation (a company uses one IdP for all internal apps). Federation typically enables SSO but could theoretically require re-authentication for each service.

Key Terminology:

SSO and Federation Terminology
Term	Definition	Example
Identity Provider (IdP)	The system that authenticates users and issues identity assertions	Okta, Azure AD, Auth0, Google
Service Provider (SP)	The application that relies on the IdP for authentication	Salesforce, Slack, your internal apps
Relying Party (RP)	Synonym for Service Provider in OIDC terminology	Your web application
Assertion/Token	Cryptographic proof of authentication from IdP	SAML assertion, OIDC ID token
Federation Trust	The configured relationship between IdP and SP	Company A trusts Company B's IdP
Claims/Attributes	User information in the assertion (name, email, groups)	email=alice@corp.com, groups=[engineering, admin]

Why SSO Matters:

Benefits of SSO

•Reduced Password Fatigue — Users remember one password, not dozens
•Centralized Security — MFA, policy enforcement, and monitoring in one place
•Instant Deprovisioning — Disable one account, revoke access everywhere
•Audit Trail — Single log of all authentication events
•Improved Compliance — Easier to enforce password policies, access reviews

SSO Risks to Manage

•Single Point of Failure — IdP outage blocks access to everything
•Blast Radius — Compromised account has access everywhere
•Integration Complexity — Each SP has unique requirements
•Session Management — Logout must propagate across all SPs
•Vendor Lock-in — Migrating IdPs is complex and risky

SSO Amplifies Account Compromise

SSO increases the value of each account to attackers—one compromised credential grants access to everything. This is why SSO must be paired with strong MFA. Organizations that implement SSO without MFA are often worse off than with separate accounts, because they've centralized all risk into one authentication event.

SAML 2.0: Enterprise Federation

Security Assertion Markup Language (SAML) 2.0 is the dominant protocol for enterprise SSO. Published in 2005, SAML enabled federated authentication before OAuth existed and remains the standard for B2B and enterprise integrations.

SAML Core Concepts:

Assertions — XML documents containing statements about a user (authentication, attributes, authorization decisions)
Bindings — How SAML messages are transported (HTTP POST, HTTP Redirect, SOAP)
Profiles — Defined flows for specific use cases (Web Browser SSO, Single Logout)

The SAML Web Browser SSO Flow:

SP-Initiated SAML Flow

•User Accesses SP — User navigates to app.example.com (the Service Provider); no session exists.
•SP Generates AuthnRequest — SP creates a SAML AuthnRequest and redirects user to IdP (idp.corp.com).
•User Authenticates at IdP — IdP prompts user for credentials (if no IdP session) and performs authentication.
•IdP Generates Assertion — IdP creates a signed SAML assertion containing user identity and attributes.
•Assertion Sent to SP — IdP posts the assertion to the SP's Assertion Consumer Service (ACS) URL via user's browser.
•SP Validates Assertion — SP verifies signature using IdP's public key, checks conditions (timestamps, audience), extracts user identity.
•SP Creates Session — SP establishes a local session for the user; user is now logged in.

SAML Assertion Structure:

A SAML assertion is an XML document with three main sections:

Issuer — Identifies the IdP that created the assertion
Subject — Identifies the user (NameID format varies: email, persistent ID, transient ID)
Conditions — Validity constraints: NotBefore, NotOnOrAfter, AudienceRestriction
AuthnStatement — When and how the user authenticated
AttributeStatement — User attributes (email, groups, department, etc.)

<saml:Assertion ...>
  <saml:Issuer>https://idp.corp.com</saml:Issuer>
  <saml:Subject>
    <saml:NameID>alice@corp.com</saml:NameID>
  </saml:Subject>
  <saml:Conditions NotBefore="..." NotOnOrAfter="...">
    <saml:AudienceRestriction>
      <saml:Audience>https://app.example.com</saml:Audience>
    </saml:AudienceRestriction>
  </saml:Conditions>
  <saml:AttributeStatement>
    <saml:Attribute Name="groups">
      <saml:AttributeValue>engineering</saml:AttributeValue>
      <saml:AttributeValue>admin</saml:AttributeValue>
    </saml:Attribute>
  </saml:AttributeStatement>
  <ds:Signature>...</ds:Signature>
</saml:Assertion>

SAML Signature Validation Is Critical

SAML vulnerabilities have occurred when SPs accepted unsigned assertions or validated signatures incorrectly. The assertion's cryptographic signature is the ONLY proof it came from the trusted IdP. Failure to validate allows attackers to forge assertions and impersonate any user. Use well-tested SAML libraries—don't implement validation yourself.

SAML Configuration Checklist
Configuration Item	Purpose	Security Note
IdP Metadata URL	Contains IdP's signing certificate, SSO endpoint	Fetch from HTTPS; verify certificate
SP Entity ID	Unique identifier for your SP	Must match AudienceRestriction in assertions
ACS URL	Where IdP posts assertions	Must be HTTPS; validate in assertion Destination
Signing Certificate	SP's private key for signing requests	Protect private key; rotate periodically
NameID Format	How users are identified	Persistent for long-lived accounts; email for simplicity
Attribute Mapping	Map SAML attributes to your user model	Validate expected attributes exist

OAuth 2.0 and OpenID Connect

While SAML dominated enterprise SSO, the mobile and API era demanded something lighter. OAuth 2.0 (2012) provided delegated authorization with JSON and simple HTTP, and OpenID Connect (OIDC) (2014) layered authentication on top of OAuth.

OAuth 2.0 is an authorization framework—it answers 'What can this app access on the user's behalf?' not 'Who is this user?' OIDC adds identity by defining:

ID Token — A JWT containing user identity claims
UserInfo Endpoint — API to fetch additional user attributes
Standard Claims — Defined schema for user information (sub, email, name, etc.)
Discovery — Standardized way to find provider endpoints

OAuth 2.0 Grant Types
Grant Type	Use Case	Token Flow
Authorization Code	Server-side web apps, SPAs (with PKCE)	User redirected to IdP; code exchanged for tokens
Authorization Code + PKCE	Public clients (mobile, SPA) that can't keep secrets	Same as above with code_verifier proof
Client Credentials	Machine-to-machine, no user context	App authenticates with client_id + secret
Device Code	Input-constrained devices (TV, CLI)	User authorizes on different device
Implicit (Deprecated)	Legacy SPAs without backend	Tokens in URL fragment; avoid for new apps
Password (Deprecated)	Legacy trusted first-party apps	Direct password exchange; avoid entirely

The Authorization Code Flow with PKCE:

This is the recommended flow for most web and mobile applications:

OIDC Authorization Code Flow

•Generate PKCE Codes — Client creates random code_verifier and derives code_challenge (SHA256 hash).
•Redirect to Authorization — Client redirects user to IdP's /authorize endpoint with code_challenge, redirect_uri, scope (openid profile email), and state.
•User Authenticates — IdP prompts user; user logs in and consents to requested scopes.
•Authorization Code Returned — IdP redirects to redirect_uri with authorization code and original state.
•Token Exchange — Client calls /token endpoint with code, code_verifier, and client credentials.
•Tokens Returned — IdP validates code_verifier matches original challenge; returns access_token, id_token, and optionally refresh_token.
•Validate ID Token — Client validates JWT signature, issuer, audience, expiration, and nonce.

OIDC Integration
Node.js
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
import { Issuer, generators } from 'openid-client';
 
// Configuration
const OIDC_ISSUER = 'https://accounts.google.com';
const CLIENT_ID = process.env.GOOGLE_CLIENT_ID!;
const CLIENT_SECRET = process.env.GOOGLE_CLIENT_SECRET!;
const REDIRECT_URI = 'https://myapp.com/callback';
 
// Discover OIDC provider endpoints
const googleIssuer = await Issuer.discover(OIDC_ISSUER);
console.log('Discovered issuer:', googleIssuer.metadata);
 
// Create client
const client = new googleIssuer.Client({
  client_id: CLIENT_ID,
  client_secret: CLIENT_SECRET,
  redirect_uris: [REDIRECT_URI],
  response_types: ['code'],
});
 
// Step 1: Generate authorization URL
function generateAuthUrl(req: Request): string {
  const code_verifier = generators.codeVerifier();
  const code_challenge = generators.codeChallenge(code_verifier);
  const state = generators.state();
  const nonce = generators.nonce();
  
  // Store in session for callback validation
  req.session.oidc = { code_verifier, state, nonce };
  
  return client.authorizationUrl({
    scope: 'openid email profile',
    code_challenge,
    code_challenge_method: 'S256',
    state,
    nonce,
  });
}
 
// Step 2: Handle callback
async function handleCallback(req: Request) {
  const { code_verifier, state, nonce } = req.session.oidc;
  const params = client.callbackParams(req);
  
  // Exchange code for tokens
  const tokenSet = await client.callback(
    REDIRECT_URI,
    params,
    { 
      code_verifier, 
      state,
      nonce,  // Validates nonce claim in id_token
    }
  );
  
  // Token validation happens automatically
  console.log('ID Token claims:', tokenSet.claims());
  // { sub: '123456789', email: 'user@gmail.com', name: 'Alice', ... }
  
  // Fetch additional user info if needed
  const userinfo = await client.userinfo(tokenSet.access_token!);
  
  return {
    userId: tokenSet.claims().sub,
    email: tokenSet.claims().email,
    name: tokenSet.claims().name,
    accessToken: tokenSet.access_token,
    refreshToken: tokenSet.refresh_token,
  };
}

Why PKCE Matters

PKCE (Proof Key for Code Exchange) prevents authorization code interception attacks. Even if an attacker intercepts the authorization code, they can't exchange it for tokens without the code_verifier that only the legitimate client knows. Always use PKCE for public clients (mobile, SPA) and recommended even for confidential clients.

Social Login Integration

Social login (also called social sign-in) allows users to authenticate using existing accounts from major providers—Google, Facebook, Apple, GitHub, Microsoft. For consumer applications, social login dramatically reduces signup friction and password fatigue.

Implementation Considerations:

Social Login Providers
Provider	Protocol	Key Considerations	Audience
Google	OIDC	Widely trusted; good OIDC compliance; email verified	Consumer, enterprise (Workspace)
Apple	OIDC	Required for iOS apps with social login; email relay option	Consumer, especially iOS users
Facebook	OAuth 2.0 (not OIDC)	Large user base; privacy concerns; uses custom endpoints	Consumer
Microsoft	OIDC	Personal and work accounts; Azure AD integration	Consumer, enterprise
GitHub	OAuth 2.0	Developer-focused; access to repos if scoped	Developer tools, open source
Twitter/X	OAuth 2.0	Limited user info; frequent API changes	Social apps, news

Account Linking Challenges:

When users can log in with multiple methods (email/password, Google, GitHub), you need an account linking strategy:

Same Email = Same Account? — If a user signs up with email alice@gmail.com, then later clicks 'Sign in with Google' using the same email, are these the same account? Usually yes, but requires verification.
Email Verification — Social providers typically guarantee email verification. If they don't (or you can't confirm), you might be linking to the wrong account.
Multiple Social Accounts — A user might want to link both Google and GitHub. Design for this from the start.
Orphaned Accounts — What happens if a user deletes their Google account? They need an alternative login method.

Account Linking Design:

Account Linking Strategy
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
interface User {
  id: string;
  email: string;
  emailVerified: boolean;
  passwordHash?: string;           // Optional if only social
  linkedAccounts: LinkedAccount[];
}
 
interface LinkedAccount {
  provider: 'google' | 'github' | 'apple' | 'facebook';
  providerUserId: string;          // Unique ID from provider
  email?: string;                  // Email from this provider
  linkedAt: Date;
}
 
async function handleSocialLogin(
  provider: string,
  providerUserId: string,
  providerEmail: string,
  emailVerified: boolean
): Promise<{ user: User; isNewUser: boolean }> {
  
  // 1. Check if this provider account is already linked
  const existingLink = await db.linkedAccounts.findOne({
    provider,
    providerUserId,
  });
  
  if (existingLink) {
    // Known user, return their account
    const user = await db.users.findById(existingLink.userId);
    return { user, isNewUser: false };
  }
  
  // 2. Check if email matches an existing user
  if (providerEmail && emailVerified) {
    const existingUser = await db.users.findByEmail(providerEmail);
    
    if (existingUser) {
      // Link this provider to existing account
      await db.linkedAccounts.create({
        userId: existingUser.id,
        provider,
        providerUserId,
        email: providerEmail,
        linkedAt: new Date(),
      });
      
      // Optionally notify user of new linked account
      await sendEmail(existingUser.email, 
        'New login method added',
        `Your ${provider} account is now linked...`
      );
      
      return { user: existingUser, isNewUser: false };
    }
  }
  
  // 3. Create new user
  const newUser = await db.users.create({
    email: providerEmail,
    emailVerified: emailVerified,
    linkedAccounts: [{
      provider,
      providerUserId,
      email: providerEmail,
      linkedAt: new Date(),
    }],
  });
  
  return { user: newUser, isNewUser: true };
}

Apple's Privacy Requirements

Apple requires 'Sign in with Apple' for iOS apps that offer any third-party login. Apple also provides email relay addresses that hide user's real email. Your account linking logic must handle relay addresses that differ from the user's actual email. Track the Apple 'sub' claim as the stable identifier, not email.

Enterprise SSO Integration

When selling to enterprises, SSO support transitions from nice-to-have to mandatory. IT departments require SSO for security (centralized access control), compliance (audit trails), and efficiency (automated provisioning/deprovisioning).

Enterprise SSO Requirements:

What Enterprises Expect

•SAML 2.0 Support — Most enterprise IdPs (Okta, Azure AD, OneLogin, Ping) support SAML. You must be a SAML SP.
•OIDC Support — Modern alternative to SAML; increasingly preferred for new integrations.
•JIT Provisioning — Automatically create user accounts on first SSO login; no manual user creation.
•SCIM Provisioning — System for Cross-domain Identity Management for full lifecycle management (create, update, deactivate).
•Attribute Mapping — Map IdP attributes (groups, department) to your application's roles and permissions.
•Domain Verification — Prove ownership of email domain before enabling SSO for @company.com addresses.
•SSO Enforcement — Option to require SSO for all users on a domain; disable password login.

Multi-Tenancy Considerations:

B2B SaaS applications typically support multiple enterprise customers, each with their own IdP configuration:

Multi-Tenant SSO Architecture
Approach	Description	Trade-offs
Subdomain per Tenant	customer1.app.com, customer2.app.com	Clean separation; more infrastructure complexity
Email Domain Detection	Detect SSO config from email domain at login	Simple UX; requires email upfront; domain conflicts possible
Tenant Selector	User selects organization from list	Clear intent; extra step; works for multi-domain orgs
Connection ID in URL	Login links include tenant identifier	Works for IdP-initiated flows; less discoverable

Multi-Tenant SSO Configuration
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
interface SSOConnection {
  id: string;
  organizationId: string;
  provider: 'saml' | 'oidc';
  enabled: boolean;
  domains: string[];           // Verified email domains
  enforced: boolean;           // Require SSO, disable password
  
  // SAML configuration
  samlIdpEntityId?: string;
  samlSsoUrl?: string;
  samlCertificate?: string;
  samlNameIdFormat?: string;
  
  // OIDC configuration  
  oidcIssuer?: string;
  oidcClientId?: string;
  oidcClientSecret?: string;  // Encrypted at rest
  
  // Attribute mapping
  attributeMapping: {
    email: string;            // Path to email in assertion
    firstName?: string;
    lastName?: string;
    groups?: string;
  };
  
  // Role assignment
  defaultRole: string;
  groupRoleMapping: Record<string, string>; // IdP group -> app role
}
 
// Determine SSO connection from email
async function detectSSOConnection(email: string): Promise<SSOConnection | null> {
  const domain = email.split('@')[1];
  
  const connection = await db.ssoConnections.findOne({
    domains: domain,
    enabled: true,
  });
  
  return connection;
}
 
// Login flow with SSO detection
async function initiateLogin(email: string): Promise<LoginAction> {
  const ssoConnection = await detectSSOConnection(email);
  
  if (ssoConnection) {
    if (ssoConnection.enforced) {
      // Must use SSO, no password option
      return { 
        action: 'redirect_sso', 
        ssoUrl: generateSSOUrl(ssoConnection),
      };
    } else {
      // SSO available but optional
      return {
        action: 'choice',
        options: ['password', 'sso'],
        ssoUrl: generateSSOUrl(ssoConnection),
      };
    }
  }
  
  // No SSO configured, use password
  return { action: 'password_prompt' };
}

Simplify with SSO Platforms

Building multi-provider SSO from scratch is complex. Platforms like Auth0, WorkOS, Clerk, and Stytch handle SAML/OIDC integration, certificate management, and multi-tenancy. Evaluate build vs buy carefully—SSO is not your core product.

Session Management in SSO

SSO introduces session management complexity that single-application authentication doesn't face. Users now have sessions at both the IdP and each SP, and these sessions must coordinate correctly.

Session Types in SSO:

SSO Session Architecture

•IdP Session — The session at the Identity Provider (e.g., Okta). As long as this is active, the user won't need to re-authenticate at the IdP.
•SP Sessions — Independent sessions at each Service Provider. Each app tracks its own session duration.
•Token Lifetime — Access tokens have limited validity (often 1 hour); refresh tokens can have much longer lifetimes.

Single Logout (SLO) Challenge:

When a user logs out of one application, should they be logged out of all applications? This is Single Logout, and it's notoriously difficult to implement correctly.

SAML Single Logout:

User clicks 'Logout' on App A (an SP)
App A sends SAML LogoutRequest to IdP
IdP sends LogoutRequest to all other SPs where this user has sessions
Each SP terminates the user's session and responds
IdP terminates IdP session and responds to App A
App A confirms logout to user

Problems:

Requires all SPs to implement SLO endpoints
Browser tab coordination is imperfect
Network failures leave sessions active
Mobile apps don't receive SLO signals
Users may have bookmarked apps directly

SLO Often Fails in Practice

Many organizations disable SAML SLO because it's unreliable and creates confusing user experiences. If perfect logout across all apps is required, consider short-lived sessions with forced re-authentication rather than attempting to coordinate logout across a federation.

Alternative Approaches:

Short-Lived SP Sessions — SP sessions expire after 4-8 hours; user re-authenticates against IdP (which still has session) seamlessly.
Front-Channel Logout in OIDC — IdP renders invisible iframes to each SP's logout endpoint. More reliable than SAML back-channel.
Token Revocation Checking — SP periodically calls IdP to verify session/token is still valid via introspection or userinfo call.
Session Sync Service — Custom service that SPs check before honoring any request; IdP updates this on logout.

Session Timeout Strategies:

Balance security and usability:

Critical apps (banking): 15-30 minute idle timeout, 8 hour absolute timeout
Productivity apps (email): 8 hour idle, 24 hour absolute
Low-risk apps: 24 hour idle, 7 day absolute
All apps: Re-authenticate for sensitive actions regardless of session age

Security Considerations for Federation

Federation introduces security risks that don't exist in self-contained authentication. You're now trusting external identity providers and accepting cryptographic assertions from systems outside your control.

Federation Security Risks and Mitigations
Risk	Description	Mitigation
IdP Compromise	If the IdP is breached, attackers can generate valid assertions	Strong IdP security, MFA at IdP, breach monitoring
Signature Bypass	Vulnerabilities in assertion validation allow forgery	Use battle-tested libraries; never custom XML parsing
Token Theft	Access tokens or SAML assertions intercepted	HTTPS everywhere; short token lifetimes; token binding
Session Fixation	Attacker sets session before SSO login completes	Regenerate session IDs after login; validate state parameter
Open Redirect	Redirect parameter manipulation after login	Strict redirect URL validation; whitelist allowed URLs
Account Takeover via Linking	Attacker links their IdP to victim's account	Verify email ownership before linking; notify user
Privilege Escalation via Attributes	Attacker modifies claims at IdP to gain access	Attribute validation; don't blindly trust group memberships

Assertion Validation Checklist:

Every assertion/token received must be validated:

Assertion Validation Steps

•Signature — Verify cryptographic signature using trusted IdP public key. Reject unsigned or improperly signed assertions.
•Issuer — Confirm the issuer matches the expected IdP. Reject assertions from unknown issuers.
•Audience — Verify the assertion is intended for your SP (your entity ID in SAML; your client_id in OIDC).
•Timing — Check NotBefore, NotOnOrAfter conditions. Reject expired or not-yet-valid assertions.
•Replay — Track assertion IDs; reject duplicates within validity window.
•Destination — Confirm Destination matches your ACS URL (SAML).
•Nonce — Verify nonce matches original request (OIDC).
•State — Verify state parameter matches original request (OIDC/OAuth).

XML Signature Wrapping Attacks

SAML has a history of XML signature wrapping vulnerabilities where attackers manipulate XML structure while preserving valid signatures. The unsigned portions contain attacker-controlled data. Never parse SAML XML manually; use libraries specifically designed for SAML that understand these attack classes.

Summary: SSO and Federation Mastery

SSO and federation are essential capabilities for modern applications—enabling seamless user experiences while maintaining centralized security control. Understanding both enterprise (SAML) and modern (OIDC) approaches ensures you can integrate with any identity ecosystem.

Key Takeaways

•SSO vs Federation — SSO is the user experience; federation is the trust architecture. Both require careful implementation.
•SAML 2.0 dominates enterprise — Mature, widely supported, XML-based. Assertions must be cryptographically validated.
•OIDC is the modern standard — JSON-based, mobile-friendly, well-defined discovery. Use Authorization Code + PKCE flow.
•Social login reduces friction — Major providers use OAuth/OIDC. Account linking requires careful design for email conflicts.
•Enterprise SSO is table stakes — B2B products must support SAML/OIDC, SCIM provisioning, and domain enforcement.
•Session management is complex — IdP and SP sessions are independent; Single Logout is notoriously unreliable.
•Federation introduces trust risks — You're accepting assertions from external systems; validate everything cryptographically.

What's Next:

The final page of this module explores Passwordless Authentication—the emerging paradigm that replaces passwords entirely with cryptographic keys, biometrics, and magic links. We'll examine WebAuthn passkeys, email magic links, biometric-only flows, and how to design systems that never require users to remember secrets.

Page Complete

You now understand SSO and federation from architectural principles through implementation details. You can integrate with enterprise identity providers via SAML or OIDC, implement social login with proper account linking, design multi-tenant SSO configurations, and secure federated authentication against common attacks.

4 / 5

Loading learning content...

System Design (HLD)Authentication Patterns

Authentication Patterns in Distributed Systems

LevelIntermediate

Duration75 mins

TopicAuthentication Patterns

4 / 5

SSO and Federation

One Identity, Many Doors

What You Will Learn

Understanding SSO and Federation

Single Sign-On (SSO) and Identity Federation are related but distinct concepts:

SSO is the user experience: authenticate once, access many applications without re-authenticating.
Federation is the trust architecture: multiple independent organizations or services accept authentication performed by a trusted identity provider.

Key Terminology:

SSO and Federation Terminology
Term	Definition	Example
Identity Provider (IdP)	The system that authenticates users and issues identity assertions	Okta, Azure AD, Auth0, Google
Service Provider (SP)	The application that relies on the IdP for authentication	Salesforce, Slack, your internal apps
Relying Party (RP)	Synonym for Service Provider in OIDC terminology	Your web application
Assertion/Token	Cryptographic proof of authentication from IdP	SAML assertion, OIDC ID token
Federation Trust	The configured relationship between IdP and SP	Company A trusts Company B's IdP
Claims/Attributes	User information in the assertion (name, email, groups)	email=alice@corp.com, groups=[engineering, admin]

Why SSO Matters:

Benefits of SSO

•Reduced Password Fatigue — Users remember one password, not dozens
•Centralized Security — MFA, policy enforcement, and monitoring in one place
•Instant Deprovisioning — Disable one account, revoke access everywhere
•Audit Trail — Single log of all authentication events
•Improved Compliance — Easier to enforce password policies, access reviews

SSO Risks to Manage

•Single Point of Failure — IdP outage blocks access to everything
•Blast Radius — Compromised account has access everywhere
•Integration Complexity — Each SP has unique requirements
•Session Management — Logout must propagate across all SPs
•Vendor Lock-in — Migrating IdPs is complex and risky

SSO Amplifies Account Compromise

SAML 2.0: Enterprise Federation

SAML Core Concepts:

Assertions — XML documents containing statements about a user (authentication, attributes, authorization decisions)
Bindings — How SAML messages are transported (HTTP POST, HTTP Redirect, SOAP)
Profiles — Defined flows for specific use cases (Web Browser SSO, Single Logout)

The SAML Web Browser SSO Flow:

SP-Initiated SAML Flow

•User Accesses SP — User navigates to app.example.com (the Service Provider); no session exists.
•SP Generates AuthnRequest — SP creates a SAML AuthnRequest and redirects user to IdP (idp.corp.com).
•User Authenticates at IdP — IdP prompts user for credentials (if no IdP session) and performs authentication.
•IdP Generates Assertion — IdP creates a signed SAML assertion containing user identity and attributes.
•Assertion Sent to SP — IdP posts the assertion to the SP's Assertion Consumer Service (ACS) URL via user's browser.
•SP Validates Assertion — SP verifies signature using IdP's public key, checks conditions (timestamps, audience), extracts user identity.
•SP Creates Session — SP establishes a local session for the user; user is now logged in.

SAML Assertion Structure:

A SAML assertion is an XML document with three main sections:

Issuer — Identifies the IdP that created the assertion
Subject — Identifies the user (NameID format varies: email, persistent ID, transient ID)
Conditions — Validity constraints: NotBefore, NotOnOrAfter, AudienceRestriction
AuthnStatement — When and how the user authenticated
AttributeStatement — User attributes (email, groups, department, etc.)

<saml:Assertion ...>
  <saml:Issuer>https://idp.corp.com</saml:Issuer>
  <saml:Subject>
    <saml:NameID>alice@corp.com</saml:NameID>
  </saml:Subject>
  <saml:Conditions NotBefore="..." NotOnOrAfter="...">
    <saml:AudienceRestriction>
      <saml:Audience>https://app.example.com</saml:Audience>
    </saml:AudienceRestriction>
  </saml:Conditions>
  <saml:AttributeStatement>
    <saml:Attribute Name="groups">
      <saml:AttributeValue>engineering</saml:AttributeValue>
      <saml:AttributeValue>admin</saml:AttributeValue>
    </saml:Attribute>
  </saml:AttributeStatement>
  <ds:Signature>...</ds:Signature>
</saml:Assertion>

SAML Signature Validation Is Critical

SAML Configuration Checklist
Configuration Item	Purpose	Security Note
IdP Metadata URL	Contains IdP's signing certificate, SSO endpoint	Fetch from HTTPS; verify certificate
SP Entity ID	Unique identifier for your SP	Must match AudienceRestriction in assertions
ACS URL	Where IdP posts assertions	Must be HTTPS; validate in assertion Destination
Signing Certificate	SP's private key for signing requests	Protect private key; rotate periodically
NameID Format	How users are identified	Persistent for long-lived accounts; email for simplicity
Attribute Mapping	Map SAML attributes to your user model	Validate expected attributes exist

OAuth 2.0 and OpenID Connect

OAuth 2.0 is an authorization framework—it answers 'What can this app access on the user's behalf?' not 'Who is this user?' OIDC adds identity by defining:

ID Token — A JWT containing user identity claims
UserInfo Endpoint — API to fetch additional user attributes
Standard Claims — Defined schema for user information (sub, email, name, etc.)
Discovery — Standardized way to find provider endpoints

OAuth 2.0 Grant Types
Grant Type	Use Case	Token Flow
Authorization Code	Server-side web apps, SPAs (with PKCE)	User redirected to IdP; code exchanged for tokens
Authorization Code + PKCE	Public clients (mobile, SPA) that can't keep secrets	Same as above with code_verifier proof
Client Credentials	Machine-to-machine, no user context	App authenticates with client_id + secret
Device Code	Input-constrained devices (TV, CLI)	User authorizes on different device
Implicit (Deprecated)	Legacy SPAs without backend	Tokens in URL fragment; avoid for new apps
Password (Deprecated)	Legacy trusted first-party apps	Direct password exchange; avoid entirely

The Authorization Code Flow with PKCE:

This is the recommended flow for most web and mobile applications:

OIDC Authorization Code Flow

•Generate PKCE Codes — Client creates random code_verifier and derives code_challenge (SHA256 hash).
•Redirect to Authorization — Client redirects user to IdP's /authorize endpoint with code_challenge, redirect_uri, scope (openid profile email), and state.
•User Authenticates — IdP prompts user; user logs in and consents to requested scopes.
•Authorization Code Returned — IdP redirects to redirect_uri with authorization code and original state.
•Token Exchange — Client calls /token endpoint with code, code_verifier, and client credentials.
•Tokens Returned — IdP validates code_verifier matches original challenge; returns access_token, id_token, and optionally refresh_token.
•Validate ID Token — Client validates JWT signature, issuer, audience, expiration, and nonce.

OIDC Integration
Node.js
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
import { Issuer, generators } from 'openid-client';
 
// Configuration
const OIDC_ISSUER = 'https://accounts.google.com';
const CLIENT_ID = process.env.GOOGLE_CLIENT_ID!;
const CLIENT_SECRET = process.env.GOOGLE_CLIENT_SECRET!;
const REDIRECT_URI = 'https://myapp.com/callback';
 
// Discover OIDC provider endpoints
const googleIssuer = await Issuer.discover(OIDC_ISSUER);
console.log('Discovered issuer:', googleIssuer.metadata);
 
// Create client
const client = new googleIssuer.Client({
  client_id: CLIENT_ID,
  client_secret: CLIENT_SECRET,
  redirect_uris: [REDIRECT_URI],
  response_types: ['code'],
});
 
// Step 1: Generate authorization URL
function generateAuthUrl(req: Request): string {
  const code_verifier = generators.codeVerifier();
  const code_challenge = generators.codeChallenge(code_verifier);
  const state = generators.state();
  const nonce = generators.nonce();
  
  // Store in session for callback validation
  req.session.oidc = { code_verifier, state, nonce };
  
  return client.authorizationUrl({
    scope: 'openid email profile',
    code_challenge,
    code_challenge_method: 'S256',
    state,
    nonce,
  });
}
 
// Step 2: Handle callback
async function handleCallback(req: Request) {
  const { code_verifier, state, nonce } = req.session.oidc;
  const params = client.callbackParams(req);
  
  // Exchange code for tokens
  const tokenSet = await client.callback(
    REDIRECT_URI,
    params,
    { 
      code_verifier, 
      state,
      nonce,  // Validates nonce claim in id_token
    }
  );
  
  // Token validation happens automatically
  console.log('ID Token claims:', tokenSet.claims());
  // { sub: '123456789', email: 'user@gmail.com', name: 'Alice', ... }
  
  // Fetch additional user info if needed
  const userinfo = await client.userinfo(tokenSet.access_token!);
  
  return {
    userId: tokenSet.claims().sub,
    email: tokenSet.claims().email,
    name: tokenSet.claims().name,
    accessToken: tokenSet.access_token,
    refreshToken: tokenSet.refresh_token,
  };
}

Why PKCE Matters

Social Login Integration

Implementation Considerations:

Social Login Providers
Provider	Protocol	Key Considerations	Audience
Google	OIDC	Widely trusted; good OIDC compliance; email verified	Consumer, enterprise (Workspace)
Apple	OIDC	Required for iOS apps with social login; email relay option	Consumer, especially iOS users
Facebook	OAuth 2.0 (not OIDC)	Large user base; privacy concerns; uses custom endpoints	Consumer
Microsoft	OIDC	Personal and work accounts; Azure AD integration	Consumer, enterprise
GitHub	OAuth 2.0	Developer-focused; access to repos if scoped	Developer tools, open source
Twitter/X	OAuth 2.0	Limited user info; frequent API changes	Social apps, news

Account Linking Challenges:

When users can log in with multiple methods (email/password, Google, GitHub), you need an account linking strategy:

Same Email = Same Account? — If a user signs up with email alice@gmail.com, then later clicks 'Sign in with Google' using the same email, are these the same account? Usually yes, but requires verification.
Email Verification — Social providers typically guarantee email verification. If they don't (or you can't confirm), you might be linking to the wrong account.
Multiple Social Accounts — A user might want to link both Google and GitHub. Design for this from the start.
Orphaned Accounts — What happens if a user deletes their Google account? They need an alternative login method.

Account Linking Design:

Account Linking Strategy
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
interface User {
  id: string;
  email: string;
  emailVerified: boolean;
  passwordHash?: string;           // Optional if only social
  linkedAccounts: LinkedAccount[];
}
 
interface LinkedAccount {
  provider: 'google' | 'github' | 'apple' | 'facebook';
  providerUserId: string;          // Unique ID from provider
  email?: string;                  // Email from this provider
  linkedAt: Date;
}
 
async function handleSocialLogin(
  provider: string,
  providerUserId: string,
  providerEmail: string,
  emailVerified: boolean
): Promise<{ user: User; isNewUser: boolean }> {
  
  // 1. Check if this provider account is already linked
  const existingLink = await db.linkedAccounts.findOne({
    provider,
    providerUserId,
  });
  
  if (existingLink) {
    // Known user, return their account
    const user = await db.users.findById(existingLink.userId);
    return { user, isNewUser: false };
  }
  
  // 2. Check if email matches an existing user
  if (providerEmail && emailVerified) {
    const existingUser = await db.users.findByEmail(providerEmail);
    
    if (existingUser) {
      // Link this provider to existing account
      await db.linkedAccounts.create({
        userId: existingUser.id,
        provider,
        providerUserId,
        email: providerEmail,
        linkedAt: new Date(),
      });
      
      // Optionally notify user of new linked account
      await sendEmail(existingUser.email, 
        'New login method added',
        `Your ${provider} account is now linked...`
      );
      
      return { user: existingUser, isNewUser: false };
    }
  }
  
  // 3. Create new user
  const newUser = await db.users.create({
    email: providerEmail,
    emailVerified: emailVerified,
    linkedAccounts: [{
      provider,
      providerUserId,
      email: providerEmail,
      linkedAt: new Date(),
    }],
  });
  
  return { user: newUser, isNewUser: true };
}

Apple's Privacy Requirements

Enterprise SSO Integration

Enterprise SSO Requirements:

What Enterprises Expect

•SAML 2.0 Support — Most enterprise IdPs (Okta, Azure AD, OneLogin, Ping) support SAML. You must be a SAML SP.
•OIDC Support — Modern alternative to SAML; increasingly preferred for new integrations.
•JIT Provisioning — Automatically create user accounts on first SSO login; no manual user creation.
•SCIM Provisioning — System for Cross-domain Identity Management for full lifecycle management (create, update, deactivate).
•Attribute Mapping — Map IdP attributes (groups, department) to your application's roles and permissions.
•Domain Verification — Prove ownership of email domain before enabling SSO for @company.com addresses.
•SSO Enforcement — Option to require SSO for all users on a domain; disable password login.

Multi-Tenancy Considerations:

B2B SaaS applications typically support multiple enterprise customers, each with their own IdP configuration:

Multi-Tenant SSO Architecture
Approach	Description	Trade-offs
Subdomain per Tenant	customer1.app.com, customer2.app.com	Clean separation; more infrastructure complexity
Email Domain Detection	Detect SSO config from email domain at login	Simple UX; requires email upfront; domain conflicts possible
Tenant Selector	User selects organization from list	Clear intent; extra step; works for multi-domain orgs
Connection ID in URL	Login links include tenant identifier	Works for IdP-initiated flows; less discoverable

Multi-Tenant SSO Configuration
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
interface SSOConnection {
  id: string;
  organizationId: string;
  provider: 'saml' | 'oidc';
  enabled: boolean;
  domains: string[];           // Verified email domains
  enforced: boolean;           // Require SSO, disable password
  
  // SAML configuration
  samlIdpEntityId?: string;
  samlSsoUrl?: string;
  samlCertificate?: string;
  samlNameIdFormat?: string;
  
  // OIDC configuration  
  oidcIssuer?: string;
  oidcClientId?: string;
  oidcClientSecret?: string;  // Encrypted at rest
  
  // Attribute mapping
  attributeMapping: {
    email: string;            // Path to email in assertion
    firstName?: string;
    lastName?: string;
    groups?: string;
  };
  
  // Role assignment
  defaultRole: string;
  groupRoleMapping: Record<string, string>; // IdP group -> app role
}
 
// Determine SSO connection from email
async function detectSSOConnection(email: string): Promise<SSOConnection | null> {
  const domain = email.split('@')[1];
  
  const connection = await db.ssoConnections.findOne({
    domains: domain,
    enabled: true,
  });
  
  return connection;
}
 
// Login flow with SSO detection
async function initiateLogin(email: string): Promise<LoginAction> {
  const ssoConnection = await detectSSOConnection(email);
  
  if (ssoConnection) {
    if (ssoConnection.enforced) {
      // Must use SSO, no password option
      return { 
        action: 'redirect_sso', 
        ssoUrl: generateSSOUrl(ssoConnection),
      };
    } else {
      // SSO available but optional
      return {
        action: 'choice',
        options: ['password', 'sso'],
        ssoUrl: generateSSOUrl(ssoConnection),
      };
    }
  }
  
  // No SSO configured, use password
  return { action: 'password_prompt' };
}

Simplify with SSO Platforms

Session Management in SSO

SSO introduces session management complexity that single-application authentication doesn't face. Users now have sessions at both the IdP and each SP, and these sessions must coordinate correctly.

Session Types in SSO:

SSO Session Architecture

•IdP Session — The session at the Identity Provider (e.g., Okta). As long as this is active, the user won't need to re-authenticate at the IdP.
•SP Sessions — Independent sessions at each Service Provider. Each app tracks its own session duration.
•Token Lifetime — Access tokens have limited validity (often 1 hour); refresh tokens can have much longer lifetimes.

Single Logout (SLO) Challenge:

When a user logs out of one application, should they be logged out of all applications? This is Single Logout, and it's notoriously difficult to implement correctly.

SAML Single Logout:

User clicks 'Logout' on App A (an SP)
App A sends SAML LogoutRequest to IdP
IdP sends LogoutRequest to all other SPs where this user has sessions
Each SP terminates the user's session and responds
IdP terminates IdP session and responds to App A
App A confirms logout to user

Problems:

Requires all SPs to implement SLO endpoints
Browser tab coordination is imperfect
Network failures leave sessions active
Mobile apps don't receive SLO signals
Users may have bookmarked apps directly

SLO Often Fails in Practice

Alternative Approaches:

Short-Lived SP Sessions — SP sessions expire after 4-8 hours; user re-authenticates against IdP (which still has session) seamlessly.
Front-Channel Logout in OIDC — IdP renders invisible iframes to each SP's logout endpoint. More reliable than SAML back-channel.
Token Revocation Checking — SP periodically calls IdP to verify session/token is still valid via introspection or userinfo call.
Session Sync Service — Custom service that SPs check before honoring any request; IdP updates this on logout.

Session Timeout Strategies:

Balance security and usability:

Critical apps (banking): 15-30 minute idle timeout, 8 hour absolute timeout
Productivity apps (email): 8 hour idle, 24 hour absolute
Low-risk apps: 24 hour idle, 7 day absolute
All apps: Re-authenticate for sensitive actions regardless of session age

Security Considerations for Federation

Federation Security Risks and Mitigations
Risk	Description	Mitigation
IdP Compromise	If the IdP is breached, attackers can generate valid assertions	Strong IdP security, MFA at IdP, breach monitoring
Signature Bypass	Vulnerabilities in assertion validation allow forgery	Use battle-tested libraries; never custom XML parsing
Token Theft	Access tokens or SAML assertions intercepted	HTTPS everywhere; short token lifetimes; token binding
Session Fixation	Attacker sets session before SSO login completes	Regenerate session IDs after login; validate state parameter
Open Redirect	Redirect parameter manipulation after login	Strict redirect URL validation; whitelist allowed URLs
Account Takeover via Linking	Attacker links their IdP to victim's account	Verify email ownership before linking; notify user
Privilege Escalation via Attributes	Attacker modifies claims at IdP to gain access	Attribute validation; don't blindly trust group memberships

Assertion Validation Checklist:

Every assertion/token received must be validated:

Assertion Validation Steps

•Signature — Verify cryptographic signature using trusted IdP public key. Reject unsigned or improperly signed assertions.
•Issuer — Confirm the issuer matches the expected IdP. Reject assertions from unknown issuers.
•Audience — Verify the assertion is intended for your SP (your entity ID in SAML; your client_id in OIDC).
•Timing — Check NotBefore, NotOnOrAfter conditions. Reject expired or not-yet-valid assertions.
•Replay — Track assertion IDs; reject duplicates within validity window.
•Destination — Confirm Destination matches your ACS URL (SAML).
•Nonce — Verify nonce matches original request (OIDC).
•State — Verify state parameter matches original request (OIDC/OAuth).

XML Signature Wrapping Attacks

Summary: SSO and Federation Mastery

Key Takeaways

•SSO vs Federation — SSO is the user experience; federation is the trust architecture. Both require careful implementation.
•SAML 2.0 dominates enterprise — Mature, widely supported, XML-based. Assertions must be cryptographically validated.
•OIDC is the modern standard — JSON-based, mobile-friendly, well-defined discovery. Use Authorization Code + PKCE flow.
•Social login reduces friction — Major providers use OAuth/OIDC. Account linking requires careful design for email conflicts.
•Enterprise SSO is table stakes — B2B products must support SAML/OIDC, SCIM provisioning, and domain enforcement.
•Session management is complex — IdP and SP sessions are independent; Single Logout is notoriously unreliable.
•Federation introduces trust risks — You're accepting assertions from external systems; validate everything cryptographically.

What's Next:

Page Complete

4 / 5