Aivorab
Ilustración editorial: OAuth 2.0 y JWT para APIs pequeñas: una guía práctica de seguridad

Seguridad de APIs · OAuth 2.0 · JWT · Autenticación · APIs pequeñas · Desarrollo de APIs

OAuth 2.0 y JWT para APIs pequeñas: una guía práctica de seguridad

Una guía práctica para elegir e implementar autenticación con OAuth 2.0 y JWT en APIs públicas pequeñas: tipos de concesión, gestión del ciclo de vida de tokens y errores comunes de seguridad sin sobreingeniería.

Publicado:

La respuesta corta

OAuth 2.0 es un marco de autorización; JWT es un formato de token. Resuelven problemas diferentes y suelen usarse juntos, no como alternativas. Para una API pública pequeña, utiliza OAuth 2.0 con el flujo de Código de Autorización (más PKCE para clientes públicos) para gestionar la autenticación y el consentimiento, y usa tokens opacos cuando expongas tu API externamente. Reserva los JWT para comunicación interna entre servicios donde necesites claims autocontenidos. Este enfoque mantiene tu modelo de seguridad simple, tus tokens revocables y tu superficie de exposición externa mínima.

Por qué esto importa para equipos pequeños

La mayoría de los desarrolladores independientes y equipos pequeños recurren a los JWT porque son fáciles de implementar y no requieren almacenamiento de sesiones en el servidor. El token es autocontenido: lo decodificas, verificas la firma y sabes quién es el usuario. Esa conveniencia tiene trade-offs reales que se vuelven costosos cuando necesitas revocar acceso, rotar credenciales o proteger datos sensibles del usuario.

OAuth 2.0, en cambio, es deliberadamente más complejo. Separa la autenticación de la autorización, introduce tipos de concesión para diferentes contextos de cliente y te da control sobre el ciclo de vida del token. Para una API pequeña que expone endpoints públicos, la estructura adicional compensa: obtienes flujos estandarizados, evitas filtrar datos de usuario en los tokens y mantienes la capacidad de revocar el acceso sin invalidar todos los tokens emitidos.

Fundamentos de OAuth 2.0: Los cuatro actores

OAuth 2.0 define cuatro roles que se mapean a componentes reales en tu sistema:

Mantener estos roles separados no es académico — es la decisión de diseño más importante que tomarás. Cuando tu servidor de autorización emite tokens y tu servidor de recursos los valida de forma independiente, puedes rotar claves de firma, cambiar formatos de token y actualizar políticas sin tocar los endpoints de API que los consumidores realmente llaman.

Elegir el tipo de concesión correcto

OAuth 2.0 define varios tipos de concesión. Para una API pública pequeña, normalmente solo necesitarás dos:

El flujo de Código de Autorización es el estándar para clientes confidenciales — aplicaciones del lado del servidor que pueden almacenar de forma segura un secreto de cliente. El flujo redirige al usuario al servidor de autorización, donde consiente los alcances solicitados. El servidor emite luego un código de autorización, que tu backend intercambia por un token de acceso. Este es el flujo detrás de “Iniciar sesión con Google” y cada integración OAuth importante.

El flujo de Código de Autorización con PKCE es el equivalente para clientes públicos — aplicaciones de una sola página, apps móviles o cualquier cliente que no pueda almacenar de forma segura un secreto. PKCE (Proof Key for Code Exchange) añade un par code_challenge y code_verifier para prevenir ataques de interceptación del código de autorización. Si tu API tiene un frontend que la llama directamente desde el navegador, usa PKCE. No uses el flujo implícito: está depreciado y es inseguro.

El flujo de Credenciales del Cliente es para comunicación máquina a máquina donde no hay usuario involucrado. Si tu API es llamada por otro servicio usando un ID de cliente estático y un secreto, este es el tipo de concesión apropiado.

JWT vs. tokens opacos: el trade-off real

Aquí es donde la mayoría de los equipos pequeños cometen un error costoso. Los JWT son tokens por valor: el token mismo contiene toda la información necesaria para validarlo. Los tokens opacos son tokens de referencia: el token es una cadena aleatoria que el servidor de recursos debe consultar para determinar qué concede.

Las fuentes del dossier son claras al respecto: cuando los tokens se exponen fuera de tu infraestructura, especialmente a clientes de terceros, debes usar tokens opacos en lugar de JWT. Los datos del JWT son fáciles de decodificar. Base64 no es cifrado. Si pones información de usuario en un token de acceso JWT, cada desarrollador de clientes podrá leerlo. Y lo harán.

Los tokens opacos resuelven este problema. El token no revela nada sobre el usuario. El servidor de recursos lo valida contra el servidor de autorización, y el cliente nunca ve los claims. Este es el enfoque recomendado para APIs públicas.

Usa JWTs internamente — entre tus microservicios, entre tu servidor de autorización y tus servidores de recursos. En ese contexto, la naturaleza autocontenida de los JWT es una ventaja real: los servicios pueden validar tokens sin un round-trip a una base de datos central, lo que mejora el rendimiento y reduce la latencia.

Gestión del ciclo de vida de los tokens

Los tokens tienen una vida útil finita, y gestionar esa vida útil es donde la seguridad vive o muere.

Los tokens de acceso deben tener una vida corta — típicamente minutos, no horas. Una expiración corta limita el daño por robo de token. Si un token de acceso se filtra, el atacante solo tiene una ventana estrecha.

