Common Implementations

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

// Provider-Specific Configuration Examples
interface ProviderConfig {
    name: string;
    discoveryUrl: string;
    scopes: string[];
    additionalParams?: Record<string, string>;
}
 
const providers: Record<string, ProviderConfig> = {
    google: {
        name: 'Google',
        discoveryUrl: 'https://accounts.google.com/.well-known/openid-configuration',
        scopes: ['openid', 'email', 'profile'],
        additionalParams: {
            access_type: 'offline', // Required for refresh tokens
            prompt: 'consent',      // Force consent to get refresh token
        },
    },
    
    microsoft: {
        name: 'Microsoft',
        // Use 'common' for multi-tenant, or specific tenant ID
        discoveryUrl: 'https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration',
        scopes: [
            'openid',
            'email', 
            'profile',
            'offline_access', // Microsoft requires this for refresh tokens
        ],
        additionalParams: {
            response_mode: 'query', // Or 'fragment' or 'form_post'
        },
    },
    
    apple: {
        name: 'Apple',
        discoveryUrl: 'https://appleid.apple.com/.well-known/openid-configuration',
        scopes: ['openid', 'email', 'name'],
        additionalParams: {
            response_mode: 'form_post', // Apple requires form_post
        },
    },
    
    github: {
        name: 'GitHub',
        // GitHub doesn't have OIDC discovery - manual configuration
        discoveryUrl: '', // Not available
        scopes: ['read:user', 'user:email'], // GitHub-specific scopes
        additionalParams: {},
    },
    
    auth0: {
        name: 'Auth0',
        // Replace 'your-tenant' with actual tenant
        discoveryUrl: 'https://your-tenant.auth0.com/.well-known/openid-configuration',
        scopes: ['openid', 'email', 'profile', 'offline_access'],
        additionalParams: {
            audience: 'https://your-api.example.com', // For API access
        },
    },
};
 
// GitHub OAuth (manual, not OIDC)
class GitHubOAuth {
    private readonly authUrl = 'https://github.com/login/oauth/authorize';
    private readonly tokenUrl = 'https://github.com/login/oauth/access_token';
    private readonly userUrl = 'https://api.github.com/user';
    
    constructor(
        private clientId: string,
        private clientSecret: string,
        private redirectUri: string,
    ) {}
    
    getAuthorizationUrl(state: string): string {
        const url = new URL(this.authUrl);
        url.searchParams.set('client_id', this.clientId);
        url.searchParams.set('redirect_uri', this.redirectUri);
        url.searchParams.set('scope', 'read:user user:email');
        url.searchParams.set('state', state);
        return url.toString();
    }
    
    async exchangeCode(code: string): Promise<{ access_token: string }> {
        const response = await fetch(this.tokenUrl, {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json',
                'Accept': 'application/json',
            },
            body: JSON.stringify({
                client_id: this.clientId,
                client_secret: this.clientSecret,
                code: code,
                redirect_uri: this.redirectUri,
            }),
        });
        
