Cómo funciona la autenticación OAuth en APIs web

Si has empezado a investigar cómo conectar tu web con servicios externos —un CRM, una plataforma de pagos, redes sociales o cualquier herramienta de terceros— probablemente ya te has topado con el término autenticación OAuth en APIs. Y si no tienes un perfil técnico, puede que te hayas perdido entre conceptos como «tokens», «scopes» o «flujos de autorización». Este artículo explica cómo funciona OAuth de manera real y práctica, sin rodeos, para que puedas tomar decisiones informadas antes de integrarlo en tu proyecto.

Qué es OAuth y por qué existe

OAuth (Open Authorization) es un protocolo de autorización estándar que permite que una aplicación acceda a recursos de otra en nombre de un usuario, sin que ese usuario tenga que compartir su contraseña. Suena simple, pero resuelve un problema enorme: antes de que existiera OAuth, muchas integraciones pedían literalmente las credenciales del usuario para actuar en su nombre. Un riesgo de seguridad enorme.

El ejemplo más cotidiano: cuando entras en una web nueva y ves el botón «Continuar con Google» o «Conectar con Spotify», eso es OAuth en acción. La web no recibe tu contraseña de Google. Recibe un token de acceso limitado que le dice que eres tú y qué puede hacer con tu cuenta.

La versión actual del protocolo es OAuth 2.0, publicada en 2012 y hoy el estándar de facto para la mayoría de las APIs públicas modernas. OAuth 1.0 existe pero está en desuso salvo en plataformas muy antiguas.

Los cuatro actores del protocolo OAuth

Para entender cómo funciona OAuth, conviene tener claros los cuatro participantes de cualquier flujo:

• Resource Owner (usuario): la persona que posee los datos y da el consentimiento.
• Client (tu aplicación): el software que quiere acceder a esos datos.
• Authorization Server: el servidor que verifica la identidad y emite los tokens (generalmente el proveedor: Google, Facebook, GitHub…).
• Resource Server: el servidor que contiene los datos protegidos (puede ser el mismo que el anterior o uno separado).

Cuando tu web quiere conectarse con, por ejemplo, la API de Google Calendar, tu web es el client, Google actúa como Authorization Server y Resource Server, y el usuario que autoriza la conexión es el Resource Owner. El flujo siempre pasa por estos cuatro actores, aunque en implementaciones simples algunos roles se solapan.

Los flujos de autorización: cuál aplica a cada caso

OAuth 2.0 no es un flujo único. Define varios grant types (o flujos) según el tipo de aplicación y el contexto. Elegir el flujo equivocado es uno de los errores más frecuentes al implementar integraciones.

Authorization Code Flow

Es el flujo más seguro y el más habitual para aplicaciones web con servidor backend. El proceso es:

1. El usuario hace clic en «Conectar con X».
2. Tu app redirige al Authorization Server con un parámetro de estado y los scopes solicitados.
3. El usuario aprueba el acceso.
4. El Authorization Server devuelve un código de autorización (no el token aún) a tu backend.
5. Tu backend intercambia ese código por un access token y, si aplica, un refresh token.

La ventaja clave: el token nunca viaja por el navegador del usuario. Siempre se gestiona en el servidor. Esto lo hace robusto frente a ataques de intercepción.

PKCE (Proof Key for Code Exchange)

Es una extensión del Authorization Code Flow diseñada para aplicaciones móviles y SPAs (Single Page Applications) donde no hay un backend seguro. Añade un code verifier y un code challenge que dificultan que un tercero pueda interceptar el código de autorización y canjearlo. Si estás desarrollando una app React o Vue que consume APIs directamente, PKCE es hoy el estándar recomendado por el IETF.

Client Credentials Flow

Este flujo no implica al usuario final. Es para comunicaciones máquina a máquina: tu servidor backend necesita acceder a una API de terceros sin que haya un usuario detrás. Se autentica usando el client_id y el client_secret de tu aplicación directamente, y recibe un token de acceso con el que opera.

Casos de uso típicos: sincronización automática de inventario, generación de reportes programados, integraciones de notificaciones entre sistemas. Si estás automatizando procesos internos con APIs, probablemente este sea tu flujo.

