OpenID Connect for… — OAuth2 and OpenID Connect | OneNoughtOne

0/121

System Design (HLD)OAuth2 and OpenID Connect

OAuth2 and OpenID Connect

LevelIntermediate

Duration90 mins

TopicOAuth2 and OpenID Connect

3 / 5

OpenID Connect for Identity

From Authorization to Authentication

OAuth 2.0 solved the delegation problem brilliantly—allowing third-party applications to access resources without sharing passwords. But it left a critical gap: OAuth 2.0 is an authorization framework, not an authentication protocol . It can tell you what someone is allowed to do, but not who that someone actually is. This distinction might seem academic, but it's profound. Applications using OAuth 2.0 alone for login were essentially saying "someone with a valid token wants in"—without standardized verification of who that someone was. Different providers implemented user identity differently, creating fragmentation and security gaps. OpenID Connect (OIDC) emerged as the solution—an identity layer built on top of OAuth 2.0. It adds standardized authentication, user identity claims, and a consistent way to verify "this is who they say they are." Today, OIDC powers login experiences across Google, Microsoft, Apple, Okta, Auth0, and virtually every modern identity provider.

What You Will Learn

By the end of this page, you will understand the critical difference between OAuth 2.0 and OIDC, master ID token structure and claims, implement OIDC authentication flows correctly, and leverage OIDC's standardized endpoints for robust identity verification.

OAuth 2.0 vs OpenID Connect

Understanding the relationship between OAuth 2.0 and OpenID Connect is fundamental. They're not competitors—OIDC is built on OAuth 2.0, extending it with identity capabilities. OAuth 2.0 Alone: Answers: "Is this client authorized to access this resource?" Returns: Access token (authorization credential) Use case: Third-party app accessing user's Google Drive files OpenID Connect (OAuth 2.0 + Identity Layer): Answers: "Who is this user?" + "Is this client authorized?" Returns: ID token (identity credential) + Access token (authorization credential) Use case: "Sign in with Google" to authenticate users

OAuth 2.0 vs OpenID Connect Comparison
Aspect	OAuth 2.0	OpenID Connect
Primary Purpose	Delegated authorization	Authentication + Authorization
Core Question	What can this client access?	Who is this user?
Key Token	Access Token	ID Token + Access Token
User Info	Non-standard, varies by provider	Standardized claims (sub, email, name, etc.)
Discovery	No standard mechanism	/.well-known/openid-configuration
Scopes	Provider-defined	Standard: openid, profile, email, phone, address
Token Format	Often opaque or JWT	ID Token must be JWT
Client Auth	Optional	Often required for confidential clients

The 'Login with OAuth' Anti-Pattern

Using pure OAuth 2.0 for login (without OIDC) is a common mistake. Getting an access token proves the user authorized something, but not who authorized it. An attacker could potentially inject a token obtained elsewhere. OIDC's ID token, with proper validation, provides cryptographic proof of identity. Always use OIDC for authentication, not bare OAuth 2.0.

The Simple Distinction: Think of a hotel key card: OAuth 2.0 is like the key card itself—it grants access to specific rooms (resources) but doesn't identify the holder. OpenID Connect adds a photo ID to verify the person using the key card is who they claim to be. Both are needed for a complete identity and access management solution.

The ID Token: OIDC's Core Innovation

The ID Token is OIDC's key contribution—a JWT that conveys identity claims about the authenticated user. Unlike access tokens (which may be opaque), ID tokens are always JWTs with a standardized structure. ID Token Structure: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6Imtex123"}. eyJpc3MiOiJodHRwczovL2FjY291bnRzLmdvb2dsZS5jb20iLCJzdWIiOiIxMT AwMjIzMzQ0NTU2Njc3ODgiLCJhdWQiOiJteWFwcC5jbGllbnRpZCIsImV4cCI 6MTcwNDEyMzQ1NiwiaWF0IjoxNzA0MTE5ODU2LCJub25jZSI6ImFiY2RlZjE yMzQ1NiIsImVtYWlsIjoidXNlckBleGFtcGxlLmNvbSIsImVtYWlsX3Zlcmlma WVkIjp0cnVlLCJuYW1lIjoiSm9obiBEb2UifQ. [signature] The three parts (header, payload, signature) are base64url-encoded and separated by dots.

Required ID Token Claims
Claim	Name	Description	Example
iss	Issuer	URL of the token issuer (IdP)	https://accounts.google.com
sub	Subject	Unique identifier for the user (stable, opaque)	110022334455667788
aud	Audience	Client ID(s) this token is intended for	myapp.clientid
exp	Expiration Time	Unix timestamp when token expires	1704123456
iat	Issued At	Unix timestamp when token was issued	1704119856

Common Optional Claims
Claim	Scope Required	Description
nonce	openid	Ties token to specific auth request (replay protection)
auth_time	openid	When user last actively authenticated
acr	openid	Authentication Context Class Reference (security level)
email	email	User's email address
email_verified	email	Whether email has been verified (boolean)
name	profile	User's full name
given_name	profile	First/given name
family_name	profile	Last/family name
picture	profile	URL to user's profile picture
phone_number	phone	User's phone number
address	address	User's physical address (JSON object)

id-token-example.ts
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
// Decoded ID Token Payload Example
interface IDTokenPayload {
    // Required claims
    iss: string;       // "https://accounts.google.com"
    sub: string;       // "110022334455667788" - stable user identifier
    aud: string | string[]; // "myapp.clientid" or ["client1", "client2"]
    exp: number;       // 1704123456 - expiration timestamp
    iat: number;       // 1704119856 - issued at timestamp
    
    // Recommended for security
    nonce?: string;    // "abc123" - ties request to response
    auth_time?: number; // 1704119800 - when user actually authenticated
    
    // Standard claims from scopes
    email?: string;         // "user@example.com"
    email_verified?: boolean; // true
    name?: string;          // "John Doe"
    given_name?: string;    // "John"
    family_name?: string;   // "Doe"
    picture?: string;       // "https://example.com/photo.jpg"
    
    // Additional context
    acr?: string;      // "urn:mace:incommon:iap:silver" - auth assurance level
    amr?: string[];    // ["pwd", "mfa"] - auth methods used
    azp?: string;      // Authorized party - client that auth'd
}
 
// Example decoded token
const exampleToken: IDTokenPayload = {
    iss: "https://accounts.google.com",
    sub: "110022334455667788",
    aud: "123456789.apps.googleusercontent.com",
    exp: 1704123456,
    iat: 1704119856,
    nonce: "n-0S6_WzA2Mj",
    email: "user@example.com",
    email_verified: true,
    name: "Jane Smith",
    given_name: "Jane",
    family_name: "Smith",
    picture: "https://lh3.googleusercontent.com/a/photo.jpg",
    auth_time: 1704119800,
    acr: "0", // Basic password authentication
    amr: ["pwd"],
};

Sub Claim is Your Stable Identifier

The 'sub' (subject) claim is the only guaranteed stable identifier. Email addresses can change. Names can change. But 'sub' is immutable for a given user at a given issuer. Always use 'sub' (combined with 'iss') as your primary key for user records—never rely on email as the unique identifier.

