Implementa OAuth 2.0 PKCE para Aplicaciones de Una Sola

La extension Proof Key for Code Exchange (PKCE) de OAuth 2.0 permite que clientes publicos como aplicaciones de una sola pagina ejecuten el flujo de codigo de autorizacion sin un secreto de cliente. Previene ataques de interceptacion de codigo de autorizacion al vincular la peticion de autorizacion al posterior intercambio de token.

Cuando Usar Esto

• Estas construyendo una SPA que se autentica contra un proveedor OAuth 2.0 u OpenID Connect
• La aplicacion ejecuta en un navegador donde un secreto de cliente no puede mantenerse confidencial
• Quieres prevenir interceptacion de codigo de autorizacion por aplicaciones maliciosas

Requisitos Previos

• Un proveedor OAuth 2.0 que soporte PKCE (Auth0, Okta, Google, Keycloak, etc.)
• Una aplicacion OAuth registrada con http://localhost:3000 como redirect URI

Solucion

1. Generar Parametros PKCE

// auth/pkce.ts
import { randomBytes, createHash } from 'crypto';

export function generatePKCE() {
  const codeVerifier = base64URLEncode(randomBytes(32));
  const codeChallenge = base64URLEncode(
    createHash('sha256').update(codeVerifier).digest()
  );
  return { codeVerifier, codeChallenge };
}