Los tokens de actualización tienen una vida más larga y se usan para obtener nuevos tokens de acceso sin requerir que el usuario se autentique nuevamente. Los tokens de actualización deben almacenarse de forma segura en el lado del cliente y rotarse en cada uso. La rotación significa emitir un nuevo token de actualización junto con el nuevo token de acceso e invalidar el anterior. Esto limita el impacto de un filtrado del token de actualización.

La revocación es el problema más difícil. Con tokens opacos, la revocación es sencilla: elimina el registro del token de tu almacén. Con JWT, la revocación requiere una lista de bloqueo o vidas cortas, porque el token es autocontenido y el servidor de recursos no puede verificar con el emisor en cada solicitud sin derrotar el beneficio de rendimiento.

Para una API pequeña, el enfoque pragmático es: tokens de acceso de vida corta (5–15 minutos), tokens de actualización rotados, y tokens opacos para clientes externos. Esto te da revocabilidad sin la complejidad de una lista de bloqueo JWT.

Errores de seguridad comunes a evitar

Error 1: Almacenar tokens en localStorage. El JavaScript que se ejecuta en el navegador puede leer localStorage. Usa cookies httpOnly o almacenamiento en memoria en su lugar. Esto previene ataques XSS que roban tokens.

Error 2: Poner claims sensibles en JWTs. Los IDs de usuario y roles están bien. Los correos electrónicos, números de teléfono y cualquier PII no deben estar en tokens de acceso. Si necesitas información de identidad, usa un token ID (que es un JWT por especificación) y mantenlo separado del token de acceso.

Error 3: Omitir el parámetro state. El parámetro state en la solicitud de autorización previene ataques CSRF durante el flujo OAuth. Siempre incluye un valor state criptográficamente aleatorio y válidalo en la devolución de llamada.

Error 4: Usar HS256 con un secreto corto. La firma JWT basada en HMAC requiere un secreto que sea al menos tan largo como la salida del hash. Para RS256, usa un par de claves adecuado. Nunca uses un secreto débil o corto para firmar tokens.

Error 5: Emitir tokens desde tu API en lugar de un servidor de autorización centralizado. Las fuentes del dossier recomiendan explícitamente en contra de esto. La emisión de tokens requiere autenticar el cliente, autenticar al usuario, autorizar al cliente y firmar tokens — todas operaciones que requieren acceso a diferentes almacenes de datos. Un servidor de autorización centralizado es el único enfoque seguro.

Un camino de implementación mínimo

Para un equipo pequeño que construye una API pública, esta es la ruta que evita la sobreingeniería mientras mantiene la seguridad:

  1. Usa un servidor de autorización open-source probado (Keycloak, Auth0 o una solución similar). No construyas el tuyo propio.
  2. Configura el flujo de Código de Autorización con PKCE para clientes basados en navegador.
  3. Emite tokens de acceso opacos a clientes externos.
  4. Usa JWTs solo para comunicación interna entre servicios.
  5. Establece la vida del token de acceso en 5–15 minutos.
  6. Implementa rotación de tokens de actualización.
  7. Valida el parámetro state en cada solicitud de autorización.
  8. Coloca tu API detrás de un gateway que maneje limitación de tasa, registro y validación de tokens.

Esta no es la arquitectura más flexible. Es la que mantendrá tu API segura mientras te enfocas en construir funcionalidades. Siempre puedes agregar complejidad después — pero no puedes eliminar fácilmente la deuda de seguridad.

Preguntas frecuentes

P: ¿Puedo usar JWTs para todo y omitir OAuth por completo? R: Puedes, pero perderás el flujo estandarizado de consentimiento, la separación de responsabilidades entre servidores de autorización y servidores de recursos, y la capacidad de usar proveedores de identidad existentes. La autenticación solo con JWT es adecuada para APIs internas privadas donde controlas todos los clientes. Es una mala elección para APIs públicas.

P: ¿Cómo revoco un JWT si ha sido filtrado? R: No puedes revocar un JWT sin una lista de bloqueo o haciéndolo expirar. Este es el trade-off fundamental. Los tokens de vida corta (5–15 minutos) hacen innecesarias las listas de bloqueo en la mayoría de los casos. Si necesitas revocación inmediata, usa tokens opacos.

P: ¿OAuth 2.0 es autenticación o autorización? R: OAuth 2.0 es estrictamente un marco de autorización. Responde “¿qué puede acceder esta aplicación?” no “¿quién es este usuario?”. Si necesitas identificar al usuario, agrega OpenID Connect sobre OAuth 2.0. OIDC proporciona un token ID que lleva información del usuario autenticado.

P: ¿Necesito un gateway de API para una API pequeña? R: No estrictamente, pero las fuentes del dossier lo recomiendan fuertemente. Un gateway centraliza preocupaciones de seguridad — limitación de tasa, registro, validación de tokens y filtrado de solicitudes — para que los endpoints de tu API puedan enfocarse en la lógica de negocio. Para un equipo pequeño, esta separación de responsabilidades vale la pena.

P: ¿Qué hay sobre OAuth 2.1? R: OAuth 2.1 es una simplificación propuesta de OAuth 2.0 que elimina tipos de concesión depreciados, exige PKCE y endurece los requisitos de seguridad. Aún no es un estándar finalizado, pero la dirección es clara: la industria se está moviendo hacia un OAuth más estricto y simple. Construir con las mejores prácticas actuales te posiciona bien para esa transición.

Fuentes