OIDC Authentication Flow

OIDC authentication builds on OAuth 2.0 Authorization Code flow with specific additions for identity. The key differences:'openid' scope is required — Signals you want OIDC, not just OAuth ID token returned — In addition to access token nonce parameter — Binds authorization request to token (prevents replay) Standardized endpoints — discovery, userinfo The Flow:

OIDC Authorization Code Flow
Step	Description	OIDC-Specific Elements
Auth Request	Client redirects user to authorization endpoint	scope=openid, nonce parameter
Authentication	User authenticates with IdP (password, MFA, etc.)	IdP handles all auth complexity
Consent	User approves requested scopes	Standard OIDC scopes shown clearly
Auth Response	Redirect back with authorization code	Same as OAuth 2.0
Token Request	Exchange code for tokens	Returns ID token + access token
Token Validation	Verify ID token signature, claims	Comprehensive validation required
UserInfo (optional)	Fetch additional claims via UserInfo endpoint	Access token authenticates request

oidc-flow-implementation.ts
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
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
// Complete OIDC Authentication Flow Implementation
import * as jose from 'jose';
 
interface OIDCConfig {
    clientId: string;
    clientSecret: string;
    redirectUri: string;
    issuer: string;
    scopes: string[];
}
 
interface TokenResponse {
    access_token: string;
    id_token: string;
    token_type: string;
    expires_in: number;
    refresh_token?: string;
    scope: string;
}
 
class OIDCClient {
    private discoveryDoc: any = null;
    private jwks: jose.JWTVerifyGetKey | null = null;
    
    constructor(private config: OIDCConfig) {}
    
    // Step 1: Fetch OIDC discovery document
    async initialize(): Promise<void> {
        const discoveryUrl = `${this.config.issuer}/.well-known/openid-configuration`;
        const response = await fetch(discoveryUrl);
        this.discoveryDoc = await response.json();
        
        // Fetch JWKS for token verification
        this.jwks = jose.createRemoteJWKSet(
            new URL(this.discoveryDoc.jwks_uri)
        );
    }
    
    // Step 2: Generate authorization URL
    generateAuthUrl(state: string, nonce: string): string {
        const url = new URL(this.discoveryDoc.authorization_endpoint);
        url.searchParams.set('client_id', this.config.clientId);
        url.searchParams.set('redirect_uri', this.config.redirectUri);
        url.searchParams.set('response_type', 'code');
        url.searchParams.set('scope', this.config.scopes.join(' '));
        url.searchParams.set('state', state);
        url.searchParams.set('nonce', nonce); // OIDC-specific: replay protection
        
        return url.toString();
    }
    
    // Step 3: Exchange code for tokens
    async exchangeCode(code: string): Promise<TokenResponse> {
        const response = await fetch(this.discoveryDoc.token_endpoint, {
            method: 'POST',
            headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
            body: new URLSearchParams({
                grant_type: 'authorization_code',
                code,
                client_id: this.config.clientId,
                client_secret: this.config.clientSecret,
                redirect_uri: this.config.redirectUri,
            }),
        });
        
        if (!response.ok) {
            throw new Error(`Token request failed: ${response.status}`);
        }
        
        return response.json();
    }
    
    // Step 4: Validate ID token (CRITICAL!)
    async validateIdToken(
        idToken: string,
        expectedNonce: string
    ): Promise<jose.JWTPayload> {
        if (!this.jwks) {
            throw new Error('Client not initialized');
        }
        
        // Verify signature and standard claims
        const { payload, protectedHeader } = await jose.jwtVerify(
            idToken,
            this.jwks,
            {
                issuer: this.config.issuer,
                audience: this.config.clientId,
                maxTokenAge: '10 minutes', // ID tokens should be fresh
            }
        );
        
        // Additional OIDC-specific validations
        
        // 1. Verify nonce matches (prevents replay/injection)
        if (payload.nonce !== expectedNonce) {
            throw new Error('Invalid nonce - possible token injection');
        }
        
        // 2. iat (issued at) should be in the past
        if (payload.iat && payload.iat > Math.floor(Date.now() / 1000)) {
            throw new Error('Token issued in the future');
        }
        
        // 3. If azp (authorized party) present, must match client_id
        if (payload.azp && payload.azp !== this.config.clientId) {
            throw new Error('Token not authorized for this client');
        }
        
        return payload;
    }
    
    // Optional: Fetch additional user info
    async getUserInfo(accessToken: string): Promise<any> {
        const response = await fetch(this.discoveryDoc.userinfo_endpoint, {
            headers: { 'Authorization': `Bearer ${accessToken}` },
        });
        
        return response.json();
    }
    
    // Complete authentication flow
    async handleCallback(
        code: string,
        expectedState: string,
        actualState: string,
        expectedNonce: string
    ): Promise<{ user: any; tokens: TokenResponse }> {
        // Verify state
        if (actualState !== expectedState) {
            throw new Error('Invalid state - CSRF detected');
        }
        
        // Exchange code for tokens
        const tokens = await this.exchangeCode(code);
        
        // Validate ID token
        const idTokenClaims = await this.validateIdToken(
            tokens.id_token,
            expectedNonce
        );
        
        // Optionally fetch more user info
        const userInfo = await this.getUserInfo(tokens.access_token);
        
        return {
            user: { ...idTokenClaims, ...userInfo },
            tokens,
        };
    }
}
 
// Usage
const oidcClient = new OIDCClient({
    clientId: 'your-client-id',
    clientSecret: 'your-client-secret',
    redirectUri: 'https://yourapp.com/callback',
    issuer: 'https://accounts.google.com',
    scopes: ['openid', 'email', 'profile'],
});
 
await oidcClient.initialize();

Never Skip ID Token Validation

ID token validation is not optional—it's the core security guarantee of OIDC. Verify the signature using the IdP's public keys. Verify issuer, audience, expiration, and nonce. Skipping these checks means you're trusting whoever can construct a JWT, not who the IdP authenticated.

OIDC Discovery and JWKS

OIDC standardizes how clients discover provider capabilities and public keys—no more hardcoding endpoints or manually managing certificates. Discovery Document: Every OIDC provider publishes a JSON document at /.well-known/openid-configuration containing all endpoints and capabilities. This enables dynamic configuration and automatic handling of endpoint changes.

discovery-document.json
JSON
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
{
  "issuer": "https://accounts.google.com",
  "authorization_endpoint": "https://accounts.google.com/o/oauth2/v2/auth",
  "token_endpoint": "https://oauth2.googleapis.com/token",
  "userinfo_endpoint": "https://openidconnect.googleapis.com/v1/userinfo",
  "revocation_endpoint": "https://oauth2.googleapis.com/revoke",
  "jwks_uri": "https://www.googleapis.com/oauth2/v3/certs",
  "scopes_supported": ["openid", "email", "profile", "phone", "address"],
  "response_types_supported": ["code", "id_token", "code id_token"],
  "grant_types_supported": ["authorization_code", "refresh_token"],
  "subject_types_supported": ["public"],
  "id_token_signing_alg_values_supported": ["RS256"],
  "claims_supported": [
    "sub", "iss", "aud", "exp", "iat", "nonce",
    "email", "email_verified", "name", "given_name",
    "family_name", "picture", "locale"
  ],
  "code_challenge_methods_supported": ["S256", "plain"],
  "token_endpoint_auth_methods_supported": [
    "client_secret_basic", "client_secret_post"
  ]
}

