Cómo testear APIs OAuth 2.0 en Apidog (Código de Autorización, Credenciales de Cliente y Refresco de Token)

Cómo probar OAuth 2.0 en APIs con Apidog: PKCE, credenciales de cliente y autoactualización

Todo equipo de API se encuentra con el mismo muro: los endpoints funcionan de forma aislada, pero al activar OAuth 2.0 la mitad de la suite de pruebas empieza a devolver 401. Entre servidores de autorización, tokens de corta duración y ámbitos, copiar tokens desde una respuesta curl hasta un encabezado se vuelve tedioso rápidamente.

Prueba Apidog hoy

La solución no es omitir la autenticación, sino integrarla en la configuración de las pruebas. Esta guía cubre los dos flujos más habituales:

• Código de autorización con PKCE para APIs que actúan en nombre de un usuario.
• Credenciales de cliente para llamadas máquina a máquina.

Si necesitas una visión general, consulta este resumen de flujos de OAuth 2.0.

A continuación configuraremos OAuth 2.0 en Apidog, reutilizaremos tokens entre solicitudes, habilitaremos su actualización automática, heredaremos la autenticación desde una carpeta y probaremos las rutas de fallo.

Los dos flujos importantes para las pruebas de API

OAuth 2.0 define varios tipos de concesión. Para las pruebas diarias, la decisión principal es sencilla:

¿La API actúa en nombre de un usuario o en nombre de un servicio?

Código de autorización con PKCE

El flujo de código de autorización obtiene un token asociado a un usuario:

1. El cliente redirige al usuario al servidor de autorización.
2. El usuario inicia sesión y concede permisos.
3. El servidor redirige al cliente con un código de un solo uso.
4. El cliente intercambia el código por un token de acceso.

El proceso completo está definido en la sección 4.1 de RFC 6749.

PKCE (Proof Key for Code Exchange) protege el intercambio. El cliente genera un verificador aleatorio, envía un desafío derivado de él durante la autorización y demuestra que posee el verificador original al canjear el código. Si un atacante intercepta el código, no podrá utilizarlo.

PKCE nació como solución para aplicaciones móviles, pero la guía actual de oauth.net lo recomienda para todos los intercambios de código de autorización, incluidos los clientes confidenciales.

Utiliza este flujo cuando el resultado dependa de la identidad del usuario, por ejemplo:

• GET /orders devuelve solo los pedidos del usuario actual.
• Los endpoints administrativos dependen del rol.
• Los límites de tasa se aplican por usuario.

Credenciales de cliente

La concesión de credenciales de cliente elimina por completo la interacción del usuario. El cliente se autentica con su propia ID y secreto, y recibe un token que representa a la aplicación.

Es una única solicitud al endpoint de tokens, sin navegador ni redirección:

curl -X POST https://auth.example.com/oauth/token \
  -d grant_type=client_credentials \
  -d client_id=orders_service \
  -d client_secret=s3cr3t_value \
  -d scope="orders:read orders:write"

Este flujo es adecuado para:

• Microservicios internos.
• Tareas cron.
• Pipelines de CI que llaman a una API de despliegue.
• Suites automatizadas que no necesitan intervención humana.

Si tu entorno permite aprovisionar un cliente de prueba, usa credenciales de cliente para la mayoría de las pruebas. Reserva el flujo de usuario para los casos en los que la identidad sea precisamente lo que quieres validar. Consulta la documentación de credenciales de cliente de OAuth 2.0 para conocer los detalles de la concesión.

Configurar OAuth 2.0 en Apidog

Apidog trata OAuth 2.0 como un tipo de autenticación integrado. Puedes configurarlo en la pestaña Auth de una solicitud o carpeta; la plataforma obtiene, adjunta y actualiza los tokens.

Los tipos de concesión disponibles incluyen:

• Código de autorización.
• Código de autorización con PKCE.
• Credenciales de cliente.
• Credenciales de contraseña.
• Implícito.

En los nuevos planes de prueba, evita las concesiones implícita y de contraseña, ya que están desaconsejadas en la guía actual de OAuth.

Los siguientes ejemplos utilizan una API ficticia de gestión de pedidos.

Configurar credenciales de cliente

Abre una solicitud o, preferiblemente, la carpeta que la contiene. Cambia el tipo de autenticación a OAuth 2.0 y selecciona Credenciales de cliente.

Completa estos campos:

• URL del token de acceso: https://auth.example.com/oauth/token
• ID de cliente: orders_service
• Secreto de cliente: el secreto aprovisionado
• Ámbito (scope): orders:read orders:write, en las opciones avanzadas

