Todo equipo de API se encuentra con el mismo muro. Los endpoints funcionan de forma aislada, luego alguien activa OAuth 2.0 y la mitad de la suite de pruebas empieza a devolver 401. De repente, estás haciendo malabares con servidores de autorización, tokens de acceso de corta duración y ámbitos, y copiar tokens a mano de una respuesta curl a un campo de encabezado se vuelve tedioso a la tercera ejecución.
La solución no es omitir la autenticación en tus pruebas. Es hacer que el manejo de tokens sea parte de la configuración de la prueba para que deje de ser un trabajo manual. Esta guía cubre los dos flujos que encontrarás en casi todos los planes de prueba: el flujo de código de autorización OAuth (con PKCE) para APIs que actúan en nombre de un usuario, y el flujo de credenciales de cliente para llamadas máquina a máquina. Si primero quieres el mapa completo de concesiones, nuestro resumen de flujos de OAuth 2.0 los explica todos.
Luego pasamos a la práctica: configurar la autenticación OAuth 2.0 en Apidog, obtener un token una vez y reutilizarlo en varias solicitudes, permitir que los tokens caducados se actualicen por sí solos, heredar la autenticación a nivel de carpeta y probar las rutas de fallo sobre las que tu revisión de seguridad preguntará.
Los dos flujos importantes para las pruebas de API
OAuth 2.0 define varios tipos de concesión, pero para las pruebas de API diarias, pasarás la mayor parte de tu tiempo con dos de ellos. Elige basándote en una pregunta: ¿la API actúa en nombre de un usuario o en nombre de un servicio?
Flujo de código de autorización, con PKCE
El flujo de código de autorización es la forma estándar de obtener un token vinculado a un usuario. El cliente envía al usuario al servidor de autorización, el usuario inicia sesión y da su consentimiento, el servidor redirige con un código de un solo uso, y el cliente intercambia el código por un token de acceso en el endpoint de tokens. RFC 6749 define todo el proceso en la sección 4.1.
PKCE (Proof Key for Code Exchange, RFC 7636) endurece el intercambio. El cliente genera un verificador aleatorio, envía un desafío hash con la solicitud de autorización y luego demuestra que posee el verificador original al canjear el código. Un atacante que intercepte el código no puede usarlo. PKCE comenzó como una solución para aplicaciones móviles, pero la guía actual de oauth.net lo recomienda para cada intercambio de código de autorización, incluidos los clientes confidenciales.
Prueba con este flujo siempre que el comportamiento del endpoint dependa de quién es el usuario: GET /orders devolviendo solo los pedidos del llamador, endpoints de administración restringidos por rol, límites de tasa por usuario.
Flujo de credenciales de cliente
La concesión de credenciales de cliente de OAuth 2.0 omite por completo al usuario. El cliente se autentica con su propia ID y secreto y recibe un token que representa a la propia aplicación. Una única solicitud POST al endpoint de tokens, sin navegador, sin 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 es el flujo para APIs máquina a máquina: microservicios internos, tareas cron, pipelines de CI que llaman a una API de despliegue. También es la pieza clave de las pruebas automatizadas, porque no necesita intervención humana. Si tu entorno de prueba te permite aprovisionar un cliente de prueba, utiliza credenciales de cliente para todo, excepto en los casos en que la identidad del usuario sea lo que se está probando.
Configuración de la autenticación OAuth 2.0 en Apidog
Apidog trata OAuth 2.0 como un tipo de autenticación de primera clase. Lo configuras una vez, en la pestaña Auth de una solicitud o carpeta, y la plataforma se encarga de obtener, adjuntar y refrescar los tokens. Los tipos de concesión admitidos incluyen Código de Autorización, Código de Autorización (con PKCE), Credenciales de Cliente, Credenciales de Contraseña e Implícito.
Aquí está la configuración para los dos flujos anteriores, utilizando una API ficticia de gestión de pedidos.
Configuración de credenciales de cliente
Abre la solicitud (o mejor, la carpeta; más sobre esto abajo), cambia el tipo de autenticación a OAuth 2.0 y elige Credenciales de Cliente como tipo de concesión. Rellena:
- URL del Token de Acceso:
https://auth.example.com/oauth/token - ID de Cliente:
orders_service - Secreto de Cliente: tu secreto provisionado
- Ámbito (Scope):
orders:read orders:write(configurado en las opciones avanzadas)
Apidog te ofrece dos formas de entregar las credenciales: como encabezado de autenticación básica (Basic Auth) o en el cuerpo de la solicitud. Adapta esto a lo que tu servidor de autorización espere; Auth0 y Okta aceptan ambos, pero algunos servidores internos solo analizan el cuerpo.
Haz clic en Obtener Token. Apidog llama al endpoint de tokens, almacena el resultado y muestra el token junto con su período de validez. A partir de entonces, cada envío lo adjunta al encabezado Authorization con el prefijo Bearer. Sin copiar y pegar, sin el manejo de variables {{token}}.
Configuración de código de autorización con PKCE
Para pruebas en contexto de usuario, elige Código de Autorización (con PKCE) como tipo de concesión. PKCE es su propia opción de concesión en Apidog, no una casilla de verificación. Necesitarás algunos campos más:
- 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 de redirección registrada con tu proveedor
- ID de Cliente y Secreto de Cliente: de tu registro de aplicación OAuth
Haz clic en Obtener Token y Apidog abrirá una ventana del navegador apuntando a la página de inicio de sesión. Inicia sesión como tu usuario de prueba, aprueba la pantalla de consentimiento y el token regresará y se ubicará en el mismo espacio administrado que antes. Si tu proveedor devuelve un token de ID de OpenID Connect junto con el token de acceso, una opción de Tipo de Token Usado te permite cambiar cuál se adjunta; útil cuando la API bajo prueba valida tokens de ID.
Un consejo práctico: mantén un usuario de prueba dedicado por cada rol que necesites cubrir (comprador, administrador, auditor de solo lectura). Obtener un token como cada usuario y volver a ejecutar el mismo escenario es la forma más rápida de verificar las reglas de acceso basadas en roles.
Reutilización de tokens y auto-actualización
Los tokens de acceso caducan, generalmente en una hora. Antes de que Apidog gestionara esto, un token caducado significaba una ejecución fallida y una recuperación manual, que es exactamente el tipo de fallo intermitente que los equipos aprenden a ignorar.
Ahora Apidog actualiza los tokens OAuth 2.0 por sí mismo cuando el servidor de autorización emite un token de actualización, una capacidad que se lanzó en la actualización de junio. Cuando el token de acceso almacenado caduca, Apidog utiliza el token de actualización para obtener uno nuevo y lo intercambia antes de enviar. También puedes apuntarlo a una URL de token de actualización personalizada en la configuración avanzada si tu proveedor separa los dos endpoints.
Para las credenciales de cliente, muchos servidores omiten los tokens de actualización por completo (la especificación lo permite, ya que el cliente puede volver a autenticarse en cualquier momento). En la práctica, esto no es un problema: volver a obtener un token con Obtener Token es un solo clic, y las ejecuciones programadas o de CI pueden solicitar un token nuevo al comienzo de cada ejecución.
Heredar autenticación a nivel de carpeta
Configurar OAuth en cada solicitud es la aproximación incorrecta. Apidog te permite establecer la autenticación en una carpeta, y las solicitudes dentro de ella heredan la configuración de su padre. Configura OAuth 2.0 una vez en tu carpeta de "API de Pedidos" y cada solicitud debajo de ella, incluyendo las nuevas que tus compañeros de equipo añadan en el próximo sprint, enviará el mismo token gestionado.
Esto es especialmente importante en escenarios de prueba de varios pasos. Un escenario de compra podría encadenar POST /carts, POST /carts/{id}/items y POST /orders. Con la autenticación a nivel de carpeta, los tres pasos comparten un token y una configuración. Cuando el token caduca a mitad del escenario, la auto-actualización lo cubre. Y cuando tu equipo de seguridad rota el secreto del cliente, actualizas una carpeta en lugar de cuarenta solicitudes.
Las solicitudes mantienen la opción de anular la configuración del padre, que es exactamente lo que quieres para pruebas negativas. Más sobre eso ahora.
Probando las rutas de fallo
Las pruebas de "ruta feliz" de OAuth demuestran que tu canalización de tokens funciona. Las pruebas de "ruta de fallo" demuestran que tu API aplica la autenticación. Si las omites, estás confiando en los valores predeterminados del framework. Aquí están los tres casos que vale la pena automatizar; para un repaso sobre lo que debería significar cada código de estado, consulta nuestra comparación de claves de API y tokens bearer.
Token caducado o faltante: esperar 401
Duplica una solicitud en tu escenario y anula su autenticación heredada con ninguna autenticación o con un token bearer codificado y ya caducado, como Bearer expired_token_do_not_rotate. Afirma sobre:
- El código de estado es igual a
401 - El encabezado de respuesta
WWW-Authenticateestá presente (el compañero de RFC 6749, RFC 6750, lo espera) - El cuerpo no filtra rastros de pila o nombres de host internos
Un 200 aquí es un error crítico. Un 403 es un "mal olor de diseño" que merece un ticket: el servidor debería distinguir entre "No sé quién eres" y "Te conozco, y no".
Ámbito incorrecto: esperar 403
Provee un segundo cliente de prueba limitado a orders:read, obtén su token y llama a un endpoint de escritura como POST /orders. Afirma que el estado es 403 y, si tu API sigue RFC 6750, el encabezado WWW-Authenticate incluye error="insufficient_scope". Esta prueba detecta la clásica mala configuración donde los ámbitos se verifican en el gateway para algunas rutas y se olvidan en otras. Si los ámbitos son nuevos para tu equipo, ámbitos de OAuth 2.0 explicados cubre cómo dividirlos.
Cliente inválido: esperar un error limpio del endpoint de tokens
Dirige una solicitud directamente a https://auth.example.com/oauth/token con un client_secret falso. Según la sección 5.2 de RFC 6749, el servidor debería devolver 400 (o 401 para autenticación de cliente fallida) con un cuerpo JSON que contenga "error": "invalid_client". Afirma ambos. Los servidores de autorización también son APIs, y su contrato de errores es parte de tu superficie.
Afirmando sobre las respuestas de tokens en escenarios de prueba
El endpoint de tokens merece su propia cobertura más allá del caso de cliente inválido. Agrega un paso en tu escenario de prueba llamando directamente al endpoint de tokens y luego adjunta afirmaciones sobre la respuesta:
access_tokenexiste y no está vacíotoken_typees igual abearer(sin distinción de mayúsculas y minúsculas según la especificación)expires_ines mayor que 0 y dentro de tu política, digamos no más de 3600scopecoincide con lo solicitado, detectando servidores que reducen silenciosamente las concesiones
Los escenarios de prueba de Apidog te permiten añadir estas afirmaciones visualmente en la respuesta JSON, sin necesidad de scripting, y puedes extraer access_token en una variable para un paso posterior cuando quieras probar el handshake puro en lugar de usar la autenticación gestionada. Conecta el escenario a tu ejecución de CI y un servidor de autorización que no se comporta correctamente hará que la compilación falle en lugar de aparecer como un misterioso 401 en producción.
El ciclo completo se ve así: configuración de OAuth 2.0 a nivel de carpeta para la "ruta feliz", anulaciones por solicitud para los casos 401 y 403, y un escenario que prueba el contrato del endpoint de tokens. Esto cubre APIs en contexto de usuario a través del código de autorización con PKCE y APIs de servicio a servicio a través de credenciales de cliente, con la actualización de tokens gestionada por ti. Descarga Apidog y pruébalo gratis; el tipo de autenticación OAuth 2.0 funciona en el plan gratuito, así que puedes apuntarlo 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 cualquier cosa máquina a máquina y para la mayoría de las suites automatizadas, ya que no necesita interacción del navegador. Usa el flujo de código de autorización con PKCE cuando la prueba dependa de la identidad del usuario: aislamiento de datos por usuario, verificaciones de rol o comportamiento de consentimiento. Evita las concesiones implícitas y de contraseña en los nuevos planes de prueba; ambas están desaconsejadas en la guía actual de OAuth.
¿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. Cuando el servidor de autorización devuelve un token de actualización, Apidog actualiza el token de acceso al expirar sin que necesites volver a autenticarte, y puedes establecer una URL de token de actualización separada en la configuración avanzada si tu proveedor utiliza una. Para configuraciones de credenciales de cliente sin tokens de actualización, volver a ejecutar Obtener Token emitirá uno nuevo.
¿Puede cada solicitud en un escenario compartir un token de OAuth?
Sí. Configura OAuth 2.0 en la carpeta padre y las solicitudes internas lo heredarán, de modo que un escenario de varios pasos se ejecuta bajo un único token gestionado. Las solicitudes individuales aún pueden anular la configuración de la carpeta, que es cómo insertas pruebas negativas (token caducado, ámbito incorrecto) en el mismo escenario.
¿Qué deberían significar un 401 versus un 403 en las APIs protegidas por OAuth?
Devuelve 401 cuando la autenticación falló: el token está ausente, caducado o mal formado. Devuelve 403 cuando el token es válido pero carece de permisos, como un ámbito faltante. Confundirlos rompe la lógica de reintento del cliente, porque un 401 le dice al cliente que se vuelva a autenticar, mientras que un 403 le dice que se detenga. Nuestra guía para probar la autenticación JWT profundiza en la validación del token en sí.