JSON Web Key Set (JWKS): The jwks_uri points to the provider's public keys used to sign ID tokens. Clients fetch these keys to verify token signatures without sharing private keys.

jwks-example.json
JSON
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
  "keys": [
    {
      "kty": "RSA",
      "use": "sig",
      "alg": "RS256",
      "kid": "abc123def456",
      "n": "0vx7agoebGcQ...(modulus in base64url)...",
      "e": "AQAB"
    },
    {
      "kty": "RSA",
      "use": "sig", 
      "alg": "RS256",
      "kid": "xyz789ghi012",
      "n": "1hqLlFJx9vZb...(modulus in base64url)...",
      "e": "AQAB"
    }
  ]
}

JWKS Best Practices

•Cache JWKS but respect expiry — Don't fetch on every request, but refresh periodically (typically 1-24 hours).
•Match 'kid' header to key — ID token header specifies which key ('kid') signed it. Find matching key in JWKS.
•Handle key rotation gracefully — Providers rotate keys. If 'kid' not found, refresh JWKS and retry once.
•Use established libraries — Don't implement JWT verification yourself. Use jose, jsonwebtoken, or equivalent.
•Validate algorithm — Only accept expected algorithms (RS256). Reject None or symmetric algorithms to prevent attacks.

jwks-handling.ts
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
// Production-Ready JWKS Handling with Caching
import * as jose from 'jose';
 
class JWKSManager {
    private jwksCache: Map<string, {
        keys: jose.JWTVerifyGetKey;
        fetchedAt: Date;
    }> = new Map();
    
    private readonly cacheTTL = 60 * 60 * 1000; // 1 hour
    
    async getVerificationKey(issuer: string): Promise<jose.JWTVerifyGetKey> {
        const cached = this.jwksCache.get(issuer);
        
        if (cached && Date.now() - cached.fetchedAt.getTime() < this.cacheTTL) {
            return cached.keys;
        }
        
        // Fetch discovery document
        const discoveryUrl = `${issuer}/.well-known/openid-configuration`;
        const discovery = await fetch(discoveryUrl).then(r => r.json());
        
        // Create JWKS client
        const keys = jose.createRemoteJWKSet(new URL(discovery.jwks_uri));
        
        this.jwksCache.set(issuer, { keys, fetchedAt: new Date() });
        return keys;
    }
    
    async verifyToken(
        token: string,
        expectedIssuer: string,
        expectedAudience: string
    ): Promise<jose.JWTPayload> {
        const keys = await this.getVerificationKey(expectedIssuer);
        
        try {
            const { payload } = await jose.jwtVerify(token, keys, {
                issuer: expectedIssuer,
                audience: expectedAudience,
                algorithms: ['RS256', 'ES256'], // Only allow expected algorithms
            });
            return payload;
        } catch (error) {
            // If key not found, might be rotation - refresh and retry once
            if (error instanceof jose.errors.JWKSNoMatchingKey) {
                this.jwksCache.delete(expectedIssuer);
                const freshKeys = await this.getVerificationKey(expectedIssuer);
                const { payload } = await jose.jwtVerify(token, freshKeys, {
                    issuer: expectedIssuer,
                    audience: expectedAudience,
                    algorithms: ['RS256', 'ES256'],
                });
                return payload;
            }
            throw error;
        }
    }
}

Algorithm Confusion Attacks

Always explicitly specify allowed algorithms. The infamous 'alg: none' attack exploits libraries that blindly trust the token's algorithm claim. By whitelisting only RS256/ES256 (asymmetric), you prevent attackers from switching to symmetric algorithms or disabled signing.

The UserInfo Endpoint

While ID tokens contain identity claims, they're intentionally compact. The UserInfo endpoint provides a way to fetch additional claims about the authenticated user using the access token. When to Use UserInfo: When you need claims beyond what's in the ID token When you need fresh/current data (ID tokens are snapshots) When the ID token would be too large with all needed claims When ID Token is Sufficient: Basic authentication with email/name When you only need stable identifiers (sub) When ID token already includes required claims

userinfo-usage.ts
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
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
// UserInfo Endpoint Usage
interface UserInfoResponse {
    sub: string;              // Always present - matches ID token sub
    name?: string;
    given_name?: string;
    family_name?: string;
    picture?: string;
    email?: string;
    email_verified?: boolean;
    phone_number?: string;
    phone_number_verified?: boolean;
    address?: {
        formatted?: string;
        street_address?: string;
        locality?: string;
        region?: string;
        postal_code?: string;
        country?: string;
    };
    updated_at?: number;
    // Provider-specific claims may be included
    [key: string]: any;
}
 
class UserInfoService {
    constructor(private userInfoEndpoint: string) {}
    
    async getUserInfo(accessToken: string): Promise<UserInfoResponse> {
        const response = await fetch(this.userInfoEndpoint, {
            headers: {
                'Authorization': `Bearer ${accessToken}`,
            },
        });
        
        if (response.status === 401) {
            throw new Error('Access token invalid or expired');
        }
        
        if (!response.ok) {
            throw new Error(`UserInfo request failed: ${response.status}`);
        }
        
        const userInfo = await response.json();
        
        // Validate sub claim matches ID token if available
        return userInfo;
    }
    
    // Fetch and merge with ID token claims
    async getCompleteProfile(
        idTokenClaims: any,
        accessToken: string
    ): Promise<UserInfoResponse> {
        const userInfo = await this.getUserInfo(accessToken);
        
        // Validate consistency
        if (userInfo.sub !== idTokenClaims.sub) {
            throw new Error('UserInfo sub does not match ID token');
        }
        
        // Merge claims (userInfo takes precedence for freshness)
        return {
            ...idTokenClaims,
            ...userInfo,
        };
    }
}
 
// Efficient pattern: Only fetch if needed
async function getUserDetails(
    idTokenClaims: any,
    accessToken: string,
    requiredFields: string[]
): Promise<any> {
    const missingFields = requiredFields.filter(
        field => !(field in idTokenClaims) || idTokenClaims[field] == null
    );
    
    if (missingFields.length === 0) {
        // ID token has everything we need
        return idTokenClaims;
    }
    
    // Need to fetch additional info
    const userInfoService = new UserInfoService(
        'https://accounts.google.com/userinfo/v2/me'
    );
    
    return userInfoService.getCompleteProfile(idTokenClaims, accessToken);
}

Claims in ID Token vs UserInfo

The same claims can appear in both ID tokens and UserInfo responses. ID token claims are captured at token issuance (snapshot in time). UserInfo returns current data. For frequently changing data like profile pictures, prefer UserInfo. For immutable data like sub, the ID token is sufficient.

