OAuth 2.0 and OpenID Connect: Modern Authentication

OAuth 2.0 and OpenID Connect (OIDC) are the foundation of modern authentication. This guide covers implementing these protocols securely in web applications.

Understanding the Protocols#

OAuth 2.0#

OAuth 2.0 is an authorization framework that enables applications to obtain limited access to user accounts.

┌──────────┐                               ┌──────────────┐
│          │──(1) Authorization Request──>│              │
│          │                               │   Resource   │
│          │<─(2) Authorization Grant────│    Owner     │
│          │                               │              │
│  Client  │                               └──────────────┘
│          │                               ┌──────────────┐
│          │──(3) Authorization Grant──>  │              │
│          │                               │ Authorization│
│          │<─(4) Access Token─────────  │   Server     │
│          │                               │              │
│          │                               └──────────────┘
│          │                               ┌──────────────┐
│          │──(5) Access Token──────────>│              │
│          │                               │   Resource   │
│          │<─(6) Protected Resource────│   Server     │
│          │                               │              │
└──────────┘                               └──────────────┘

OpenID Connect#

OIDC adds an identity layer on top of OAuth 2.0:

ID Token: JWT containing user identity claims
UserInfo Endpoint: Returns user profile information
Standard Scopes: openid, profile, email, address, phone

Authorization Code Flow with PKCE#

The recommended flow for web applications:

// Step 1: Generate PKCE values
function generatePKCE() {
  const verifier = crypto.randomBytes(32).toString('base64url');
  const challenge = crypto
    .createHash('sha256')
    .update(verifier)
    .digest('base64url');

  return { verifier, challenge };
}

// Step 2: Redirect to authorization endpoint
function initiateLogin() {
  const { verifier, challenge } = generatePKCE();
  const state = crypto.randomBytes(16).toString('hex');

  // Store verifier and state in session
  session.codeVerifier = verifier;
  session.state = state;

  const params = new URLSearchParams({
    client_id: process.env.OAUTH_CLIENT_ID,
    redirect_uri: 'https://myapp.com/callback',
    response_type: 'code',
    scope: 'openid profile email',
    state,
    code_challenge: challenge,
    code_challenge_method: 'S256',
  });

  return `https://auth.provider.com/authorize?${params}`;
}

// Step 3: Handle callback
async function handleCallback(code: string, state: string) {
  // Verify state
  if (state !== session.state) {
    throw new Error('Invalid state parameter');
  }

  // Exchange code for tokens
  const response = await fetch('https://auth.provider.com/token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({
      grant_type: 'authorization_code',
      client_id: process.env.OAUTH_CLIENT_ID,
      client_secret: process.env.OAUTH_CLIENT_SECRET,
      code,
      redirect_uri: 'https://myapp.com/callback',
      code_verifier: session.codeVerifier,
    }),
  });

  const tokens = await response.json();
  return tokens;
}

Token Handling#

Validating ID Tokens#

import jwt from 'jsonwebtoken';
import jwksClient from 'jwks-rsa';

const client = jwksClient({
  jwksUri: 'https://auth.provider.com/.well-known/jwks.json',
  cache: true,
  rateLimit: true,
});

async function validateIdToken(idToken: string): Promise<TokenPayload> {
  // Decode header to get key ID
  const decoded = jwt.decode(idToken, { complete: true });
  if (!decoded || typeof decoded === 'string') {
    throw new Error('Invalid token');
  }

  // Get signing key
  const key = await client.getSigningKey(decoded.header.kid);
  const publicKey = key.getPublicKey();

  // Verify token
  const payload = jwt.verify(idToken, publicKey, {
    algorithms: ['RS256'],
    audience: process.env.OAUTH_CLIENT_ID,
    issuer: 'https://auth.provider.com',
  }) as TokenPayload;

  // Additional validations
  const now = Math.floor(Date.now() / 1000);

  if (payload.exp < now) {
    throw new Error('Token expired');
  }

  if (payload.iat > now + 60) {
    throw new Error('Token issued in the future');
  }

  // Verify nonce if present
  if (session.nonce && payload.nonce !== session.nonce) {
    throw new Error('Invalid nonce');
  }

  return payload;
}

Refresh Token Flow#

class TokenManager {
  private accessToken: string | null = null;
  private refreshToken: string | null = null;
  private expiresAt: number = 0;

  async getAccessToken(): Promise<string> {
    // Check if token needs refresh (with buffer)
    if (Date.now() >= this.expiresAt - 60000) {
      await this.refresh();
    }

    if (!this.accessToken) {
      throw new Error('No access token available');
    }

    return this.accessToken;
  }

  private async refresh(): Promise<void> {
    if (!this.refreshToken) {
      throw new Error('No refresh token available');
    }

    const response = await fetch('https://auth.provider.com/token', {
      method: 'POST',
      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
      body: new URLSearchParams({
        grant_type: 'refresh_token',
        client_id: process.env.OAUTH_CLIENT_ID,
        client_secret: process.env.OAUTH_CLIENT_SECRET,
        refresh_token: this.refreshToken,
      }),
    });

    if (!response.ok) {
      // Refresh token expired or revoked
      this.clear();
      throw new Error('Session expired');
    }

    const tokens = await response.json();
    this.setTokens(tokens);
  }

  setTokens(tokens: TokenResponse): void {
    this.accessToken = tokens.access_token;
    this.refreshToken = tokens.refresh_token || this.refreshToken;
    this.expiresAt = Date.now() + tokens.expires_in * 1000;
  }