Apidog permite enviar las credenciales de dos formas:

• Como encabezado de autenticación básica (Basic Auth).
• En el cuerpo de la solicitud.

Elige la opción que espera tu servidor de autorización. Auth0 y Okta aceptan ambas, aunque algunos servidores internos solo analizan las credenciales del cuerpo.

Haz clic en Obtener Token. Apidog llamará al endpoint de tokens, almacenará la respuesta y mostrará el token junto con su período de validez. Después, cada solicitud lo enviará automáticamente en el encabezado:

[REDACTED CREDENTIAL] <access_token>

No tendrás que copiar y pegar tokens ni mantener manualmente variables como {{token}}.

Configurar código de autorización con PKCE

Para probar operaciones en contexto de usuario, selecciona Código de autorización con PKCE. En Apidog, PKCE es un tipo de concesión independiente, no una casilla adicional.

Necesitarás estos valores:

• URL de autorización: https://auth.example.com/oauth/authorize
• URL del token de acceso: https://auth.example.com/oauth/token
• URL de retorno (callback): la URI registrada con tu proveedor
• ID y secreto de cliente: los datos de tu aplicación OAuth

Haz clic en Obtener Token. Apidog abrirá una ventana del navegador hacia la pantalla de inicio de sesión. Inicia sesión con el usuario de prueba, aprueba el consentimiento y el token regresará al espacio administrado por Apidog.

Si tu proveedor devuelve un token de ID de OpenID Connect junto con el token de acceso, la opción Tipo de token usado permite elegir cuál se adjunta. Esto resulta útil cuando la API valida tokens de ID.

Consejo para las pruebas basadas en roles

Mantén un usuario de prueba por cada rol relevante:

• Comprador.
• Administrador.
• Auditor de solo lectura.

Obtén un token para cada usuario y ejecuta el mismo escenario. Es una forma rápida de verificar las reglas de acceso basadas en roles.

Reutilizar tokens y actualizar tokens caducados

Los tokens de acceso suelen caducar al cabo de una hora. Un token caducado no debería convertirse en un fallo intermitente que el equipo termine ignorando.

Cuando el servidor de autorización emite un token de actualización, Apidog puede renovar automáticamente el token de acceso. Al detectar que el token almacenado ha caducado, Apidog utiliza el token de actualización, obtiene uno nuevo y lo intercambia antes de enviar la solicitud.

Esta capacidad se incorporó en la actualización de junio. Si tu proveedor utiliza un endpoint independiente, puedes especificar una URL personalizada para el token de actualización en la configuración avanzada.

En el flujo de credenciales de cliente, muchos servidores no emiten tokens de actualización. La especificación lo permite porque el cliente puede autenticarse de nuevo en cualquier momento.

En ese caso:

• Haz clic en Obtener Token para emitir otro token.
• En ejecuciones programadas o de CI, solicita un token nuevo al comienzo de cada ejecución.

Heredar la autenticación desde una carpeta

Configurar OAuth 2.0 solicitud por solicitud genera duplicación y facilita los errores. Apidog permite definir la autenticación en una carpeta para que las solicitudes internas hereden automáticamente la configuración.

Por ejemplo, configura OAuth 2.0 una sola vez en la carpeta API de Pedidos. Todas las solicitudes actuales y futuras utilizarán el mismo token administrado:

API de Pedidos/
├── POST /carts
├── POST /carts/{id}/items
└── POST /orders

Esto es especialmente útil en escenarios de varios pasos. Los tres endpoints compartirán la configuración y el token. Si el token caduca durante el escenario, la actualización automática se encargará de renovarlo.

También puedes rotar el secreto del cliente desde un único lugar, en vez de modificar decenas de solicitudes.

Las solicitudes individuales pueden anular la autenticación heredada. Esa capacidad es esencial para las pruebas negativas.

Probar las rutas de fallo

Las pruebas de ruta feliz verifican que el flujo de tokens funciona. Las pruebas de fallo confirman que la API aplica correctamente la autenticación y la autorización.

Para revisar las diferencias entre mecanismos de autenticación, consulta esta comparación de claves de API y tokens bearer.

Token caducado o ausente: esperar 401

Duplica una solicitud y anula la autenticación heredada. Puedes usar ninguna autenticación o un token Bearer [REDACTED]:

[REDACTED CREDENTIAL] [REDACTED]

Comprueba que:

• El código de estado sea 401.
• El encabezado de respuesta WWW-Authenticate esté presente, como espera RFC 6750.
• El cuerpo no revele trazas de pila ni nombres de host internos.