OIDC Scopes and Claims

OIDC standardizes scopes and the claims they grant access to. This predictability makes integration consistent across providers. The Scope-to-Claims Mapping:

Standard OIDC Scopes and Their Claims
Scope	Claims Provided	Notes
openid	sub	Required for OIDC; triggers ID token issuance
profile	name, family_name, given_name, middle_name, nickname, preferred_username, picture, website, gender, birthdate, zoneinfo, locale, updated_at	User profile information
email	email, email_verified	Email address and verification status
phone	phone_number, phone_number_verified	Phone number and verification status
address	address (nested object)	Physical mailing address
offline_access	(none - affects token response)	Requests refresh token for offline access

Requesting Specific Claims: Beyond scopes, OIDC allows requesting specific claims via the claims parameter. This is useful when you need only certain claims from a scope, or when you need claims not covered by standard scopes.

claims-request.ts
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
// Requesting specific claims
const claimsParam = {
    id_token: {
        // Required in ID token
        email: { essential: true },
        email_verified: { essential: true },
        // Optional in ID token
        picture: null,
    },
    userinfo: {
        // These claims only needed from UserInfo
        given_name: null,
        family_name: null,
        phone_number: { essential: true },
    },
};
 
// Build authorization URL with claims parameter
const authUrl = new URL('https://accounts.google.com/o/oauth2/v2/auth');
authUrl.searchParams.set('client_id', clientId);
authUrl.searchParams.set('redirect_uri', redirectUri);
authUrl.searchParams.set('response_type', 'code');
authUrl.searchParams.set('scope', 'openid email profile phone');
authUrl.searchParams.set('claims', JSON.stringify(claimsParam));
authUrl.searchParams.set('state', state);
authUrl.searchParams.set('nonce', nonce);
 
// Principle of Least Privilege: Request Only What You Need
const minimalScopes = 'openid email'; // vs 'openid profile email phone address'
 
// Good: Request only necessary claims
function getRequiredScopes(features: string[]): string {
    const scopes = new Set(['openid']); // Always required
    
    if (features.includes('email-notifications')) {
        scopes.add('email');
    }
    
    if (features.includes('personalized-greeting')) {
        scopes.add('profile'); // For name
    }
    
    if (features.includes('sms-verification')) {
        scopes.add('phone');
    }
    
    if (features.includes('offline-sync')) {
        scopes.add('offline_access'); // Refresh tokens
    }
    
    return Array.from(scopes).join(' ');
}

Progressive Consent

Don't request all possible scopes upfront. Request 'openid email' for login, then ask for 'phone' only when the user tries to enable SMS 2FA. This progressive consent improves sign-up conversion—users are more likely to approve minimal permissions initially.

OIDC Implementation Best Practices

Implementing OIDC correctly requires attention to several security and usability considerations. Here are patterns used by experienced engineering teams:

Security Best Practices