Implicit Flow (obsoleto)

Conviene mencionarlo porque todavía aparece en documentación antigua. El Implicit Flow devolvía el token directamente en la URL del navegador, lo que lo hacía vulnerable. Desde 2019 se considera obsoleto en OAuth 2.0 y la recomendación oficial es reemplazarlo por Authorization Code + PKCE en todos los casos.

Qué son los tokens y cómo funcionan en la práctica

Un access token es una cadena de texto (frecuentemente en formato JWT) que tu aplicación incluye en cada petición a la API como prueba de autorización. El Resource Server valida ese token y, si es válido, responde con los datos solicitados.

Los access tokens tienen una vida útil corta (típicamente entre 15 minutos y 1 hora) para minimizar el daño si son comprometidos. Aquí entra el refresh token: un token de larga duración (días, semanas) que tu app puede usar para obtener un nuevo access token sin pedirle al usuario que vuelva a autorizar. El flujo es silencioso para el usuario, pero técnicamente requiere que tu backend gestione correctamente el almacenamiento seguro del refresh token.

Un error habitual: guardar tokens en localStorage del navegador. Es accesible desde JavaScript y, por tanto, vulnerable a ataques XSS. La práctica recomendada para tokens sensibles es almacenarlos en cookies httpOnly con flag Secure, inaccesibles desde el código JavaScript del cliente.

Scopes: definir exactamente qué acceso se solicita

Los scopes son permisos granulares que tu aplicación declara necesitar. En lugar de pedir acceso completo a la cuenta de un usuario, especificas exactamente qué necesitas: leer correos, escribir en el calendario, acceder al perfil público, etc.

Desde la perspectiva del usuario, los scopes son lo que aparece en la pantalla de consentimiento («Esta aplicación quiere acceder a: tus contactos, tu calendario de trabajo»). Desde la perspectiva del desarrollador, los scopes determinan qué endpoints de la API podrás usar con ese token.

El principio de mínimo privilegio aplica aquí con fuerza: solicita solo los scopes que realmente necesitas. Pedir más de lo necesario genera desconfianza en el usuario y aumenta el riesgo si el token es comprometido. Algunas APIs además limitan ciertos scopes a aplicaciones que hayan pasado una verificación de seguridad adicional (por ejemplo, la API de Gmail para acceso a correos completos).

Diferencias entre autenticación y autorización: el matiz que confunde

OAuth es un protocolo de autorización, no de autenticación. Esta distinción es técnicamente importante aunque a menudo se mezcla en la práctica. OAuth responde a «¿qué puede hacer esta aplicación?», no a «¿quién es este usuario?».

Para autenticación de usuarios (saber quién es alguien), el estándar complementario es OpenID Connect (OIDC), que construye sobre OAuth 2.0 añadiendo un ID token con información verificable del usuario. Cuando una web usa «Iniciar sesión con Google», técnicamente está usando OIDC (que a su vez usa OAuth 2.0 por debajo). Si solo necesitas identificar al usuario en tu sistema, OIDC es el protocolo correcto; si necesitas que tu app opere en nombre del usuario en un servicio de terceros, usas OAuth directamente.

Consideraciones reales antes de implementar OAuth

Conocer el protocolo es el primer paso, pero antes de implementarlo hay decisiones prácticas que afectan directamente al tiempo de desarrollo y a la seguridad del resultado.

¿Usas una librería o construyes desde cero?

Implementar OAuth manualmente es posible, pero innecesariamente arriesgado. Existen librerías bien mantenidas para cada ecosistema: Passport.js para Node, league/oauth2-client para PHP, django-allauth para Django… En WordPress, plugins como WP OAuth Server o el uso de la API de aplicaciones de WordPress ya cubren muchos casos de uso. La regla general: si el proveedor que necesitas tiene una librería oficial, úsala. El tiempo que ahorras en gestionar edge cases vale más que la flexibilidad de hacerlo a mano.

Registro de tu aplicación en el proveedor