function base64URLEncode(buffer: Buffer): string {
  return buffer
    .toString('base64')
    .replace(/\+/g, '-')
    .replace(/\//g, '_')
    .replace(/=/g, '');
}

2. Redirigir al Endpoint de Autorizacion

// auth/authorize.ts
export function buildAuthorizationUrl(params: {
  authorizationEndpoint: string;
  clientId: string;
  redirectUri: string;
  scope: string;
  state: string;
  codeChallenge: string;
}) {
  const url = new URL(params.authorizationEndpoint);
  url.searchParams.set('response_type', 'code');
  url.searchParams.set('client_id', params.clientId);
  url.searchParams.set('redirect_uri', params.redirectUri);
  url.searchParams.set('scope', params.scope);
  url.searchParams.set('state', params.state);
  url.searchParams.set('code_challenge', params.codeChallenge);
  url.searchParams.set('code_challenge_method', 'S256');
  return url.toString();
}

// Uso
const { codeVerifier, codeChallenge } = generatePKCE();
sessionStorage.setItem('pkce_verifier', codeVerifier);

const state = generateState();
sessionStorage.setItem('oauth_state', state);

window.location.href = buildAuthorizationUrl({
  authorizationEndpoint: 'https://auth.example.com/oauth/authorize',
  clientId: 'your-client-id',
  redirectUri: 'http://localhost:3000/callback',
  scope: 'openid profile email',
  state,
  codeChallenge,
});

3. Intercambiar Codigo por Tokens

// auth/tokenExchange.ts
export async function exchangeCodeForToken(params: {
  tokenEndpoint: string;
  clientId: string;
  redirectUri: string;
  code: string;
  codeVerifier: string;
}) {
  const response = await fetch(params.tokenEndpoint, {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({
      grant_type: 'authorization_code',
      client_id: params.clientId,
      redirect_uri: params.redirectUri,
      code: params.code,
      code_verifier: params.codeVerifier,
    }),
  });

  if (!response.ok) {
    throw new Error(`Token exchange failed: ${response.statusText}`);
  }

  return response.json() as Promise<{
    access_token: string;
    refresh_token: string;
    id_token: string;
    expires_in: number;
  }>;
}

// En callback handler
const urlParams = new URLSearchParams(window.location.search);
const code = urlParams.get('code');
const state = urlParams.get('state');

if (state !== sessionStorage.getItem('oauth_state')) {
  throw new Error('Parametro state invalido');
}

const codeVerifier = sessionStorage.getItem('pkce_verifier')!;
const tokens = await exchangeCodeForToken({
  tokenEndpoint: 'https://auth.example.com/oauth/token',
  clientId: 'your-client-id',
  redirectUri: 'http://localhost:3000/callback',
  code: code!,
  codeVerifier,
});

4. Almacenamiento Seguro de Tokens

// auth/storage.ts
export function storeTokens(tokens: TokenResponse) {
  // Almacena access token solo en memoria (mas seguro para SPAs)
  window.__ACCESS_TOKEN__ = tokens.access_token;
  
  // Almacena refresh token en cookie httpOnly via backend proxy
  // Nunca almacenes refresh tokens en localStorage
}

export function getAccessToken(): string | undefined {
  return window.__ACCESS_TOKEN__;
}

Como Funciona

1. Code Verifier es un secreto aleatorio generado por el cliente
2. Code Challenge es el hash SHA-256 del verifier, enviado con la peticion de autorizacion
3. Servidor de Autorizacion almacena el challenge y emite un codigo de autorizacion
4. Intercambio de Token requiere el verifier original, probando que el cliente inicio el flujo
5. Sin PKCE, un codigo de autorizacion interceptado podria ser intercambiado por un atacante

Consideraciones de Produccion

• Valida siempre el parametro state para prevenir ataques CSRF
• Usa Content Security Policy headers para mitigar robo de tokens por XSS
• Implementa silent token refresh usando prompt=none en un iframe oculto
• Rota refresh tokens y detecta reutilizacion para prevenir ataques de replay

Errores Comunes

• Almacenar tokens en localStorage donde XSS puede robarlos facilmente
• No validar el parametro state durante el manejo del callback
• Usar response_type=token (flujo implicito) que esta deprecado para SPAs

Soluciones Avanzadas

Silent token refresh con iframe oculto

Refresca tokens sin un redirect completo usando prompt=none en un iframe oculto. Esto funciona cuando el usuario aún tiene una sesión activa con el servidor de autorización:

// auth/silentRefresh.ts
export function silentRefresh(config: {
  authorizationEndpoint: string;
  clientId: string;
  redirectUri: string;
  scope: string;
}): Promise<TokenResponse> {
  return new Promise((resolve, reject) => {
    const state = generateRandomString(32);
    const iframe = document.createElement('iframe');
    iframe.style.display = 'none';
    iframe.src = buildAuthorizationUrl({
      ...config,
      state,
      codeChallenge: '', // No needed para silent refresh
      prompt: 'none',
      response_type: 'code',
    });

    let cleanup: () => void;

    const timeout = setTimeout(() => {
      cleanup();
      reject(new Error('Silent refresh timed out'));
    }, 5000);

    const messageHandler = (event: MessageEvent) => {
      if (event.origin !== new URL(config.authorizationEndpoint).origin) return;
      if (event.data.state !== state) return;

      cleanup();
      if (event.data.error) {
        reject(new Error(event.data.error));
      } else {
        resolve(event.data as TokenResponse);
      }
    };

    cleanup = () => {
      clearTimeout(timeout);
      window.removeEventListener('message', messageHandler);
      iframe.remove();
    };

    window.addEventListener('message', messageHandler);
    document.body.appendChild(iframe);
  });
}

// Uso: llamar antes de que el token expire
async function refreshIfNeeded() {
  const token = getAccessToken();
  if (!token || isTokenExpired(token)) {
    try {
      const tokens = await silentRefresh({
        authorizationEndpoint: 'https://auth.example.com/oauth/authorize',
        clientId: 'your-client-id',
        redirectUri: 'http://localhost:3000/callback',
        scope: 'openid profile email',
      });
      storeTokens(tokens);
    } catch (err) {
      // Sesión expirada, redirigir a login
      window.location.href = '/login';
    }
  }
}

function isTokenExpired(token: string): boolean {
  const payload = JSON.parse(atob(token.split('.')[1]));
  return Date.now() >= payload.exp * 1000 - 30_000; // 30s buffer
}

Patrón Backend-for-frontend (BFF)

En lugar de manejar OAuth completamente en el navegador, usa un backend ligero que almacena los tokens en cookies httpOnly. La SPA solo interactúa con el backend:

// server/bff-auth.ts (Express backend)
import express from 'express';
import crypto from 'crypto';
import cookieParser from 'cookie-parser';

const app = express();
app.use(cookieParser());

const CLIENT_ID = process.env.OAUTH_CLIENT_ID!;
const CLIENT_SECRET = process.env.OAUTH_CLIENT_SECRET!;
const TOKEN_ENDPOINT = 'https://auth.example.com/oauth/token';
const AUTHORIZATION_ENDPOINT = 'https://auth.example.com/oauth/authorize';
const REDIRECT_URI = 'https://app.example.com/auth/callback';

app.get('/auth/login', (req, res) => {
  const codeVerifier = base64URLEncode(crypto.randomBytes(32));
  const codeChallenge = base64URLEncode(
    crypto.createHash('sha256').update(codeVerifier).digest()
  );
  const state = base64URLEncode(crypto.randomBytes(16));

  res.cookie('pkce_verifier', codeVerifier, {
    httpOnly: true,
    secure: true,
    sameSite: 'strict',
    maxAge: 600_000, // 10 minutos
  });
  res.cookie('oauth_state', state, {
    httpOnly: true,
    secure: true,
    sameSite: 'strict',
    maxAge: 600_000,
  });

  const url = new URL(AUTHORIZATION_ENDPOINT);
  url.searchParams.set('response_type', 'code');
  url.searchParams.set('client_id', CLIENT_ID);
  url.searchParams.set('redirect_uri', REDIRECT_URI);
  url.searchParams.set('scope', 'openid profile email');
  url.searchParams.set('state', state);
  url.searchParams.set('code_challenge', codeChallenge);
  url.searchParams.set('code_challenge_method', 'S256');

  res.redirect(url.toString());
});

app.get('/auth/callback', async (req, res) => {
  const { code, state } = req.query;
  const expectedState = req.cookies.oauth_state;
  const codeVerifier = req.cookies.pkce_verifier;

  if (!code || state !== expectedState) {
    return res.status(400).send('State inválido o código faltante');
  }

  const tokenResponse = await fetch(TOKEN_ENDPOINT, {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({
      grant_type: 'authorization_code',
      client_id: CLIENT_ID,
      client_secret: CLIENT_SECRET,
      redirect_uri: REDIRECT_URI,
      code: code as string,
      code_verifier: codeVerifier,
    }),
  });

  const tokens = await tokenResponse.json();

  // Almacenar tokens en cookies httpOnly — nunca expuestos a JS
  res.cookie('access_token', tokens.access_token, {
    httpOnly: true,
    secure: true,
    sameSite: 'strict',
    maxAge: tokens.expires_in * 1000,
  });
  res.cookie('refresh_token', tokens.refresh_token, {
    httpOnly: true,
    secure: true,
    sameSite: 'strict',
    maxAge: 30 * 24 * 60 * 60 * 1000, // 30 días
  });

  res.clearCookie('pkce_verifier');
  res.clearCookie('oauth_state');
  res.redirect('/');
});

app.get('/auth/token', (req, res) => {
  const accessToken = req.cookies.access_token;
  if (!accessToken) {
    return res.status(401).json({ error: 'No autenticado' });
  }
  // Retornar token a SPA para llamadas API
  res.json({ access_token: accessToken });
});

app.post('/auth/refresh', async (req, res) => {
  const refreshToken = req.cookies.refresh_token;
  if (!refreshToken) {
    return res.status(401).json({ error: 'No refresh token' });
  }

  const tokenResponse = await fetch(TOKEN_ENDPOINT, {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({
      grant_type: 'refresh_token',
      client_id: CLIENT_ID,
      client_secret: CLIENT_SECRET,
      refresh_token: refreshToken,
    }),
  });

  const tokens = await tokenResponse.json();

  res.cookie('access_token', tokens.access_token, {
    httpOnly: true,
    secure: true,
    sameSite: 'strict',
    maxAge: tokens.expires_in * 1000,
  });

  if (tokens.refresh_token) {
    res.cookie('refresh_token', tokens.refresh_token, {
      httpOnly: true,
      secure: true,
      sameSite: 'strict',
      maxAge: 30 * 24 * 60 * 60 * 1000,
    });
  }

  res.json({ success: true });
});

app.post('/auth/logout', async (req, res) => {
  const refreshToken = req.cookies.refresh_token;
  if (refreshToken) {
    // Revocar token en el servidor de auth
    await fetch(TOKEN_ENDPOINT + '/revoke', {
      method: 'POST',
      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
      body: new URLSearchParams({
        token: refreshToken,
        client_id: CLIENT_ID,
        client_secret: CLIENT_SECRET,
      }),
    });
  }
  res.clearCookie('access_token');
  res.clearCookie('refresh_token');
  res.json({ success: true });
});

React hook para gestión de estado OAuth

// hooks/useAuth.ts
import { useState, useEffect, useCallback } from 'react';

interface AuthState {
  isAuthenticated: boolean;
  accessToken: string | null;
  loading: boolean;
  error: string | null;
}

export function useAuth() {
  const [state, setState] = useState<AuthState>({
    isAuthenticated: false,
    accessToken: null,
    loading: true,
    error: null,
  });

  const login = useCallback(() => {
    window.location.href = '/auth/login';
  }, []);

  const logout = useCallback(async () => {
    await fetch('/auth/logout', { method: 'POST' });
    setState({
      isAuthenticated: false,
      accessToken: null,
      loading: false,
      error: null,
    });
    window.location.href = '/';
  }, []);

  const refreshToken = useCallback(async () => {
    try {
      const res = await fetch('/auth/refresh', { method: 'POST' });
      if (!res.ok) throw new Error('Refresh falló');
      const data = await res.json();
      if (data.success) {
        const tokenRes = await fetch('/auth/token');
        const tokenData = await tokenRes.json();
        setState({
          isAuthenticated: true,
          accessToken: tokenData.access_token,
          loading: false,
          error: null,
        });
      }
    } catch {
      setState({
        isAuthenticated: false,
        accessToken: null,
        loading: false,
        error: 'Sesión expirada',
      });
    }
  }, []);

  useEffect(() => {
    async function init() {
      try {
        const res = await fetch('/auth/token');
        if (res.ok) {
          const data = await res.json();
          setState({
            isAuthenticated: true,
            accessToken: data.access_token,
            loading: false,
            error: null,
          });
        } else {
          setState({
            isAuthenticated: false,
            accessToken: null,
            loading: false,
            error: null,
          });
        }
      } catch {
        setState({
          isAuthenticated: false,
          accessToken: null,
          loading: false,
          error: 'Error al verificar estado de auth',
        });
      }
    }
    init();

    // Configurar refresh automático antes de que el token expire
    const refreshInterval = setInterval(() => {
      refreshToken();
    }, 10 * 60 * 1000); // Cada 10 minutos

    return () => clearInterval(refreshInterval);
  }, [refreshToken]);

  return { ...state, login, logout, refreshToken };
}

// Uso en componente
function App() {
  const { isAuthenticated, loading, login, logout } = useAuth();

  if (loading) return <div>Cargando...</div>;
  if (!isAuthenticated) {
    return <button onClick={login}>Iniciar sesión</button>;
  }

  return (
    <div>
      <h1>Dashboard</h1>
      <button onClick={logout}>Cerrar sesión</button>
    </div>
  );
}