•Always validate ID tokens — Verify signature, issuer, audience, expiration, and nonce. Use established libraries.
•Use nonce for replay protection — Generate unique nonce per request, store in session, verify in ID token.
•Combine state and nonce — State prevents CSRF; nonce prevents token replay. Both are needed.
•Verify issuer exactly — Match issuer claim exactly (https://accounts.google.com vs https://accounts.google.com/). Trailing slashes matter!
•Handle multiple audiences — If aud is an array, your client_id must be present. Some providers always return arrays.
•Check azp for multi-audience tokens — If aud contains multiple values, azp should match your client_id.

User Account Linking Strategies

•Primary key: (iss, sub) tuple — A user can have different 'sub' values from different providers. Store provider along with sub.
•Email linking with caution — Two OIDC accounts with same email may be different people if email_verified is false.
•Handle provider changes — User might switch from Google to Microsoft login. Support linking multiple providers to one account.
•Graceful re-authentication — When user returns after long absence, handle potential claim changes (new email, name change).

account-linking.ts
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
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
// Secure Account Linking Implementation
interface OIDCIdentity {
    issuer: string;    // e.g., "https://accounts.google.com"
    subject: string;   // e.g., "110022334455667788"
    email?: string;
    emailVerified?: boolean;
}
 
interface UserAccount {
    id: string;
    primaryEmail: string;
    identities: OIDCIdentity[];
    createdAt: Date;
}
 
class AccountLinkingService {
    constructor(private db: Database) {}
    
    async findOrCreateUser(oidcIdentity: OIDCIdentity): Promise<UserAccount> {
        // Step 1: Look for existing identity link
        let user = await this.findUserByIdentity(
            oidcIdentity.issuer,
            oidcIdentity.subject
        );
        
        if (user) {
            return user;
        }
        
        // Step 2: If email is verified, look for existing account to link
        if (oidcIdentity.email && oidcIdentity.emailVerified) {
            const existingByEmail = await this.findUserByVerifiedEmail(
                oidcIdentity.email
            );
            
            if (existingByEmail) {
                // Link this new identity to existing account
                await this.addIdentityToUser(existingByEmail.id, oidcIdentity);
                return existingByEmail;
            }
        }
        
        // Step 3: Create new account
        return this.createUser(oidcIdentity);
    }
    
    private async findUserByIdentity(
        issuer: string,
        subject: string
    ): Promise<UserAccount | null> {
        return this.db.users.findFirst({
            where: {
                identities: {
                    some: { issuer, subject },
                },
            },
        });
    }
    
    private async findUserByVerifiedEmail(
        email: string
    ): Promise<UserAccount | null> {
        // Only link if an existing identity has this email verified
        return this.db.users.findFirst({
            where: {
                identities: {
                    some: { 
                        email,
                        emailVerified: true,
                    },
                },
            },
        });
    }
    
    private async addIdentityToUser(
        userId: string,
        identity: OIDCIdentity
    ): Promise<void> {
        await this.db.userIdentities.create({
            data: {
                userId,
                issuer: identity.issuer,
                subject: identity.subject,
                email: identity.email,
                emailVerified: identity.emailVerified || false,
            },
        });
    }
    
    private async createUser(identity: OIDCIdentity): Promise<UserAccount> {
        return this.db.users.create({
            data: {
                id: generateUUID(),
                primaryEmail: identity.email || '',
                identities: {
                    create: {
                        issuer: identity.issuer,
                        subject: identity.subject,
                        email: identity.email,
                        emailVerified: identity.emailVerified || false,
                    },
                },
                createdAt: new Date(),
            },
        });
    }
}

The Email Linking Trap

Don't automatically link accounts just because emails match. A malicious IdP could claim any email. Only link when email_verified is true AND you trust the issuer. Even then, consider requiring user confirmation for linking to prevent account takeover scenarios.

System Design (HLD)OAuth2 and OpenID Connect

OAuth2 and OpenID Connect

LevelIntermediate

Duration90 mins

TopicOAuth2 and OpenID Connect

3 / 5

OpenID Connect for Identity

From Authorization to Authentication

OAuth 2.0 solved the delegation problem brilliantly—allowing third-party applications to access resources without sharing passwords. But it left a critical gap: OAuth 2.0 is an authorization framework, not an authentication protocol . It can tell you what someone is allowed to do, but not who that someone actually is. This distinction might seem academic, but it's profound. Applications using OAuth 2.0 alone for login were essentially saying "someone with a valid token wants in"—without standardized verification of who that someone was. Different providers implemented user identity differently, creating fragmentation and security gaps. OpenID Connect (OIDC) emerged as the solution—an identity layer built on top of OAuth 2.0. It adds standardized authentication, user identity claims, and a consistent way to verify "this is who they say they are." Today, OIDC powers login experiences across Google, Microsoft, Apple, Okta, Auth0, and virtually every modern identity provider.

What You Will Learn

By the end of this page, you will understand the critical difference between OAuth 2.0 and OIDC, master ID token structure and claims, implement OIDC authentication flows correctly, and leverage OIDC's standardized endpoints for robust identity verification.

OAuth 2.0 vs OpenID Connect

Understanding the relationship between OAuth 2.0 and OpenID Connect is fundamental. They're not competitors—OIDC is built on OAuth 2.0, extending it with identity capabilities. OAuth 2.0 Alone: Answers: "Is this client authorized to access this resource?" Returns: Access token (authorization credential) Use case: Third-party app accessing user's Google Drive files OpenID Connect (OAuth 2.0 + Identity Layer): Answers: "Who is this user?" + "Is this client authorized?" Returns: ID token (identity credential) + Access token (authorization credential) Use case: "Sign in with Google" to authenticate users

OAuth 2.0 vs OpenID Connect Comparison
Aspect	OAuth 2.0	OpenID Connect
Primary Purpose	Delegated authorization	Authentication + Authorization
Core Question	What can this client access?	Who is this user?
Key Token	Access Token	ID Token + Access Token
User Info	Non-standard, varies by provider	Standardized claims (sub, email, name, etc.)
Discovery	No standard mechanism	/.well-known/openid-configuration
Scopes	Provider-defined	Standard: openid, profile, email, phone, address
Token Format	Often opaque or JWT	ID Token must be JWT
Client Auth	Optional	Often required for confidential clients

The 'Login with OAuth' Anti-Pattern

Using pure OAuth 2.0 for login (without OIDC) is a common mistake. Getting an access token proves the user authorized something, but not who authorized it. An attacker could potentially inject a token obtained elsewhere. OIDC's ID token, with proper validation, provides cryptographic proof of identity. Always use OIDC for authentication, not bare OAuth 2.0.

The Simple Distinction: Think of a hotel key card: OAuth 2.0 is like the key card itself—it grants access to specific rooms (resources) but doesn't identify the holder. OpenID Connect adds a photo ID to verify the person using the key card is who they claim to be. Both are needed for a complete identity and access management solution.

The ID Token: OIDC's Core Innovation

The ID Token is OIDC's key contribution—a JWT that conveys identity claims about the authenticated user. Unlike access tokens (which may be opaque), ID tokens are always JWTs with a standardized structure. ID Token Structure: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6Imtex123"}. eyJpc3MiOiJodHRwczovL2FjY291bnRzLmdvb2dsZS5jb20iLCJzdWIiOiIxMT AwMjIzMzQ0NTU2Njc3ODgiLCJhdWQiOiJteWFwcC5jbGllbnRpZCIsImV4cCI 6MTcwNDEyMzQ1NiwiaWF0IjoxNzA0MTE5ODU2LCJub25jZSI6ImFiY2RlZjE yMzQ1NiIsImVtYWlsIjoidXNlckBleGFtcGxlLmNvbSIsImVtYWlsX3Zlcmlma WVkIjp0cnVlLCJuYW1lIjoiSm9obiBEb2UifQ. [signature] The three parts (header, payload, signature) are base64url-encoded and separated by dots.

Required ID Token Claims
Claim	Name	Description	Example
iss	Issuer	URL of the token issuer (IdP)	https://accounts.google.com
sub	Subject	Unique identifier for the user (stable, opaque)	110022334455667788
aud	Audience	Client ID(s) this token is intended for	myapp.clientid
exp	Expiration Time	Unix timestamp when token expires	1704123456
iat	Issued At	Unix timestamp when token was issued	1704119856

Common Optional Claims
Claim	Scope Required	Description
nonce	openid	Ties token to specific auth request (replay protection)
auth_time	openid	When user last actively authenticated
acr	openid	Authentication Context Class Reference (security level)
email	email	User's email address
email_verified	email	Whether email has been verified (boolean)
name	profile	User's full name
given_name	profile	First/given name
family_name	profile	Last/family name
picture	profile	URL to user's profile picture
phone_number	phone	User's phone number
address	address	User's physical address (JSON object)

id-token-example.ts
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
// Decoded ID Token Payload Example
interface IDTokenPayload {
    // Required claims
    iss: string;       // "https://accounts.google.com"
    sub: string;       // "110022334455667788" - stable user identifier
    aud: string | string[]; // "myapp.clientid" or ["client1", "client2"]
    exp: number;       // 1704123456 - expiration timestamp
    iat: number;       // 1704119856 - issued at timestamp
    
    // Recommended for security
    nonce?: string;    // "abc123" - ties request to response
    auth_time?: number; // 1704119800 - when user actually authenticated
    
    // Standard claims from scopes
    email?: string;         // "user@example.com"
    email_verified?: boolean; // true
    name?: string;          // "John Doe"
    given_name?: string;    // "John"
    family_name?: string;   // "Doe"
    picture?: string;       // "https://example.com/photo.jpg"
    
    // Additional context
    acr?: string;      // "urn:mace:incommon:iap:silver" - auth assurance level
    amr?: string[];    // ["pwd", "mfa"] - auth methods used
    azp?: string;      // Authorized party - client that auth'd
}
 
// Example decoded token
const exampleToken: IDTokenPayload = {
    iss: "https://accounts.google.com",
    sub: "110022334455667788",
    aud: "123456789.apps.googleusercontent.com",
    exp: 1704123456,
    iat: 1704119856,
    nonce: "n-0S6_WzA2Mj",
    email: "user@example.com",
    email_verified: true,
    name: "Jane Smith",
    given_name: "Jane",
    family_name: "Smith",
    picture: "https://lh3.googleusercontent.com/a/photo.jpg",
    auth_time: 1704119800,
    acr: "0", // Basic password authentication
    amr: ["pwd"],
};

Sub Claim is Your Stable Identifier

The 'sub' (subject) claim is the only guaranteed stable identifier. Email addresses can change. Names can change. But 'sub' is immutable for a given user at a given issuer. Always use 'sub' (combined with 'iss') as your primary key for user records—never rely on email as the unique identifier.

OIDC Authentication Flow

OIDC authentication builds on OAuth 2.0 Authorization Code flow with specific additions for identity. The key differences:'openid' scope is required — Signals you want OIDC, not just OAuth ID token returned — In addition to access token nonce parameter — Binds authorization request to token (prevents replay) Standardized endpoints — discovery, userinfo The Flow:

OIDC Authorization Code Flow
Step	Description	OIDC-Specific Elements
Auth Request	Client redirects user to authorization endpoint	scope=openid, nonce parameter
Authentication	User authenticates with IdP (password, MFA, etc.)	IdP handles all auth complexity
Consent	User approves requested scopes	Standard OIDC scopes shown clearly
Auth Response	Redirect back with authorization code	Same as OAuth 2.0
Token Request	Exchange code for tokens	Returns ID token + access token
Token Validation	Verify ID token signature, claims	Comprehensive validation required
UserInfo (optional)	Fetch additional claims via UserInfo endpoint	Access token authenticates request

oidc-flow-implementation.ts
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
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
// Complete OIDC Authentication Flow Implementation
import * as jose from 'jose';
 
interface OIDCConfig {
    clientId: string;
    clientSecret: string;
    redirectUri: string;
    issuer: string;
    scopes: string[];
}
 
interface TokenResponse {
    access_token: string;
    id_token: string;
    token_type: string;
    expires_in: number;
    refresh_token?: string;
    scope: string;
}
 
class OIDCClient {
    private discoveryDoc: any = null;
    private jwks: jose.JWTVerifyGetKey | null = null;
    
    constructor(private config: OIDCConfig) {}
    
    // Step 1: Fetch OIDC discovery document
    async initialize(): Promise<void> {
        const discoveryUrl = `${this.config.issuer}/.well-known/openid-configuration`;
        const response = await fetch(discoveryUrl);
        this.discoveryDoc = await response.json();
        
        // Fetch JWKS for token verification
        this.jwks = jose.createRemoteJWKSet(
            new URL(this.discoveryDoc.jwks_uri)
        );
    }
    
    // Step 2: Generate authorization URL
    generateAuthUrl(state: string, nonce: string): string {
        const url = new URL(this.discoveryDoc.authorization_endpoint);
        url.searchParams.set('client_id', this.config.clientId);
        url.searchParams.set('redirect_uri', this.config.redirectUri);
        url.searchParams.set('response_type', 'code');
        url.searchParams.set('scope', this.config.scopes.join(' '));
        url.searchParams.set('state', state);
        url.searchParams.set('nonce', nonce); // OIDC-specific: replay protection
        
        return url.toString();
    }
    
    // Step 3: Exchange code for tokens
    async exchangeCode(code: string): Promise<TokenResponse> {
        const response = await fetch(this.discoveryDoc.token_endpoint, {
            method: 'POST',
            headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
            body: new URLSearchParams({
                grant_type: 'authorization_code',
                code,
                client_id: this.config.clientId,
                client_secret: this.config.clientSecret,
                redirect_uri: this.config.redirectUri,
            }),
        });
        
        if (!response.ok) {
            throw new Error(`Token request failed: ${response.status}`);
        }
        
        return response.json();
    }
    
    // Step 4: Validate ID token (CRITICAL!)
    async validateIdToken(
        idToken: string,
        expectedNonce: string
    ): Promise<jose.JWTPayload> {
        if (!this.jwks) {
            throw new Error('Client not initialized');
        }
        
        // Verify signature and standard claims
        const { payload, protectedHeader } = await jose.jwtVerify(
            idToken,
            this.jwks,
            {
                issuer: this.config.issuer,
                audience: this.config.clientId,
                maxTokenAge: '10 minutes', // ID tokens should be fresh
            }
        );
        
        // Additional OIDC-specific validations
        
        // 1. Verify nonce matches (prevents replay/injection)
        if (payload.nonce !== expectedNonce) {
            throw new Error('Invalid nonce - possible token injection');
        }
        
        // 2. iat (issued at) should be in the past
        if (payload.iat && payload.iat > Math.floor(Date.now() / 1000)) {
            throw new Error('Token issued in the future');
        }
        
        // 3. If azp (authorized party) present, must match client_id
        if (payload.azp && payload.azp !== this.config.clientId) {
            throw new Error('Token not authorized for this client');
        }
        
        return payload;
    }
    
    // Optional: Fetch additional user info
    async getUserInfo(accessToken: string): Promise<any> {
        const response = await fetch(this.discoveryDoc.userinfo_endpoint, {
            headers: { 'Authorization': `Bearer ${accessToken}` },
        });
        
        return response.json();
    }
    
    // Complete authentication flow
    async handleCallback(
        code: string,
        expectedState: string,
        actualState: string,
        expectedNonce: string
    ): Promise<{ user: any; tokens: TokenResponse }> {
        // Verify state
        if (actualState !== expectedState) {
            throw new Error('Invalid state - CSRF detected');
        }
        
        // Exchange code for tokens
        const tokens = await this.exchangeCode(code);
        
        // Validate ID token
        const idTokenClaims = await this.validateIdToken(
            tokens.id_token,
            expectedNonce
        );
        
        // Optionally fetch more user info
        const userInfo = await this.getUserInfo(tokens.access_token);
        
        return {
            user: { ...idTokenClaims, ...userInfo },
            tokens,
        };
    }
}
 
// Usage
const oidcClient = new OIDCClient({
    clientId: 'your-client-id',
    clientSecret: 'your-client-secret',
    redirectUri: 'https://yourapp.com/callback',
    issuer: 'https://accounts.google.com',
    scopes: ['openid', 'email', 'profile'],
});
 
await oidcClient.initialize();

Never Skip ID Token Validation

ID token validation is not optional—it's the core security guarantee of OIDC. Verify the signature using the IdP's public keys. Verify issuer, audience, expiration, and nonce. Skipping these checks means you're trusting whoever can construct a JWT, not who the IdP authenticated.

OIDC Discovery and JWKS

OIDC standardizes how clients discover provider capabilities and public keys—no more hardcoding endpoints or manually managing certificates. Discovery Document: Every OIDC provider publishes a JSON document at /.well-known/openid-configuration containing all endpoints and capabilities. This enables dynamic configuration and automatic handling of endpoint changes.

discovery-document.json
JSON
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
{
  "issuer": "https://accounts.google.com",
  "authorization_endpoint": "https://accounts.google.com/o/oauth2/v2/auth",
  "token_endpoint": "https://oauth2.googleapis.com/token",
  "userinfo_endpoint": "https://openidconnect.googleapis.com/v1/userinfo",
  "revocation_endpoint": "https://oauth2.googleapis.com/revoke",
  "jwks_uri": "https://www.googleapis.com/oauth2/v3/certs",
  "scopes_supported": ["openid", "email", "profile", "phone", "address"],
  "response_types_supported": ["code", "id_token", "code id_token"],
  "grant_types_supported": ["authorization_code", "refresh_token"],
  "subject_types_supported": ["public"],
  "id_token_signing_alg_values_supported": ["RS256"],
  "claims_supported": [
    "sub", "iss", "aud", "exp", "iat", "nonce",
    "email", "email_verified", "name", "given_name",
    "family_name", "picture", "locale"
  ],
  "code_challenge_methods_supported": ["S256", "plain"],
  "token_endpoint_auth_methods_supported": [
    "client_secret_basic", "client_secret_post"
  ]
}

JSON Web Key Set (JWKS): The jwks_uri points to the provider's public keys used to sign ID tokens. Clients fetch these keys to verify token signatures without sharing private keys.

jwks-example.json
JSON
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
  "keys": [
    {
      "kty": "RSA",
      "use": "sig",
      "alg": "RS256",
      "kid": "abc123def456",
      "n": "0vx7agoebGcQ...(modulus in base64url)...",
      "e": "AQAB"
    },
    {
      "kty": "RSA",
      "use": "sig", 
      "alg": "RS256",
      "kid": "xyz789ghi012",
      "n": "1hqLlFJx9vZb...(modulus in base64url)...",
      "e": "AQAB"
    }
  ]
}