Un 200 representa un error crítico. Un 403 también indica un problema de diseño: el servidor debe distinguir entre «no sé quién eres» y «sé quién eres, pero no tienes permiso».

Ámbito incorrecto: esperar 403

Aprovisiona un segundo cliente de prueba limitado a orders:read. Obtén su token y llama a un endpoint de escritura, como POST /orders.

Comprueba que:

• El código de estado sea 403.
• El encabezado WWW-Authenticate incluya error="insufficient_scope" si la API sigue RFC 6750.

Esta prueba detecta configuraciones inconsistentes en las que el gateway verifica ámbitos para algunas rutas, pero los omite en otras. Si necesitas revisar cómo dividir permisos, consulta Ámbitos de OAuth 2.0 explicados.

Cliente inválido: validar el error del endpoint de tokens

Envía una solicitud directamente a:

https://auth.example.com/oauth/token

Usa un client_secret falso. Según la sección 5.2 de RFC 6749, el servidor debería responder con:

• 400, o 401 si falla la autenticación del cliente.
• Un cuerpo JSON que contenga "error": "invalid_client".

Los servidores de autorización también son APIs. Su contrato de errores forma parte de la superficie que debes probar.

Validar respuestas de tokens

El endpoint de tokens merece cobertura propia, además del caso de cliente inválido. Añade un paso que lo llame directamente y valida la respuesta JSON:

• access_token existe y no está vacío.
• token_type es bearer, sin distinguir mayúsculas y minúsculas.
• expires_in es mayor que 0 y respeta tu política, por ejemplo, no más de 3600.
• scope coincide con el valor solicitado, para detectar servidores que reducen silenciosamente las concesiones.

Los escenarios de prueba de Apidog permiten añadir estas afirmaciones visualmente, sin scripting. También puedes extraer access_token a una variable para un paso posterior si quieres probar el intercambio puro en lugar de utilizar la autenticación administrada.

Conecta el escenario a CI. Así, un servidor de autorización que incumpla el contrato hará fallar la compilación en lugar de manifestarse como un 401 misterioso en producción.

El ciclo completo queda así:

1. Configura OAuth 2.0 a nivel de carpeta para la ruta feliz.
2. Anula la autenticación por solicitud para probar 401 y 403.
3. Prueba directamente el contrato del endpoint de tokens.
4. Ejecuta todo el escenario en CI.
5. Usa PKCE para APIs en contexto de usuario y credenciales de cliente para APIs servicio a servicio.

Puedes descargar Apidog y probarlo gratis. La autenticación OAuth 2.0 está disponible en el plan gratuito, por lo que puedes conectarla a tu propio endpoint de tokens en pocos minutos.

Preguntas frecuentes

¿Qué flujo de OAuth debo usar para las pruebas de API?

Usa credenciales de cliente para llamadas máquina a máquina y para la mayoría de las suites automatizadas, porque no requieren interacción con el navegador.

Usa código de autorización con PKCE cuando la prueba dependa de la identidad del usuario, por ejemplo:

• Aislamiento de datos por usuario.
• Verificaciones de roles.
• Comportamiento del consentimiento.

Evita las concesiones implícita y de contraseña en nuevos planes de prueba.

¿Cómo actualizo automáticamente un token caducado en Apidog?

Configura OAuth 2.0 en la pestaña Auth y obtén un token con Obtener Token. Si el servidor de autorización devuelve un token de actualización, Apidog renovará el token de acceso cuando caduque.

Si tu proveedor utiliza un endpoint separado, establece su URL en las opciones avanzadas. En configuraciones de credenciales de cliente sin tokens de actualización, vuelve a ejecutar Obtener Token para emitir uno nuevo.

¿Puede cada solicitud de un escenario compartir un token de OAuth?

Sí. Configura OAuth 2.0 en la carpeta padre y las solicitudes internas heredarán la configuración. De esta forma, un escenario de varios pasos puede ejecutarse con un único token administrado.

Las solicitudes individuales aún pueden anular la configuración de la carpeta. Utiliza esa opción para probar tokens caducados, ámbitos incorrectos y otros casos negativos.

¿Qué diferencia hay entre 401 y 403 en una API protegida por OAuth?

Devuelve 401 cuando falla la autenticación: el token falta, caducó o está mal formado.

Devuelve 403 cuando el token es válido, pero no tiene permisos suficientes, por ejemplo, porque le falta un ámbito.

Confundir ambos códigos rompe la lógica de reintento del cliente:

• 401 indica que el cliente debe autenticarse de nuevo.
• 403 indica que debe detenerse porque no tiene autorización.

Para profundizar en la validación del token, consulta la guía para probar la autenticación JWT.