Añade Login a tu aplicación Flutter para Windows

Esta guía muestra cómo integrar Auth0 con una aplicación de escritorio Flutter para Windows mediante el SDK de Auth0 para Flutter (beta).

Requisitos previos:

• Flutter SDK 3.24.0+ y Dart 3.5.0+.
• Windows 10 o posterior.
• Visual Studio 2022 con la carga de trabajo Desarrollo de escritorio con C++.
• Una cuenta de Auth0: regístrate gratis.

Esta función está en beta (auth0_flutter 2.1.0-beta.1). La API puede cambiar antes de su disponibilidad general.

Esta guía te muestra cómo agregar inicio de sesión, cierre de sesión y la visualización del perfil de usuario a una aplicación de escritorio de Flutter para Windows con el SDK auth0_flutter mediante OAuth 2.0 Flujo de código de autorización + PKCE.

​

Primeros pasos

1. Crear un proyecto Flutter para Windows

   Crea un nuevo proyecto de Flutter compatible con Windows.

   flutter create --platforms=windows my_app
   cd my_app
   

   Compruebe que Windows esté disponible:

   flutter devices
   

   Debería ver un dispositivo de escritorio con Windows en la lista.

   Ejecute flutter doctor para verificar que su entorno esté configurado correctamente y que se detecte Visual Studio 2022 con el desarrollo de escritorio en C++.

2. Instalar el SDK de Auth0 para Flutter

   Agrega la versión beta del SDK que incluye compatibilidad con Windows:

   flutter pub add auth0_flutter:2.1.0-beta.1
   flutter pub add flutter_dotenv
   

   Tu pubspec.yaml debe incluir:

   El SDK de Auth0 para Flutter requiere Flutter 3.24.0+ y Dart 3.5.0+. Además, la plataforma Windows también requiere Visual Studio 2022 con la carga de trabajo Desarrollo para el escritorio con C++.

3. Configurar Auth0

   Crea o configura una aplicación de Auth0 con las URL de devolución de llamada necesarias para la autenticación en aplicaciones de escritorio de Windows.

   Configuración rápida

   Crea una aplicación Native en tu Auth0 Dashboard con esta configuración:

   Field	Value
   Allowed Callback URLs	auth0flutter://callback
   Allowed Logout URLs	auth0flutter://callback

   Tus credenciales:

   • Domain: {yourDomain}
   • Client ID: {yourClientId}

   CLI

   auth0 apps create \
     --name "My Flutter Windows App" \
     --type native \
     --callbacks "auth0flutter://callback" \
     --logout-urls "auth0flutter://callback"
   

   Dashboard

   1. Ve a Auth0 Dashboard → Applications > Applications.
   2. Selecciona Create Application.
   3. Asígnale el nombre “My Flutter Windows App” y elige Native como tipo de aplicación.
   4. Ve a la pestaña Settings de tu nueva aplicación.
   5. Configura Allowed Callback URLs con auth0flutter://callback.
   6. Configura Allowed Logout URLs con auth0flutter://callback.
   7. Desplázate hacia abajo y haz clic en Save Changes.
   8. Copia los valores de Domain y Client ID de la parte superior de la configuración de la aplicación.

   La URL auth0flutter://callback es un esquema personalizado que redirige el callback del navegador a tu aplicación de escritorio cuando se completa la autenticación.

4. Configurar las variables de entorno

   Crea un archivo .env en la raíz de tu proyecto:

   Agrega el archivo .env a los recursos de Flutter en pubspec.yaml:

   Nunca subas tu archivo .env al control de versiones. Agrégalo a .gitignore.

5. Configurar el runner de Windows

   El flujo de autenticación de Windows requiere configurar el callback en el runner de tu aplicación. El plugin de Flutter no recibe automáticamente del sistema operativo las activaciones del esquema de protocolo, por lo que debes agregar la aplicación de instancia única y el reenvío de URI.

   Reemplaza el contenido de windows/runner/main.cpp:

   Este código:

   • Garantiza una única instancia mediante un mutex de Windows.
   • Captura las URI auth0flutter://callback que se pasan como argumentos de línea de comandos.
   • Reenvía las URI de los inicios secundarios a la instancia en ejecución mediante un named pipe.
   • Establece la variable de entorno PLUGIN_STARTUP_URL para que el plugin de Auth0 la lea.
6. Registrar el esquema de URL personalizado

   Registra auth0flutter como un esquema de URL personalizado para que Windows dirija los URI de callback a tu aplicación.

   Crea el archivo windows/url_scheme.reg:

   Reemplaza C:\path\to\your\app.exe por la ruta real del ejecutable compilado de tu aplicación. Durante el desarrollo, normalmente es:

   build\windows\x64\runner\Debug\my_app.exe
   

   Haz doble clic en el archivo .reg para importarlo en el Registro de Windows.

   Para distribuirlo en producción, registra el esquema de URL personalizado mediante programación en el instalador de tu aplicación (MSIX, Inno Setup, etc.), en lugar de depender de un archivo .reg.

   Verifica que el esquema funcione:

   Abre el Símbolo del sistema y ejecuta:

   start auth0flutter://test
   

   La aplicación debería iniciarse (o pasar a primer plano si ya se está ejecutando).

7. Implementar Login y Logout

   Cree lib/auth_service.dart para gestionar la autenticación de Windows:

   Actualmente, el SDK de Auth0 Flutter para Windows no admite la administración de credenciales. Debe almacenar manualmente las credenciales si necesita que las sesiones se mantengan entre reinicios de la aplicación.