JWKS Best Practices

•Cache JWKS but respect expiry — Don't fetch on every request, but refresh periodically (typically 1-24 hours).
•Match 'kid' header to key — ID token header specifies which key ('kid') signed it. Find matching key in JWKS.
•Handle key rotation gracefully — Providers rotate keys. If 'kid' not found, refresh JWKS and retry once.
•Use established libraries — Don't implement JWT verification yourself. Use jose, jsonwebtoken, or equivalent.
•Validate algorithm — Only accept expected algorithms (RS256). Reject None or symmetric algorithms to prevent attacks.

jwks-handling.ts
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
// Production-Ready JWKS Handling with Caching
import * as jose from 'jose';
 
class JWKSManager {
    private jwksCache: Map<string, {
        keys: jose.JWTVerifyGetKey;
        fetchedAt: Date;
    }> = new Map();
    
    private readonly cacheTTL = 60 * 60 * 1000; // 1 hour
    
    async getVerificationKey(issuer: string): Promise<jose.JWTVerifyGetKey> {
        const cached = this.jwksCache.get(issuer);
        
        if (cached && Date.now() - cached.fetchedAt.getTime() < this.cacheTTL) {
            return cached.keys;
        }
        
        // Fetch discovery document
        const discoveryUrl = `${issuer}/.well-known/openid-configuration`;
        const discovery = await fetch(discoveryUrl).then(r => r.json());
        
        // Create JWKS client
        const keys = jose.createRemoteJWKSet(new URL(discovery.jwks_uri));
        
        this.jwksCache.set(issuer, { keys, fetchedAt: new Date() });
        return keys;
    }
    
