Unirme a la lista
Todos los artículos
OAuthlocal developmentauthenticationcallbacks

Cómo probar callbacks de OAuth en local

Para probar callbacks de OAuth en local, necesitas una URL HTTPS pública que apunte a tu app local. Los proveedores de OAuth redirigen al usuario de vuelta a una URL de callback registrada tras la autenticación, y la mayoría exige HTTPS, algo que localhost a secas no puede ofrecer sin configuración adicional.

Por qué los redirect URIs de OAuth bloquean localhost

Los proveedores de OAuth 2.0 validan el parámetro redirect_uri contra una lista blanca de URLs registradas. Durante el desarrollo, tu callback podría verse así:

https://your-app.portpreview.dev/auth/callback

Sin un túnel, o bien registras http://localhost:3000/auth/callback (que algunos proveedores permiten, pero no todos) o despliegas a staging por cada cambio de auth. Un túnel a localhost te da un endpoint HTTPS real en tu máquina.

Qué necesitas para probar OAuth en local

  • Credenciales de la app OAuth (client ID y secret) de tu proveedor.
  • Una app local con rutas de auth para iniciar el login y manejar el callback.
  • Una URL de túnel registrada como redirect URI permitido en el panel del proveedor.
  • Variables de entorno que apunten a la URL del túnel durante el desarrollo.

Paso a paso: probar OAuth en local con PortPreview

  1. Inicia tu app en local con las rutas de OAuth habilitadas.
  2. Ejecuta npx portpreview 3000 para obtener una URL HTTPS pública.
  3. Añade la URL de callback (por ejemplo https://your-app.portpreview.dev/auth/callback) a los redirect URIs permitidos de tu proveedor de OAuth.
  4. Actualiza tu entorno local para usar la URL del túnel como URL base.
  5. Inicia el flujo de OAuth en un navegador y completa el ciclo de redirección.
  6. Verifica el intercambio de tokens, la creación de sesión y el manejo de errores.

Consejos por proveedor

Google OAuth

Google permite http://localhost para desarrollo, pero probar con túneles HTTPS valida el comportamiento similar a producción, incluidas las flags de cookies seguras y las políticas de contenido mixto.

GitHub OAuth

GitHub exige coincidencia exacta del redirect URI. Registra tu URL de túnel en los ajustes de la app OAuth y actualízala cuando cambie la sesión del túnel, o usa un subdominio estable si tu proveedor de túnel lo admite.

Auth0 e IdP empresariales

Los proveedores de identidad empresariales suelen exigir callbacks HTTPS y a veces restringen localhost por completo. Los túneles son la solución estándar para pruebas locales de integración SAML y OIDC.

Errores comunes al probar OAuth en local

  • Redirect URI no coincidente: la URL de callback debe coincidir exactamente, incluidas barras finales y mayúsculas/minúsculas del path.
  • URL de túnel obsoleta: si tu URL de túnel cambia entre sesiones, actualiza la lista blanca del proveedor.
  • Parámetro state no validado: verifica siempre el parámetro state para prevenir ataques CSRF, incluso en desarrollo.
  • Problemas de dominio de cookies: las cookies de sesión pueden no persistir si los ajustes de dominio chocan con el hostname del túnel.

Consideraciones de seguridad

Los callbacks de OAuth transportan códigos de autorización que deben intercambiarse en el servidor. Nunca expongas los client secrets en el código frontend y trata las URLs de túnel como endpoints de desarrollo temporales, no como dominios de producción. Lee nuestra guía de seguridad de túneles a localhost para conocer las mejores prácticas.

Compartir flujos de OAuth con el equipo

Cuando producto o QA necesiten probar el inicio de sesión social, comparte la URL del túnel en lugar de desplegar a staging. Mira cómo compartir tu servidor de desarrollo local para flujos de colaboración.

Únete a la lista de espera de PortPreview para agilizar las pruebas de OAuth y webhooks desde un solo túnel.

Preguntas frecuentes

¿Se puede probar OAuth en localhost?
Sí. La mayoría de los proveedores de OAuth permiten redirect URIs http://localhost, pero muchos exigen HTTPS para pruebas similares a producción. Un túnel a localhost ofrece una URL HTTPS pública mapeada a tu app local.
¿Por qué los proveedores de OAuth exigen redirect URIs HTTPS?
HTTPS protege los códigos de autorización y los tokens en tránsito durante la redirección. Muchos proveedores imponen HTTPS para evitar la interceptación de credenciales sensibles en redes no seguras.
¿Cómo registro una URL de túnel como redirect URI de OAuth?
Copia tu URL HTTPS de túnel, añade tu ruta de callback y agrega la URL completa a la lista de redirect URIs permitidos en el panel de desarrollador de tu proveedor.