OAuth2 Flows

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

// Step 1: Construct authorization URL
const authorizationUrl = new URL('https://accounts.google.com/o/oauth2/v2/auth');
authorizationUrl.searchParams.set('client_id', process.env.GOOGLE_CLIENT_ID);
authorizationUrl.searchParams.set('redirect_uri', 'https://myapp.com/callback');
authorizationUrl.searchParams.set('response_type', 'code');
authorizationUrl.searchParams.set('scope', 'openid email profile');
authorizationUrl.searchParams.set('state', generateCryptoRandomState()); // CSRF protection
authorizationUrl.searchParams.set('access_type', 'offline'); // Request refresh token
 
// Redirect user to authorization URL
res.redirect(authorizationUrl.toString());
 
// Step 2: Handle callback - exchange code for tokens
app.get('/callback', async (req, res) => {
    const { code, state } = req.query;
    
    // Verify state matches what we stored (CSRF protection)
    if (state !== req.session.oauthState) {
        return res.status(403).send('Invalid state parameter');
    }
    
    // Exchange authorization code for tokens (server-to-server)
    const tokenResponse = await fetch('https://oauth2.googleapis.com/token', {
        method: 'POST',
        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
        body: new URLSearchParams({
            code: code as string,
            client_id: process.env.GOOGLE_CLIENT_ID,
            client_secret: process.env.GOOGLE_CLIENT_SECRET, // Server-side only!
            redirect_uri: 'https://myapp.com/callback',
            grant_type: 'authorization_code',
        }),
    });
    
    const tokens = await tokenResponse.json();
    // tokens = { access_token, refresh_token, expires_in, token_type, id_token }
    
    // Store tokens securely - never expose to client
    await storeTokensSecurely(req.session.userId, tokens);
    
    res.redirect('/dashboard');
});

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

// PKCE Implementation for SPAs/Mobile Apps
import * as crypto from 'crypto';
 
// Generate cryptographically random code verifier (43-128 characters)
function generateCodeVerifier(): string {
    const buffer = crypto.randomBytes(32);
    return base64URLEncode(buffer);
}
 
// Generate code challenge from verifier using SHA-256
async function generateCodeChallenge(verifier: string): Promise<string> {
    const encoder = new TextEncoder();
    const data = encoder.encode(verifier);
    const digest = await crypto.subtle.digest('SHA-256', data);
    return base64URLEncode(new Uint8Array(digest));
}
 