    async verifyToken(
        token: string,
        expectedIssuer: string,
        expectedAudience: string
    ): Promise<jose.JWTPayload> {
        const keys = await this.getVerificationKey(expectedIssuer);
        
        try {
            const { payload } = await jose.jwtVerify(token, keys, {
                issuer: expectedIssuer,
                audience: expectedAudience,
                algorithms: ['RS256', 'ES256'], // Only allow expected algorithms
            });
            return payload;
        } catch (error) {
            // If key not found, might be rotation - refresh and retry once
            if (error instanceof jose.errors.JWKSNoMatchingKey) {
                this.jwksCache.delete(expectedIssuer);
                const freshKeys = await this.getVerificationKey(expectedIssuer);
                const { payload } = await jose.jwtVerify(token, freshKeys, {
                    issuer: expectedIssuer,
                    audience: expectedAudience,
                    algorithms: ['RS256', 'ES256'],
                });
                return payload;
            }
            throw error;
        }
    }
}

Algorithm Confusion Attacks

Always explicitly specify allowed algorithms. The infamous 'alg: none' attack exploits libraries that blindly trust the token's algorithm claim. By whitelisting only RS256/ES256 (asymmetric), you prevent attackers from switching to symmetric algorithms or disabled signing.

The UserInfo Endpoint

While ID tokens contain identity claims, they're intentionally compact. The UserInfo endpoint provides a way to fetch additional claims about the authenticated user using the access token. When to Use UserInfo: When you need claims beyond what's in the ID token When you need fresh/current data (ID tokens are snapshots) When the ID token would be too large with all needed claims When ID Token is Sufficient: Basic authentication with email/name When you only need stable identifiers (sub) When ID token already includes required claims

userinfo-usage.ts
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
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
// UserInfo Endpoint Usage
interface UserInfoResponse {
    sub: string;              // Always present - matches ID token sub
    name?: string;
    given_name?: string;
    family_name?: string;
    picture?: string;
    email?: string;
    email_verified?: boolean;
    phone_number?: string;
    phone_number_verified?: boolean;
    address?: {
        formatted?: string;
        street_address?: string;
        locality?: string;
        region?: string;
        postal_code?: string;
        country?: string;
    };
    updated_at?: number;
    // Provider-specific claims may be included
    [key: string]: any;
}
 
class UserInfoService {
    constructor(private userInfoEndpoint: string) {}
    
    async getUserInfo(accessToken: string): Promise<UserInfoResponse> {
        const response = await fetch(this.userInfoEndpoint, {
            headers: {
                'Authorization': `Bearer ${accessToken}`,
            },
        });
        
        if (response.status === 401) {
            throw new Error('Access token invalid or expired');
        }
        
        if (!response.ok) {
            throw new Error(`UserInfo request failed: ${response.status}`);
        }
        
        const userInfo = await response.json();
        
        // Validate sub claim matches ID token if available
        return userInfo;
    }
    
    // Fetch and merge with ID token claims
    async getCompleteProfile(
        idTokenClaims: any,
        accessToken: string
    ): Promise<UserInfoResponse> {
        const userInfo = await this.getUserInfo(accessToken);
        
        // Validate consistency
        if (userInfo.sub !== idTokenClaims.sub) {
            throw new Error('UserInfo sub does not match ID token');
        }
        
        // Merge claims (userInfo takes precedence for freshness)
        return {
            ...idTokenClaims,
            ...userInfo,
        };
    }
}
 
// Efficient pattern: Only fetch if needed
async function getUserDetails(
    idTokenClaims: any,
    accessToken: string,
    requiredFields: string[]
): Promise<any> {
    const missingFields = requiredFields.filter(
        field => !(field in idTokenClaims) || idTokenClaims[field] == null
    );
    
    if (missingFields.length === 0) {
        // ID token has everything we need
        return idTokenClaims;
    }
    
    // Need to fetch additional info
    const userInfoService = new UserInfoService(
        'https://accounts.google.com/userinfo/v2/me'
    );
    
    return userInfoService.getCompleteProfile(idTokenClaims, accessToken);
}

Claims in ID Token vs UserInfo

The same claims can appear in both ID tokens and UserInfo responses. ID token claims are captured at token issuance (snapshot in time). UserInfo returns current data. For frequently changing data like profile pictures, prefer UserInfo. For immutable data like sub, the ID token is sufficient.

OIDC Scopes and Claims

OIDC standardizes scopes and the claims they grant access to. This predictability makes integration consistent across providers. The Scope-to-Claims Mapping:

Standard OIDC Scopes and Their Claims
Scope	Claims Provided	Notes
openid	sub	Required for OIDC; triggers ID token issuance
profile	name, family_name, given_name, middle_name, nickname, preferred_username, picture, website, gender, birthdate, zoneinfo, locale, updated_at	User profile information
email	email, email_verified	Email address and verification status
phone	phone_number, phone_number_verified	Phone number and verification status
address	address (nested object)	Physical mailing address
offline_access	(none - affects token response)	Requests refresh token for offline access

Requesting Specific Claims: Beyond scopes, OIDC allows requesting specific claims via the claims parameter. This is useful when you need only certain claims from a scope, or when you need claims not covered by standard scopes.

claims-request.ts
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
// Requesting specific claims
const claimsParam = {
    id_token: {
        // Required in ID token
        email: { essential: true },
        email_verified: { essential: true },
        // Optional in ID token
        picture: null,
    },
    userinfo: {
        // These claims only needed from UserInfo
        given_name: null,
        family_name: null,
        phone_number: { essential: true },
    },
};
 
// Build authorization URL with claims parameter
const authUrl = new URL('https://accounts.google.com/o/oauth2/v2/auth');
authUrl.searchParams.set('client_id', clientId);
authUrl.searchParams.set('redirect_uri', redirectUri);
authUrl.searchParams.set('response_type', 'code');
authUrl.searchParams.set('scope', 'openid email profile phone');
authUrl.searchParams.set('claims', JSON.stringify(claimsParam));
authUrl.searchParams.set('state', state);
authUrl.searchParams.set('nonce', nonce);
 
// Principle of Least Privilege: Request Only What You Need
const minimalScopes = 'openid email'; // vs 'openid profile email phone address'
 
// Good: Request only necessary claims
function getRequiredScopes(features: string[]): string {
    const scopes = new Set(['openid']); // Always required
    
    if (features.includes('email-notifications')) {
        scopes.add('email');
    }
    
    if (features.includes('personalized-greeting')) {
        scopes.add('profile'); // For name
    }
    
    if (features.includes('sms-verification')) {
        scopes.add('phone');
    }
    
    if (features.includes('offline-sync')) {
        scopes.add('offline_access'); // Refresh tokens
    }
    
    return Array.from(scopes).join(' ');
}

Progressive Consent

Don't request all possible scopes upfront. Request 'openid email' for login, then ask for 'phone' only when the user tries to enable SMS 2FA. This progressive consent improves sign-up conversion—users are more likely to approve minimal permissions initially.

OIDC Implementation Best Practices

Implementing OIDC correctly requires attention to several security and usability considerations. Here are patterns used by experienced engineering teams:

Security Best Practices

•Always validate ID tokens — Verify signature, issuer, audience, expiration, and nonce. Use established libraries.
•Use nonce for replay protection — Generate unique nonce per request, store in session, verify in ID token.
•Combine state and nonce — State prevents CSRF; nonce prevents token replay. Both are needed.
•Verify issuer exactly — Match issuer claim exactly (https://accounts.google.com vs https://accounts.google.com/). Trailing slashes matter!
•Handle multiple audiences — If aud is an array, your client_id must be present. Some providers always return arrays.
•Check azp for multi-audience tokens — If aud contains multiple values, azp should match your client_id.

User Account Linking Strategies

•Primary key: (iss, sub) tuple — A user can have different 'sub' values from different providers. Store provider along with sub.
•Email linking with caution — Two OIDC accounts with same email may be different people if email_verified is false.
•Handle provider changes — User might switch from Google to Microsoft login. Support linking multiple providers to one account.
•Graceful re-authentication — When user returns after long absence, handle potential claim changes (new email, name change).

account-linking.ts
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
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
// Secure Account Linking Implementation
interface OIDCIdentity {
    issuer: string;    // e.g., "https://accounts.google.com"
    subject: string;   // e.g., "110022334455667788"
    email?: string;
    emailVerified?: boolean;
}
 
interface UserAccount {
    id: string;
    primaryEmail: string;
    identities: OIDCIdentity[];
    createdAt: Date;
}
 
class AccountLinkingService {
    constructor(private db: Database) {}
    
    async findOrCreateUser(oidcIdentity: OIDCIdentity): Promise<UserAccount> {
        // Step 1: Look for existing identity link
        let user = await this.findUserByIdentity(
            oidcIdentity.issuer,
            oidcIdentity.subject
        );
        
        if (user) {
            return user;
        }
        
        // Step 2: If email is verified, look for existing account to link
        if (oidcIdentity.email && oidcIdentity.emailVerified) {
            const existingByEmail = await this.findUserByVerifiedEmail(
                oidcIdentity.email
            );
            
            if (existingByEmail) {
                // Link this new identity to existing account
                await this.addIdentityToUser(existingByEmail.id, oidcIdentity);
                return existingByEmail;
            }
        }
        
        // Step 3: Create new account
        return this.createUser(oidcIdentity);
    }
    
    private async findUserByIdentity(
        issuer: string,
        subject: string
    ): Promise<UserAccount | null> {
        return this.db.users.findFirst({
            where: {
                identities: {
                    some: { issuer, subject },
                },
            },
        });
    }
    
    private async findUserByVerifiedEmail(
        email: string
    ): Promise<UserAccount | null> {
        // Only link if an existing identity has this email verified
        return this.db.users.findFirst({
            where: {
                identities: {
                    some: { 
                        email,
                        emailVerified: true,
                    },
                },
            },
        });
    }
    
    private async addIdentityToUser(
        userId: string,
        identity: OIDCIdentity
    ): Promise<void> {
        await this.db.userIdentities.create({
            data: {
                userId,
                issuer: identity.issuer,
                subject: identity.subject,
                email: identity.email,
                emailVerified: identity.emailVerified || false,
            },
        });
    }
    
    private async createUser(identity: OIDCIdentity): Promise<UserAccount> {
        return this.db.users.create({
            data: {
                id: generateUUID(),
                primaryEmail: identity.email || '',
                identities: {
                    create: {
                        issuer: identity.issuer,
                        subject: identity.subject,
                        email: identity.email,
                        emailVerified: identity.emailVerified || false,
                    },
                },
                createdAt: new Date(),
            },
        });
    }
}

The Email Linking Trap

Don't automatically link accounts just because emails match. A malicious IdP could claim any email. Only link when email_verified is true AND you trust the issuer. Even then, consider requiring user confirmation for linking to prevent account takeover scenarios.

OpenID Connect for Identity

From Authorization to Authentication

OAuth 2.0 vs OpenID Connect

The ID Token: OIDC's Core Innovation

OIDC Authentication Flow

OIDC Discovery and JWKS

The UserInfo Endpoint

OIDC Scopes and Claims

OIDC Implementation Best Practices

There’s more to understand.

OpenID Connect for Identity

From Authorization to Authentication

OAuth 2.0 vs OpenID Connect

The ID Token: OIDC's Core Innovation

OIDC Authentication Flow

OIDC Discovery and JWKS

The UserInfo Endpoint

OIDC Scopes and Claims

OIDC Implementation Best Practices

There’s more to understand.