Antes de llamar a ninguna API con OAuth, necesitas registrar tu aplicación en el portal de desarrolladores del proveedor (Google Cloud Console, Facebook Developers, GitHub OAuth Apps…). Allí obtienes el client_id y el client_secret, y configuras las redirect URIs autorizadas. Una redirect URI incorrecta o no registrada es la causa más común de errores en la fase inicial de integración.

Gestión del estado y protección CSRF

El parámetro state en el flujo de autorización no es opcional aunque técnicamente lo parezca. Su función es prevenir ataques CSRF (Cross-Site Request Forgery) durante el flujo OAuth. Genera un valor aleatorio por sesión, inclúyelo en la petición de autorización y verifícalo cuando el proveedor redirija de vuelta a tu app. Si el state no coincide, rechaza el flujo. Es un detalle pequeño que tiene consecuencias de seguridad reales.

Qué pasa cuando caduca el token

Un sistema que no gestiona correctamente la caducidad de tokens produce errores silenciosos que solo se detectan cuando el usuario ya ha tenido una mala experiencia. Implementa lógica de refresco proactiva: antes de hacer una petición crítica, comprueba si el token está próximo a expirar y renuévalo. No esperes al error 401 del servidor para reaccionar.

OAuth en el contexto de integraciones para empresas

En proyectos web empresariales —ya sea una web corporativa que conecta con Salesforce, un e-commerce que se integra con plataformas logísticas o una intranet que sincroniza con Microsoft 365—, OAuth aparece casi siempre como la capa de acceso seguro. Su adopción universal entre las APIs modernas hace que entenderlo bien no sea opcional si gestionas integraciones de cierta complejidad.

Un aspecto que con frecuencia se pasa por alto en proyectos con múltiples integraciones: la gestión centralizada de tokens. Si tu sistema conecta con cinco servicios distintos via OAuth, necesitas un mecanismo claro para almacenar, refrescar y revocar esos tokens de forma segura y auditable. Delegar esa responsabilidad en cada integración de forma independiente genera deuda técnica que se acumula rápidamente.

Si estás en ese punto de evaluación —decidiendo cómo estructurar las integraciones de tu proyecto—, en Rayo Web podemos ayudarte a definir la arquitectura adecuada antes de escribir una sola línea de código.

Errores frecuentes que conviene conocer de antemano

Más allá de los ya mencionados (tokens en localStorage, no validar state, no manejar la caducidad), hay algunos patrones de error recurrentes en implementaciones OAuth:

• Client secret expuesto en frontend: el client_secret nunca debe estar en código JavaScript del cliente ni en un repositorio público. Pertenece exclusivamente al backend.
• Redirect URIs demasiado amplias: configurar wildcards en las redirect URIs autorizadas (si el proveedor lo permite) amplía innecesariamente la superficie de ataque.
• No implementar revocación de tokens: cuando un usuario desconecta tu app, debes llamar al endpoint de revocación del proveedor, no solo eliminar el token de tu base de datos local.
• Ignorar los refresh tokens expirados: los refresh tokens también expiran o pueden ser revocados por el proveedor. Tu lógica debe manejar ese escenario pidiendo al usuario que autorice de nuevo, en lugar de fallar silenciosamente.

Ninguno de estos errores es raro ni académico. Aparecen en proyectos reales con cierta regularidad, especialmente cuando la implementación la hace alguien que entiende el protocolo a nivel superficial pero no ha trabajado con sus detalles en producción.

Recursos y estándares de referencia

Si quieres profundizar más allá de este artículo, la fuente canónica es la documentación oficial del OAuth 2.0 en oauth.net, que mantiene las especificaciones actualizadas y referencias a las extensiones más recientes como PKCE, PAR (Pushed Authorization Requests) y OAuth 2.1, que consolidará las mejores prácticas de seguridad en una nueva versión del estándar.

Para el día a día, los portales de desarrolladores de los principales proveedores (Google, Microsoft, GitHub, Stripe) tienen documentación de flujos específica que suele ser más práctica que la especificación base. Leer la documentación del proveedor concreto con el que vas a trabajar siempre tiene prioridad sobre el estándar genérico, porque cada implementación tiene sus peculiaridades.