8. Mostrar información del perfil de usuario

   Crea la interfaz de usuario principal de la aplicación en lib/main.dart:

9. Ejecuta la aplicación

   Compila y ejecuta la aplicación:

   flutter run -d windows
   

   Flujo esperado:

   1. La app se inicia con un botón de Log In.
   2. Selecciona Log In. Se abrirá en el navegador del sistema la página de Auth0 Universal Login.
   3. Completa la autenticación en el navegador.
   4. El navegador redirige a auth0flutter://callback → tu app vuelve al primer plano.
   5. Se muestran el nombre, el correo electrónico y la foto de perfil del usuario.

   Asegúrate de registrar el esquema de URL personalizado (Paso 6) antes de hacer la prueba. De lo contrario, el callback del navegador no podrá llegar a tu aplicación.

Verificación

Ahora deberías tener una experiencia de inicio de sesión con Auth0 completamente funcional en tu aplicación de Flutter para Windows. La aplicación abre el navegador del sistema para Auth0 Universal Login, recibe el callback mediante el esquema de URL personalizado y muestra el perfil del usuario autenticado.

---

​

Solución de problemas y uso avanzado

Problemas comunes y soluciones

​

El navegador se abre, pero la aplicación no recibe el callback

Síntoma: El inicio de sesión con Auth0 se completa correctamente en el navegador, pero la aplicación nunca recibe las credenciales.

Solución:

1. Abra el Editor del Registro → HKEY_CURRENT_USER\Software\Classes\auth0flutter\shell\open\command y confirme la ruta de su .exe.
2. Pruebe con start auth0flutter://test en el Símbolo del sistema; la aplicación debería iniciarse.
3. Asegúrese de que windows/runner/main.cpp incluya el servidor de canalización y el código del mutex.
4. Compruebe que no haya instancias antiguas ejecutándose en el Administrador de tareas.
5. Vuelva a compilar por completo: flutter clean && flutter run -d windows.

​

La autenticación agota el tiempo de espera después de 5 minutos

Síntoma: Parece que Login se queda bloqueado y al final falla.

Solución: La aplicación nunca recibió la URI de callback. Verifique lo siguiente:

1. La entrada del registro apunta a la ruta correcta del ejecutable.
2. El nombre del mutex auth0flutter_single_instance_mutex es coherente en main.cpp.
3. Ningún firewall ni antivirus está bloqueando la canalización con nombre.
4. Finalice todas las instancias antiguas y vuelva a compilar.

​

Se inicia una segunda instancia de la aplicación en lugar de reenviar la URI

Síntoma: Se abre una nueva ventana en lugar de que la aplicación existente reciba el callback.

Solución:

1. Finalice todas las instancias en ejecución en el Administrador de tareas.
2. Asegúrese de que el nombre del mutex sea coherente en main.cpp.
3. Vuelva a compilar con el siguiente comando: flutter clean && flutter run -d windows.

​

No se encuentra WindowsWebAuthentication

Síntoma: Error de compilación que hace referencia a windowsWebAuthentication.

Solución: Asegúrese de que su pubspec.yaml especifique la versión beta:

dependencies:
  auth0_flutter: 2.1.0-beta.1

Ejecute flutter pub get para actualizar.

​

Error de discrepancia en la URL de devolución de llamada

Síntoma: Error “redirect_uri_mismatch” de Auth0.

Solución:

1. Verifique que Allowed Callback URLs en Auth0 Dashboard → configuración de la aplicación sea exactamente auth0flutter://callback.
2. Asegúrese de que el parámetro appCustomURL en su código coincida: 'auth0flutter://callback'.
3. Compruebe si hay barras diagonales finales o espacios en blanco.

Uso de un servidor intermediario

Cuando Auth0 redirige directamente a un esquema personalizado, el navegador puede mostrar un aviso o dejar una pestaña en blanco. Para una experiencia más fluida, use un servidor HTTPS intermediario:

1. Configure un endpoint del servidor (por ejemplo, https://your-app.example.com/callback) que redirija a auth0flutter://callback?code=...&state=....
2. En Auth0 Dashboard → configuración de la aplicación, establezca Allowed Callback URLs en https://your-app.example.com/callback.
3. Pase ambas URL al método de Login:

final result = await auth0.windowsWebAuthentication().login(
  appCustomURL: 'auth0flutter://callback',
  redirectUrl: 'https://your-app.example.com/callback',
);

La página del servidor puede mostrar “Redirigiendo…” y cerrarse sola para ofrecer una experiencia más fluida.

Scopes y audiencia personalizados

Solicite alcances adicionales o una audiencia de API:

final result = await auth0.windowsWebAuthentication().login(
  appCustomURL: 'auth0flutter://callback',
  scopes: {'openid', 'profile', 'email', 'read:messages'},
  audience: 'https://your-api.example.com',
);

Configure la API en Auth0 Dashboard → Aplicaciones > APIs antes de usar el parámetro audience.

---

​

Siguientes pasos

• SDK de Auth0 para Flutter en GitHub — código fuente y seguimiento de incidencias.
• SDK de Auth0 para Flutter en pub.dev — referencia de la API.
• Inicio rápido de Flutter (Android, iOS, macOS, Web) — otras guías para plataformas.
• Prácticas recomendadas para el almacenamiento de tokens — gestión segura de credenciales.
• Auth0 Universal Login — personalización de la experiencia de inicio de sesión.