        return response.json();
    }
    
    async getUser(accessToken: string): Promise<any> {
        const response = await fetch(this.userUrl, {
            headers: { 'Authorization': `Bearer ${accessToken}` },
        });
        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
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
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181

// Multi-Tenant Enterprise SSO Implementation
interface TenantConfig {
    tenantId: string;
    name: string;
    domain: string; // e.g., 'acme.com'
    ssoEnabled: boolean;
    oidcConfig?: {
        issuer: string;
        clientId: string;
        clientSecret: string;
    };
}
 
class EnterpriseSSOManager {
    constructor(
        private tenantStore: TenantStore,
        private defaultLoginUrl: string,
    ) {}
    
    // Determine auth method based on email domain
    async getAuthMethodForEmail(email: string): Promise<{
        method: 'sso' | 'password';
        config?: TenantConfig;
    }> {
        const domain = email.split('@')[1];
        const tenant = await this.tenantStore.findByDomain(domain);
        
        if (tenant?.ssoEnabled && tenant.oidcConfig) {
            return { method: 'sso', config: tenant };
        }
        
        return { method: 'password' };
    }
    
    // Build SSO login URL for tenant
    buildSSOUrl(tenant: TenantConfig, state: string, nonce: string): string {
        if (!tenant.oidcConfig) {
            throw new Error('Tenant does not have SSO configured');
        }
        
        const { issuer, clientId } = tenant.oidcConfig;
        
        // Fetch discovery document (in practice, cache this)
        const discoveryUrl = `${issuer}/.well-known/openid-configuration`;
        
        // Build auth URL - this would be async in practice
        const authUrl = new URL(`${issuer}/authorize`);
        authUrl.searchParams.set('client_id', clientId);
        authUrl.searchParams.set('redirect_uri', `${this.defaultLoginUrl}/sso/callback`);
        authUrl.searchParams.set('response_type', 'code');
        authUrl.searchParams.set('scope', 'openid email profile');
        authUrl.searchParams.set('state', state);
        authUrl.searchParams.set('nonce', nonce);
        
        return authUrl.toString();
    }
    
    // Validate SSO callback for specific tenant
    async validateSSOCallback(
        tenantId: string,
        code: string,
        state: string,
        expectedState: string,
        expectedNonce: string
    ): Promise<{ userId: string; email: string; claims: any }> {
        if (state !== expectedState) {
            throw new Error('State mismatch - CSRF detected');
        }
        
        const tenant = await this.tenantStore.findById(tenantId);
        if (!tenant?.oidcConfig) {
            throw new Error('Invalid tenant');
        }
        
        // Exchange code for tokens
        const tokens = await this.exchangeCode(tenant, code);
        
        // Validate ID token
        const claims = await this.validateIdToken(
            tenant,
            tokens.id_token,
            expectedNonce
        );
        
        return {
            userId: claims.sub,
            email: claims.email,
            claims,
        };
    }
    
    private async exchangeCode(tenant: TenantConfig, code: string) {
        const { issuer, clientId, clientSecret } = tenant.oidcConfig!;
        
        const response = await fetch(`${issuer}/oauth/token`, {
            method: 'POST',
            headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
            body: new URLSearchParams({
                grant_type: 'authorization_code',
                code,
                client_id: clientId,
                client_secret: clientSecret,
                redirect_uri: `${this.defaultLoginUrl}/sso/callback`,
            }),
        });
        
        return response.json();
    }
    
    private async validateIdToken(
        tenant: TenantConfig,
        idToken: string,
        expectedNonce: string
    ): Promise<any> {
        // In practice, use jose library with proper JWKS validation
        // This is simplified for illustration
        const { issuer, clientId } = tenant.oidcConfig!;
        
        // Proper validation would:
        // 1. Fetch JWKS from issuer
        // 2. Verify signature
        // 3. Validate iss, aud, exp, nonce
        
        return { sub: 'user-id', email: 'user@example.com' }; // Placeholder
    }
}
 
// SCIM Provisioning Integration
interface SCIMUser {
    id: string;
    userName: string;
    emails: Array<{ value: string; primary: boolean }>;
    active: boolean;
    name?: { givenName?: string; familyName?: string };
    groups?: Array<{ value: string; display: string }>;
}
 
class SCIMProvisioning {
    // Handle user creation from IdP
    async createUser(scimUser: SCIMUser, tenantId: string): Promise<void> {
        const primaryEmail = scimUser.emails.find(e => e.primary)?.value;
        
        await this.userStore.create({
            externalId: scimUser.id,
            email: primaryEmail,
            firstName: scimUser.name?.givenName,
            lastName: scimUser.name?.familyName,
            tenantId,
            active: scimUser.active,
            syncedAt: new Date(),
        });
    }
    
    // Handle user updates from IdP
    async updateUser(scimUser: SCIMUser, tenantId: string): Promise<void> {
        const user = await this.userStore.findByExternalId(scimUser.id, tenantId);
        
        if (user) {
            await this.userStore.update(user.id, {
                active: scimUser.active,
                syncedAt: new Date(),
            });
        }
    }
    
    // Handle user deprovisioning
    async deleteUser(externalId: string, tenantId: string): Promise<void> {
        const user = await this.userStore.findByExternalId(externalId, tenantId);
        
        if (user) {
            // Soft delete or deactivate
            await this.userStore.update(user.id, {
                active: false,
                deactivatedAt: new Date(),
            });
            
            // Revoke all sessions and tokens
            await this.sessionStore.revokeAllForUser(user.id);
        }
    }
}

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

// Keycloak Integration Example (Self-Hosted)
import Keycloak from 'keycloak-connect';
import session from 'express-session';
 
// Keycloak configuration
const keycloakConfig = {
    realm: 'my-realm',
    'auth-server-url': 'https://keycloak.example.com/',
    'ssl-required': 'all',
    resource: 'my-app', // Client ID
    'public-client': false,
    'confidential-port': 0,
    credentials: {
        secret: process.env.KEYCLOAK_CLIENT_SECRET,
    },
};
 
// Initialize Keycloak
const memoryStore = new session.MemoryStore();
const keycloak = new Keycloak({ store: memoryStore }, keycloakConfig);
 
// Session configuration
app.use(session({
    secret: process.env.SESSION_SECRET,
    resave: false,
    saveUninitialized: true,
    store: memoryStore,
}));
 
// Initialize Keycloak middleware
app.use(keycloak.middleware());
 
// Protected route
app.get('/api/protected',
    keycloak.protect(), // Requires authentication
    (req, res) => {
        const user = (req as any).kauth.grant.access_token.content;
        res.json({ 
            message: 'Protected data',
            user: user.preferred_username,
        });
    }
);
 
// Role-based protection
app.get('/api/admin',
    keycloak.protect('realm:admin'), // Requires 'admin' role
    (req, res) => {
        res.json({ message: 'Admin only data' });
    }
);
 
// Scope-based protection
app.get('/api/reports',
    keycloak.protect('reports:read'), // Requires specific scope
    (req, res) => {
        res.json({ message: 'Reports data' });
    }
);

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
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180

// Complete BFF Implementation for SPA Security
import express from 'express';
import session from 'express-session';
import RedisStore from 'connect-redis';
import { createClient } from 'redis';
import * as jose from 'jose';
 
const app = express();
const redis = createClient({ url: process.env.REDIS_URL });
 
// Session configuration with secure cookies
app.use(session({
    store: new RedisStore({ client: redis }),
    secret: process.env.SESSION_SECRET!,
    resave: false,
    saveUninitialized: false,
    name: '__Host-session', // __Host- prefix ensures secure, same-origin cookies
    cookie: {
        httpOnly: true,        // Not accessible to JavaScript
        secure: true,          // HTTPS only
        sameSite: 'strict',    // CSRF protection
        maxAge: 24 * 60 * 60 * 1000, // 24 hours
        path: '/',
    },
}));
 
// CSRF protection
const csrfProtection = (req: Request, res: Response, next: NextFunction) => {
    const csrfToken = req.headers['x-csrf-token'];
    const sessionCsrf = (req.session as any).csrfToken;
    
    if (!csrfToken || csrfToken !== sessionCsrf) {
        return res.status(403).json({ error: 'Invalid CSRF token' });
    }
    next();
};
 
// BFF Login endpoint - initiates OAuth flow
app.get('/bff/auth/login', (req, res) => {
    const state = crypto.randomUUID();
    const nonce = crypto.randomUUID();
    
    // Store in session for validation on callback
    (req.session as any).oauthState = state;
    (req.session as any).oauthNonce = nonce;
    
    const authUrl = new URL('https://auth.example.com/authorize');
    authUrl.searchParams.set('client_id', process.env.OAUTH_CLIENT_ID!);
    authUrl.searchParams.set('redirect_uri', 'https://app.example.com/bff/auth/callback');
    authUrl.searchParams.set('response_type', 'code');
    authUrl.searchParams.set('scope', 'openid email profile offline_access');
    authUrl.searchParams.set('state', state);
    authUrl.searchParams.set('nonce', nonce);
    
    res.redirect(authUrl.toString());
});
 
// BFF Callback - handles OAuth callback, stores tokens
app.get('/bff/auth/callback', async (req, res) => {
    const { code, state } = req.query;
    
    // Validate state
    if (state !== (req.session as any).oauthState) {
        return res.status(403).send('State mismatch');
    }
    
    try {
        // Exchange code for tokens
        const tokenResponse = await fetch('https://auth.example.com/oauth/token', {
            method: 'POST',
            headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
            body: new URLSearchParams({
                grant_type: 'authorization_code',
                code: code as string,
                client_id: process.env.OAUTH_CLIENT_ID!,
                client_secret: process.env.OAUTH_CLIENT_SECRET!,
                redirect_uri: 'https://app.example.com/bff/auth/callback',
            }),
        });
        
        const tokens = await tokenResponse.json();
        
        // Validate ID token
        const jwks = jose.createRemoteJWKSet(
            new URL('https://auth.example.com/.well-known/jwks.json')
        );
        const { payload } = await jose.jwtVerify(tokens.id_token, jwks, {
            issuer: 'https://auth.example.com',
            audience: process.env.OAUTH_CLIENT_ID!,
        });
        
        // Validate nonce
        if (payload.nonce !== (req.session as any).oauthNonce) {
            throw new Error('Nonce mismatch');
        }
        
        // Store tokens in session (server-side, not browser!)
        (req.session as any).tokens = {
            accessToken: tokens.access_token,
            refreshToken: tokens.refresh_token,
            expiresAt: Date.now() + (tokens.expires_in * 1000),
        };
        (req.session as any).user = {
            id: payload.sub,
            email: payload.email,
            name: payload.name,
        };
        (req.session as any).csrfToken = crypto.randomUUID();
        
        // Clear OAuth state
        delete (req.session as any).oauthState;
        delete (req.session as any).oauthNonce;
        
        // Redirect to app
        res.redirect('https://app.example.com');
    } catch (error) {
        console.error('Auth callback error:', error);
        res.redirect('https://app.example.com/login?error=auth_failed');
    }
});
 
// BFF User Info - returns user info to SPA
app.get('/bff/auth/user', (req, res) => {
    if (!(req.session as any).user) {
        return res.status(401).json({ authenticated: false });
    }
    
    res.json({
        authenticated: true,
        user: (req.session as any).user,
        csrfToken: (req.session as any).csrfToken,
    });
});
 
// BFF API Proxy - proxies requests to resource server with token
app.all('/bff/api/*', csrfProtection, async (req, res) => {
    const session = req.session as any;
    
    if (!session.tokens) {
        return res.status(401).json({ error: 'Not authenticated' });
    }
    
    // Refresh token if needed
    if (Date.now() > session.tokens.expiresAt - 60000) {
        try {
            const refreshed = await refreshTokens(session.tokens.refreshToken);
            session.tokens = {
                accessToken: refreshed.access_token,
                refreshToken: refreshed.refresh_token || session.tokens.refreshToken,
                expiresAt: Date.now() + (refreshed.expires_in * 1000),
            };
        } catch {
            return res.status(401).json({ error: 'Session expired' });
        }
    }
    
    // Forward request to resource server
    const apiPath = req.path.replace('/bff/api', '');
    const apiResponse = await fetch(`https://api.example.com${apiPath}`, {
        method: req.method,
        headers: {
            'Authorization': `Bearer ${session.tokens.accessToken}`,
            'Content-Type': 'application/json',
        },
        body: ['GET', 'HEAD'].includes(req.method) ? undefined : JSON.stringify(req.body),
    });
    
    res.status(apiResponse.status).json(await apiResponse.json());
});
 
// BFF Logout
app.post('/bff/auth/logout', csrfProtection, (req, res) => {
    req.session.destroy((err) => {
        if (err) {
            return res.status(500).json({ error: 'Logout failed' });
        }
        res.clearCookie('__Host-session');
        res.json({ success: true });
    });
});

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

// Pattern 1: Token Forwarding
class ServiceAClient {
    async callServiceB(userAccessToken: string): Promise<any> {
        // Forward the user's token to downstream service
        return fetch('https://service-b.internal/api/resource', {
            headers: {
                'Authorization': `Bearer ${userAccessToken}`,
            },
        });
    }
}
 
// Pattern 2: Token Exchange (RFC 8693)
class TokenExchangeClient {
    constructor(
        private tokenEndpoint: string,
        private clientId: string,
        private clientSecret: string,
    ) {}
    
    async exchange(
        subjectToken: string,
        targetAudience: string,
        scopes: string[],
    ): Promise<string> {
        const response = await fetch(this.tokenEndpoint, {
            method: 'POST',
            headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
            body: new URLSearchParams({
                grant_type: 'urn:ietf:params:oauth:grant-type:token-exchange',
                subject_token: subjectToken,
                subject_token_type: 'urn:ietf:params:oauth:token-type:access_token',
                requested_token_type: 'urn:ietf:params:oauth:token-type:access_token',
                audience: targetAudience,
                scope: scopes.join(' '),
                client_id: this.clientId,
                client_secret: this.clientSecret,
            }),
        });
        
        const data = await response.json();
        return data.access_token;
    }
}
 
// Usage: Gateway service exchanges token for internal services
class APIGateway {
    private tokenExchange: TokenExchangeClient;
    
    async handleRequest(userToken: string, targetService: string) {
        // Exchange user's token for service-specific token
        const serviceToken = await this.tokenExchange.exchange(
            userToken,
            `https://${targetService}.internal`,
            ['service:read'],
        );
        
        // Call internal service with exchanged token
        return fetch(`https://${targetService}.internal/api/resource`, {
            headers: { 'Authorization': `Bearer ${serviceToken}` },
        });
    }
}
 
// Pattern 3: Service-to-Service with Client Credentials
class InternalServiceClient {
    private accessToken: string | null = null;
    private tokenExpiry: number = 0;
    
    constructor(
        private tokenEndpoint: string,
        private clientId: string,
        private clientSecret: string,
        private targetAudience: string,
    ) {}
    
    private async ensureToken(): Promise<string> {
        if (this.accessToken && Date.now() < this.tokenExpiry - 60000) {
            return this.accessToken;
        }
        
        const response = await fetch(this.tokenEndpoint, {
            method: 'POST',
            headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
            body: new URLSearchParams({
                grant_type: 'client_credentials',
                client_id: this.clientId,
                client_secret: this.clientSecret,
                audience: this.targetAudience,
            }),
        });
        
        const data = await response.json();
        this.accessToken = data.access_token;
        this.tokenExpiry = Date.now() + (data.expires_in * 1000);
        
        return this.accessToken;
    }
    
    async callService(path: string): Promise<any> {
        const token = await this.ensureToken();
        return fetch(`${this.targetAudience}${path}`, {
            headers: { 'Authorization': `Bearer ${token}` },
        });
    }
}
 
// Combining User Context with Service Identity
class ServiceWithUserContext {
    private serviceClient: InternalServiceClient;
    
    async callWithUserContext(userToken: string, path: string) {
        // Get service-to-service token for authentication
        const serviceToken = await this.serviceClient.ensureToken();
        
        // Pass both: service identity + user context
        return fetch(`https://downstream.internal${path}`, {
            headers: {
                'Authorization': `Bearer ${serviceToken}`, // Service identity
                'X-User-Token': userToken, // User context (validated downstream)
            },
        });
    }
}

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

// Production-Ready OAuth Client Configuration
interface ProductionOAuthConfig {
    // Multiple authorization servers for failover
    authServers: Array<{
        url: string;
        priority: number;
        healthCheck: string;
    }>;
    
    // Client credentials from secrets manager
    credentials: {
        provider: 'vault' | 'aws-secrets' | 'azure-keyvault';
        path: string;
    };
    
    // Resilience settings
    resilience: {
        timeout: number;
        retries: number;
        circuitBreaker: {
            failureThreshold: number;
            resetTimeout: number;
        };
    };
    
    // Observability
    observability: {
        metrics: boolean;
        tracing: boolean;
        auditLog: boolean;
    };
}
 
// Health check for auth server
class AuthServerHealthCheck {
    async checkHealth(serverUrl: string): Promise<boolean> {
        try {
            const response = await fetch(
                `${serverUrl}/.well-known/openid-configuration`,
                { timeout: 5000 }
            );
            return response.ok;
        } catch {
            return false;
        }
    }
    
    async selectHealthyServer(servers: ProductionOAuthConfig['authServers']): Promise<string> {
        // Sort by priority
        const sortedServers = [...servers].sort((a, b) => a.priority - b.priority);
        
        for (const server of sortedServers) {
            if (await this.checkHealth(server.url)) {
                return server.url;
            }
        }
        
        throw new Error('No healthy auth servers available');
    }
}
 
// Metrics for OAuth operations
class OAuthMetrics {
    private metrics: MetricsClient;
    
    recordTokenRequest(success: boolean, grantType: string, durationMs: number) {
        this.metrics.increment('oauth.token_request', {
            success: String(success),
            grant_type: grantType,
        });
        this.metrics.histogram('oauth.token_request_duration', durationMs, {
            grant_type: grantType,
        });
    }
    
    recordTokenValidation(success: boolean, error?: string) {
        this.metrics.increment('oauth.token_validation', {
            success: String(success),
            error: error || 'none',
        });
    }
    
    recordRefreshToken(success: boolean) {
        this.metrics.increment('oauth.token_refresh', {
            success: String(success),
        });
    }
}
 
// Audit logging for compliance
interface AuthAuditEvent {
    timestamp: Date;
    eventType: 'login' | 'logout' | 'token_issued' | 'token_refresh' | 'token_revoked';
    userId?: string;
    clientId: string;
    ipAddress: string;
    userAgent: string;
    success: boolean;
    failureReason?: string;
    mfaUsed?: boolean;
    mfaMethod?: string;
    sessionId?: string;
}
 
class AuthAuditLogger {
    constructor(private logDestination: AuditLogDestination) {}
    
    async logAuthEvent(event: AuthAuditEvent): Promise<void> {
        // Ensure immutable, append-only logging
        await this.logDestination.append({
            ...event,
            timestamp: new Date(),
            logId: crypto.randomUUID(),
        });
    }
}

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

// OAuth Testing Utilities
import * as jose from 'jose';
import { generateKeyPair } from 'jose';
 
// Generate test keys for JWT creation
async function createTestKeys() {
    const { publicKey, privateKey } = await generateKeyPair('RS256');
    return { publicKey, privateKey };
}
 
// Create test JWT with custom claims
async function createTestToken(
    privateKey: jose.KeyLike,
    claims: Record<string, any>,
    options?: { expiresIn?: string; kid?: string }
): Promise<string> {
    const jwt = new jose.SignJWT(claims)
        .setProtectedHeader({ 
            alg: 'RS256', 
            typ: 'JWT',
            kid: options?.kid || 'test-key-1',
        })
        .setIssuedAt()
        .setIssuer('https://test-auth.example.com')
        .setAudience('test-client-id');
    
    if (options?.expiresIn) {
        jwt.setExpirationTime(options.expiresIn);
    }
    
    return jwt.sign(privateKey);
}
 
// Test fixture factory
class OAuthTestFixtures {
    private privateKey: jose.KeyLike;
    private publicKey: jose.KeyLike;
    
    async init() {
        const keys = await createTestKeys();
        this.privateKey = keys.privateKey;
        this.publicKey = keys.publicKey;
    }
    
    async validToken(overrides?: Record<string, any>): Promise<string> {
        return createTestToken(this.privateKey, {
            sub: 'test-user-123',
            email: 'test@example.com',
            scope: 'openid email profile',
            ...overrides,
        }, { expiresIn: '1h' });
    }
    
    async expiredToken(): Promise<string> {
        return createTestToken(this.privateKey, {
            sub: 'test-user-123',
            exp: Math.floor(Date.now() / 1000) - 3600, // 1 hour ago
        });
    }
    
    async wrongAudienceToken(): Promise<string> {
        const claims = { sub: 'test-user-123', aud: 'wrong-client-id' };
        return new jose.SignJWT(claims)
            .setProtectedHeader({ alg: 'RS256', typ: 'JWT' })
            .setIssuedAt()
            .setExpirationTime('1h')
            .sign(this.privateKey);
    }
    
    // Mock JWKS endpoint response
    async mockJWKS(): Promise<object> {
        const publicJwk = await jose.exportJWK(this.publicKey);
        return {
            keys: [{
                ...publicJwk,
                kid: 'test-key-1',
                use: 'sig',
                alg: 'RS256',
            }],
        };
    }
}
 
// Example test cases
describe('TokenValidator', () => {
    let fixtures: OAuthTestFixtures;
    let validator: TokenValidator;
    
    beforeAll(async () => {
        fixtures = new OAuthTestFixtures();
        await fixtures.init();
        
        // Configure validator with test JWKS
        validator = new TokenValidator({
            issuer: 'https://test-auth.example.com',
            audience: 'test-client-id',
            jwks: await fixtures.mockJWKS(),
        });
    });
    
    test('validates correct token', async () => {
        const token = await fixtures.validToken();
        const result = await validator.validate(token);
        
        expect(result.valid).toBe(true);
        expect(result.payload?.sub).toBe('test-user-123');
    });
    
    test('rejects expired token', async () => {
        const token = await fixtures.expiredToken();
        const result = await validator.validate(token);
        
        expect(result.valid).toBe(false);
        expect(result.error).toContain('expired');
    });
    
    test('rejects wrong audience', async () => {
        const token = await fixtures.wrongAudienceToken();
        const result = await validator.validate(token);
        
        expect(result.valid).toBe(false);
        expect(result.error).toContain('audience');
    });
    
    test('rejects tampered token', async () => {
        const token = await fixtures.validToken();
        const tamperedToken = token.slice(0, -5) + 'XXXXX'; // Corrupt signature
        
        const result = await validator.validate(tamperedToken);
        expect(result.valid).toBe(false);
    });
});