// Base64 URL encoding (no padding, URL-safe characters)
function base64URLEncode(buffer: Uint8Array): string {
    return btoa(String.fromCharCode(...buffer))
        .replace(/\+/g, '-')
        .replace(/\//g, '_')
        .replace(/=/g, '');
}
 
// Step 1: Initiate PKCE flow
async function initiateOAuth() {
    const codeVerifier = generateCodeVerifier();
    const codeChallenge = await generateCodeChallenge(codeVerifier);
    
    // Store verifier securely (will need it later)
    sessionStorage.setItem('pkce_code_verifier', codeVerifier);
    
    const authUrl = new URL('https://auth.example.com/authorize');
    authUrl.searchParams.set('client_id', 'spa-client-id');
    authUrl.searchParams.set('redirect_uri', 'https://spa.example.com/callback');
    authUrl.searchParams.set('response_type', 'code');
    authUrl.searchParams.set('scope', 'openid profile email');
    authUrl.searchParams.set('state', generateSecureState());
    authUrl.searchParams.set('code_challenge', codeChallenge);
    authUrl.searchParams.set('code_challenge_method', 'S256'); // SHA-256
    
    window.location.href = authUrl.toString();
}
 
// Step 2: Exchange code with verifier (no client_secret needed!)
async function handleCallback(code: string) {
    const codeVerifier = sessionStorage.getItem('pkce_code_verifier');
    sessionStorage.removeItem('pkce_code_verifier');
    
    const response = await fetch('https://auth.example.com/token', {
        method: 'POST',
        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
        body: new URLSearchParams({
            grant_type: 'authorization_code',
            client_id: 'spa-client-id',
            code: code,
            redirect_uri: 'https://spa.example.com/callback',
            code_verifier: codeVerifier!, // Proves we initiated the flow
        }),
    });
    
    return response.json();
}

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

// Client Credentials Flow - Machine-to-Machine
interface TokenResponse {
    access_token: string;
    token_type: string;
    expires_in: number;
    scope?: string;
}
 
class ServiceClient {
    private accessToken: string | null = null;
    private tokenExpiry: Date | null = null;
    
    constructor(
        private clientId: string,
        private clientSecret: string,
        private tokenEndpoint: string,
        private scope: string,
    ) {}
    
    // Obtain access token using client credentials
    async getAccessToken(): Promise<string> {
        // Return cached token if still valid
        if (this.accessToken && this.tokenExpiry && new Date() < this.tokenExpiry) {
            return this.accessToken;
        }
        
        // Request new token
        const response = await fetch(this.tokenEndpoint, {
            method: 'POST',
            headers: {
                'Content-Type': 'application/x-www-form-urlencoded',
                // Many servers support HTTP Basic Auth for client credentials
                'Authorization': `Basic ${Buffer.from(
                    `${this.clientId}:${this.clientSecret}`
                ).toString('base64')}`,
            },
            body: new URLSearchParams({
                grant_type: 'client_credentials',
                scope: this.scope,
            }),
        });
        
        if (!response.ok) {
            throw new Error(`Token request failed: ${response.status}`);
        }
        
        const data: TokenResponse = await response.json();
        
        // Cache token with buffer time (refresh 60s before expiry)
        this.accessToken = data.access_token;
        this.tokenExpiry = new Date(Date.now() + (data.expires_in - 60) * 1000);
        
        return this.accessToken;
    }
    
    // Make authenticated API call
    async callApi(endpoint: string, options: RequestInit = {}): Promise<Response> {
        const token = await this.getAccessToken();
        
        return fetch(endpoint, {
            ...options,
            headers: {
                ...options.headers,
                'Authorization': `Bearer ${token}`,
            },
        });
    }
}
 
// Usage
const paymentService = new ServiceClient(
    process.env.PAYMENT_SERVICE_CLIENT_ID!,
    process.env.PAYMENT_SERVICE_CLIENT_SECRET!,
    'https://auth.internal.example.com/oauth/token',
    'payment:read payment:write',
);
 
// Calls are automatically authenticated
const transactions = await paymentService.callApi(
    'https://payment.internal.example.com/api/transactions'
);

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

// ROPC Flow - ONLY for legacy migration scenarios
// ⚠️ NOT RECOMMENDED for new implementations
 
async function legacyPasswordLogin(username: string, password: string) {
    // WARNING: User credentials are directly handled by the client
    // This creates security and trust concerns
    
    const response = await fetch('https://auth.example.com/oauth/token', {
        method: 'POST',
        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
        body: new URLSearchParams({
            grant_type: 'password',
            username: username,
            password: password,
            client_id: 'legacy-app-client-id',
            client_secret: 'legacy-app-client-secret', // If confidential client
            scope: 'openid profile email',
        }),
    });
    
    if (!response.ok) {
        const error = await response.json();
        throw new Error(`Authentication failed: ${error.error_description}`);
    }
    
    return response.json(); // { access_token, refresh_token, expires_in, ... }
}
 
// Migration example: Wrapping legacy login with OAuth
class MigrationAuthService {
    // Phase 1: Use ROPC during migration
    async legacyLogin(username: string, password: string) {
        return legacyPasswordLogin(username, password);
    }
    
    // Phase 2: Offer modern OAuth flow as alternative
    async modernLogin() {
        // Redirect to Authorization Code + PKCE flow
        window.location.href = buildPKCEAuthUrl();
    }
    
    // Phase 3: Deprecate legacy, use modern flow only
    async login() {
        return this.modernLogin();
    }
}

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

// Device Authorization Flow Implementation
interface DeviceCodeResponse {
    device_code: string;
    user_code: string;
    verification_uri: string;
    verification_uri_complete?: string; // URI with code pre-filled
    expires_in: number;
    interval: number; // Polling interval in seconds
}
 
class DeviceAuth {
    constructor(
        private clientId: string,
        private authServer: string,
        private scope: string,
    ) {}
    
    // Step 1: Request device and user codes
    async initiateDeviceAuthorization(): Promise<DeviceCodeResponse> {
        const response = await fetch(`${this.authServer}/device/code`, {
            method: 'POST',
            headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
            body: new URLSearchParams({
                client_id: this.clientId,
                scope: this.scope,
            }),
        });
        
        return response.json();
    }
    
    // Step 2: Display to user
    displayUserInstructions(deviceCode: DeviceCodeResponse): void {
        console.log('
' + '='.repeat(60));
        console.log('To sign in, visit: ' + deviceCode.verification_uri);
        console.log('And enter code:    ' + deviceCode.user_code);
        console.log('='.repeat(60) + '
');
        
        // If QR code support exists, display it
        if (deviceCode.verification_uri_complete) {
            generateQRCode(deviceCode.verification_uri_complete);
        }
    }
    
    // Step 3: Poll for authorization
    async pollForToken(deviceCode: string, interval: number, timeout: number) {
        const startTime = Date.now();
        
        while (Date.now() - startTime < timeout * 1000) {
            await sleep(interval * 1000);
            
            const response = await fetch(`${this.authServer}/token`, {
                method: 'POST',
                headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
                body: new URLSearchParams({
                    grant_type: 'urn:ietf:params:oauth:grant-type:device_code',
                    device_code: deviceCode,
                    client_id: this.clientId,
                }),
            });
            
            const data = await response.json();
            
            if (data.access_token) {
                return data; // Authorization successful!
            }
            
            // Handle pending states
            switch (data.error) {
                case 'authorization_pending':
                    // User hasn't authorized yet, keep polling
                    continue;
                case 'slow_down':
                    // Server says slow down, increase interval
                    interval += 5;
                    continue;
                case 'access_denied':
                    throw new Error('User denied authorization');
                case 'expired_token':
                    throw new Error('Device code expired, restart flow');
                default:
                    throw new Error(`Unknown error: ${data.error}`);
            }
        }
        
        throw new Error('Authorization timeout');
    }
    
    // Full flow
    async authorize() {
        const deviceCode = await this.initiateDeviceAuthorization();
        this.displayUserInstructions(deviceCode);
        
        return this.pollForToken(
            deviceCode.device_code,
            deviceCode.interval,
            deviceCode.expires_in,
        );
    }
}
 
// CLI Usage
const auth = new DeviceAuth(
    'cli-tool-client-id',
    'https://auth.example.com/oauth',
    'openid profile email offline_access',
);
 
const tokens = await auth.authorize();
console.log('Successfully authenticated!');