  clear(): void {
    this.accessToken = null;
    this.refreshToken = null;
    this.expiresAt = 0;
  }
}

Backend for Frontend (BFF) Pattern#

Keep tokens secure on the server:

// API Route: /api/auth/login
export async function POST(req: Request) {
  const { verifier, challenge } = generatePKCE();
  const state = crypto.randomUUID();

  // Store in HTTP-only cookie
  const session = await encrypt({ verifier, state });

  cookies().set('auth_session', session, {
    httpOnly: true,
    secure: true,
    sameSite: 'lax',
    maxAge: 600, // 10 minutes
  });

  const authUrl = buildAuthUrl({ state, challenge });
  return Response.json({ authUrl });
}

// API Route: /api/auth/callback
export async function GET(req: Request) {
  const { searchParams } = new URL(req.url);
  const code = searchParams.get('code');
  const state = searchParams.get('state');

  // Retrieve session
  const sessionCookie = cookies().get('auth_session');
  const session = await decrypt(sessionCookie.value);

  if (state !== session.state) {
    return Response.redirect('/login?error=invalid_state');
  }

  // Exchange code for tokens
  const tokens = await exchangeCode(code, session.verifier);

  // Validate ID token
  const idToken = await validateIdToken(tokens.id_token);

  // Create application session
  const appSession = await encrypt({
    userId: idToken.sub,
    accessToken: tokens.access_token,
    refreshToken: tokens.refresh_token,
    expiresAt: Date.now() + tokens.expires_in * 1000,
  });

  cookies().set('app_session', appSession, {
    httpOnly: true,
    secure: true,
    sameSite: 'strict',
    maxAge: 7 * 24 * 60 * 60, // 7 days
  });

  return Response.redirect('/dashboard');
}

// API Route: /api/proxy/[...path]
export async function handler(req: Request) {
  const session = await getSession();

  if (!session) {
    return Response.json({ error: 'Unauthorized' }, { status: 401 });
  }

  // Refresh if needed
  if (Date.now() >= session.expiresAt - 60000) {
    const newTokens = await refreshTokens(session.refreshToken);
    await updateSession(newTokens);
    session.accessToken = newTokens.access_token;
  }

  // Proxy request to resource server
  const path = req.url.replace('/api/proxy', '');
  const response = await fetch(`https://api.service.com${path}`, {
    method: req.method,
    headers: {
      'Authorization': `Bearer ${session.accessToken}`,
      'Content-Type': 'application/json',
    },
    body: req.method !== 'GET' ? await req.text() : undefined,
  });

  return response;
}

// Auth.js (NextAuth) configuration
import NextAuth from 'next-auth';
import Google from 'next-auth/providers/google';
import GitHub from 'next-auth/providers/github';

export const { handlers, auth, signIn, signOut } = NextAuth({
  providers: [
    Google({
      clientId: process.env.GOOGLE_CLIENT_ID,
      clientSecret: process.env.GOOGLE_CLIENT_SECRET,
      authorization: {
        params: {
          prompt: 'consent',
          access_type: 'offline',
          response_type: 'code',
        },
      },
    }),
    GitHub({
      clientId: process.env.GITHUB_CLIENT_ID,
      clientSecret: process.env.GITHUB_CLIENT_SECRET,
    }),
  ],
  callbacks: {
    async jwt({ token, account }) {
      if (account) {
        token.accessToken = account.access_token;
        token.refreshToken = account.refresh_token;
        token.expiresAt = account.expires_at;
      }
      return token;
    },
    async session({ session, token }) {
      session.accessToken = token.accessToken;
      return session;
    },
  },
});

Security Best Practices#

State and Nonce#

// Always use state to prevent CSRF
const state = crypto.randomBytes(32).toString('hex');
session.oauthState = state;

// Use nonce for ID token replay protection
const nonce = crypto.randomBytes(32).toString('hex');
session.oauthNonce = nonce;

const authUrl = new URL('https://auth.provider.com/authorize');
authUrl.searchParams.set('state', state);
authUrl.searchParams.set('nonce', nonce);

Token Storage#

// Never store tokens in localStorage or sessionStorage
// Bad
localStorage.setItem('access_token', token);

// Good: HTTP-only cookies
cookies().set('session', encryptedSession, {
  httpOnly: true,    // Not accessible via JavaScript
  secure: true,      // HTTPS only
  sameSite: 'strict', // CSRF protection
  path: '/',
});

Logout#

async function logout() {
  // Clear local session
  cookies().delete('app_session');

  // Revoke tokens at provider
  await fetch('https://auth.provider.com/revoke', {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({
      token: session.refreshToken,
      token_type_hint: 'refresh_token',
      client_id: process.env.OAUTH_CLIENT_ID,
      client_secret: process.env.OAUTH_CLIENT_SECRET,
    }),
  });

  // Redirect to provider logout (optional)
  const logoutUrl = new URL('https://auth.provider.com/logout');
  logoutUrl.searchParams.set('post_logout_redirect_uri', 'https://myapp.com');

  return Response.redirect(logoutUrl);
}

OAuth 2.0 and OIDC provide secure, standardized authentication. Always use PKCE for public clients, validate tokens properly, store tokens securely in HTTP-only cookies, and implement proper logout. Consider using the BFF pattern for SPAs to keep tokens server-side.