Blog Maria Tech

Si estás integrando una API externa en tu aplicación web y te has topado con mensajes de error como “La aplicación no puede conectarse”, “Invalid redirect URI” o errores del navegador como ERR_CONNECTION_REFUSED al intentar autenticar usuarios mediante OAuth 2.0, no estás solo.

Este es uno de los problemas más frecuentes durante el desarrollo local y suele estar relacionado con una causa muy específica: la discrepancia de protocolos en la URI de redirección (redirect_uri).

A continuación, veremos por qué ocurre este problema y cómo solucionarlo para que tu flujo de autenticación funcione correctamente tanto en desarrollo como en producción.

El origen del problema: la seguridad en OAuth 2.0

OAuth 2.0 es el estándar utilizado por numerosas plataformas y servicios para permitir que aplicaciones externas accedan a recursos protegidos de forma segura. Durante la configuración de una aplicación, normalmente se debe registrar una o más URI de redirección.

Estas direcciones son utilizadas por el proveedor de autenticación para devolver al usuario a tu aplicación una vez que ha iniciado sesión y autorizado el acceso.

El conflicto suele aparecer debido a la diferencia entre los requisitos de seguridad de la plataforma y las características de un entorno local de desarrollo:

1. Las plataformas exigen HTTPS: Muchos proveedores requieren que la redirect_uri utilice un protocolo seguro (https://) para proteger el intercambio de información sensible.
2. Los entornos locales suelen usar HTTP: Herramientas de desarrollo como Laragon, XAMPP, WAMP o configuraciones locales de servidores web suelen funcionar inicialmente mediante http://.

Cuando la aplicación genera una URL con HTTPS pero el servidor local no está preparado para responder mediante ese protocolo, el navegador no puede establecer la conexión. Por otro lado, si se utiliza HTTP, muchos proveedores rechazarán la solicitud por razones de seguridad o porque la URL no coincide exactamente con la registrada.

La solución en 3 pasos

La clave consiste en lograr que tu entorno local soporte HTTPS y que las URLs generadas por tu aplicación coincidan exactamente con las registradas en el proveedor de autenticación.

Paso 1: Habilitar HTTPS en tu entorno local

Configura un certificado SSL local para que tu aplicación pueda responder mediante HTTPS.

Algunas opciones comunes son:

• Laragon: Permite habilitar certificados SSL locales de forma automática.
• Laravel Valet: Puede generar certificados locales seguros mediante comandos específicos.
• mkcert: Herramienta ampliamente utilizada para crear certificados confiables en entornos de desarrollo.
• Docker o servidores personalizados: Configura certificados SSL dentro del contenedor o servidor correspondiente.

Una vez configurado, tu aplicación debería ser accesible mediante una URL similar a:

https://miaplicacion.local

Paso 2: Generar URLs seguras desde la aplicación

Es importante que la URI de redirección se genere utilizando HTTPS para garantizar que coincida con la configuración registrada en el proveedor.

Por ejemplo, en Laravel:

$redirect_uri = secure_url(route('oauth.callback', [], false));

El objetivo no es utilizar una función específica, sino asegurarse de que la URL enviada al proveedor tenga exactamente el protocolo HTTPS esperado.

Paso 3: Verificar la configuración del proveedor

La URI configurada en el panel del proveedor debe coincidir exactamente con la generada por tu aplicación.

Ejemplos:

• Correcto: https://miaplicacion.local/oauth/callback
• Incorrecto: http://miaplicacion.local/oauth/callback
• Incorrecto: https://miaplicacion.local/oauth/callback/
• Incorrecto: https://www.miaplicacion.local/oauth/callback (si el dominio registrado no incluye www)

Las plataformas suelen realizar comparaciones estrictas, por lo que cualquier diferencia en protocolo, dominio, ruta, mayúsculas o barras finales puede provocar errores de autenticación.

Buenas prácticas adicionales

Además de corregir el problema inmediato, es recomendable seguir estas prácticas:

• Mantener la misma estructura de URLs entre desarrollo, pruebas y producción.
• Utilizar variables de entorno para configurar dominios y rutas de autenticación.
• Evitar construir manualmente las URLs de redirección cuando el framework puede generarlas automáticamente.
• Verificar periódicamente la configuración registrada en los proveedores externos.
• Probar el flujo completo de autenticación antes de desplegar cambios en producción.

Conclusión

La mayoría de los problemas relacionados con OAuth 2.0 en entornos de desarrollo no provienen de errores en el código, sino de diferencias entre la configuración local y los requisitos de seguridad exigidos por los proveedores de autenticación.

Al habilitar HTTPS localmente, generar URLs seguras desde la aplicación y asegurarte de que las URIs registradas coincidan exactamente con las utilizadas en el código, podrás evitar errores de autenticación y contar con un flujo de integración mucho más estable y seguro.

Estos mismos principios aplican a cualquier integración basada en OAuth 2.0, independientemente del proveedor o servicio externo con el que estés trabajando.