Agrega el inicio de sesión a tu aplicación Flutter

Esta guía muestra cómo integrar Auth0 con cualquier aplicación de Flutter mediante el SDK de Auth0 para Flutter.

Usa IA para integrar Auth0

Si usas un asistente de programación con IA como Claude Code, Cursor o GitHub Copilot, puedes agregar la autenticación de Auth0 automáticamente en cuestión de minutos con Agent Skills.

Instala:

npx skills add auth0/agent-skills --skill auth0-quickstart --skill auth0-flutter-native

Luego, pídele a tu asistente de IA:

Add Auth0 authentication to my Flutter app

Tu asistente de IA creará automáticamente tu aplicación de Auth0, obtendrá las credenciales, agregará la dependencia del SDK auth0_flutter, configurará las URL de devolución de llamada para Android e iOS, e implementará el inicio y cierre de sesión con Web Auth y almacenamiento seguro de credenciales. Documentación completa de Agent Skills →

Esta guía muestra cómo integrar Auth0 con una aplicación de Flutter mediante el SDK de Auth0 para Flutter. Abarca la configuración para las plataformas Android, iOS y macOS.

El SDK de Auth0 para Flutter también es compatible con Web y Windows (beta). Estas plataformas tienen inicios rápidos específicos:

• Inicio rápido de Flutter Web — para aplicaciones de Flutter orientadas al navegador
• Inicio rápido de Flutter Windows — para aplicaciones de escritorio de Flutter en Windows (beta)

​

Primeros pasos

1. Crea un proyecto nuevo de Flutter

   Cree un nuevo proyecto de Flutter para esta guía de inicio rápido.

   En su terminal:

   1. Vaya al directorio de trabajo
   2. Ejecute: flutter create auth0_flutter_sample
   3. Acceda al proyecto: cd auth0_flutter_sample
   4. Ábralo en su IDE:
      • VS Code: code .
      • Android Studio: open -a "Android Studio" .

   # Crear nuevo proyecto Flutter
   flutter create auth0_flutter_sample
   
   # Navegar al directorio del proyecto
   cd auth0_flutter_sample
   
   # Abrir en VS Code
   code .
   

   Esto crea una aplicación moderna de Flutter con la estructura de proyecto más reciente. Ejecuta flutter doctor para comprobar que tu entorno esté configurado correctamente.

2. Instala el SDK de Auth0 para Flutter

   Agrega el SDK de Auth0 para Flutter a tu proyecto con la CLI de Flutter.

   flutter pub add auth0_flutter
   

   Esto añadirá auth0_flutter a las dependencias de tu pubspec.yaml:

   pubspec.yaml

   dependencies:
     auth0_flutter: ^2.0.0-beta.1
   

   El SDK de Flutter de Auth0 requiere Flutter 3.24.0+ y Dart 3.5.0+. Ejecuta flutter doctor para verificar que tu entorno cumpla estos requisitos.

3. Configura tu aplicación de Auth0

   A continuación, debes crear una nueva aplicación en tu inquilino de Auth0 y configurar las URL de callback.

   1. Ve al Auth0 Dashboard
   2. Haz clic en Applications > Applications > Create Application
   3. En la ventana emergente, ingresa un nombre para tu aplicación, selecciona Native como tipo de aplicación y haz clic en Create
   4. Ve a la pestaña Settings en la página de detalles de la aplicación
   5. Anota los valores de Domain y Client ID; los necesitarás más adelante

   En la pestaña Settings, configura las siguientes URL según la plataforma de destino:

   Allowed Callback URLs:

   Android

   https://{yourDomain}/android/{yourPackageName}/callback
   

   iOS

   https://{yourDomain}/ios/{yourBundleIdentifier}/callback,
   {yourBundleIdentifier}://{yourDomain}/ios/{yourBundleIdentifier}/callback
   

   macOS

   https://{yourDomain}/macos/{yourBundleIdentifier}/callback,
   {yourBundleIdentifier}://{yourDomain}/macos/{yourBundleIdentifier}/callback
   

   Allowed Logout URLs:

   Agrega al campo Allowed Logout URLs las mismas URL de la configuración de callback anterior.

   Allowed Callback URLs son una medida de seguridad fundamental para garantizar que los usuarios regresen de forma segura a tu aplicación después de autenticarse. Sin una URL que coincida, el proceso de inicio de sesión fallará.

   Allowed Logout URLs son esenciales para ofrecer una experiencia de usuario fluida al cerrar sesión. Sin una URL que coincida, los usuarios no serán redirigidos de vuelta a tu aplicación después de cerrar sesión.

   Por ejemplo, si tu dominio de Auth0 es example.us.auth0.com y el nombre del paquete de Android es com.example.myapp, tu URL de callback de Android sería: https://example.us.auth0.com/android/com.example.myapp/callback

   Importante: Asegúrate de que el nombre del paquete (Android) o el identificador del paquete (iOS/macOS) de tus URL de callback coincida con el identificador real de tu aplicación. Si la autenticación falla, verifica que estos valores sean idénticos.

4. Configure su aplicación

   Se requiere una configuración específica para cada plataforma para habilitar el flujo de autenticación. Sigue las instrucciones correspondientes a cada plataforma de destino.

   Android

   Abre el archivo android/app/build.gradle y agrega los siguientes marcadores de posición del manifiesto dentro de android > defaultConfig:

   android/app/build.gradle

   android {
       // ...
       defaultConfig {
           // Agrega la siguiente línea
           manifestPlaceholders += [auth0Domain: "{yourDomain}", auth0Scheme: "https"]
       }
       // ...
   }
   

   Reemplaza {yourDomain} por tu dominio de Auth0 (por ejemplo, example.us.auth0.com).

   Esquema https

   Para usar el esquema https en tu URL de callback, configura Android app links para tu aplicación.

   Para la autenticación biométrica (opcional):

   Si planeas usar autenticación biométrica, actualiza MainActivity.kt para que extienda FlutterFragmentActivity:

   android/app/src/main/kotlin/.../MainActivity.kt

   import io.flutter.embedding.android.FlutterFragmentActivity
   
   class MainActivity: FlutterFragmentActivity() {
   }
   

   iOS

   Para usar Universal Links (URL de callback HTTPS) en iOS 17.4 o posterior, configura un dominio asociado:

   1. Abre tu aplicación en Xcode: open ios/Runner.xcworkspace
   2. Selecciona el target Runner y ve a Signing & Capabilities
   3. Haz clic en + Capability y agrega Associated Domains
   4. Agrega la entrada: webcredentials:{yourDomain}
   5. En el Auth0 Dashboard, ve a Settings > Advanced Settings > Device Settings
   6. En la sección iOS, establece tu Team ID y App ID (identificador del paquete)

   La configuración de Universal Links es opcional. Omite este paso si no necesitas compatibilidad con Universal Links; el SDK volverá automáticamente a los esquemas de URL personalizados.

   macOS

   Sigue los mismos pasos que para iOS, pero abre macos/Runner.xcworkspace.

   Android: Asegúrate de que el valor de auth0Domain coincida exactamente con tu dominio de Auth0. Si falla la autenticación, verifica que este valor sea idéntico al dominio que aparece en tu Auth0 Dashboard.

   iOS/macOS: Universal Links requieren una cuenta de pago de Apple Developer y iOS 17.4+/macOS 14.4+. En versiones anteriores, el SDK volverá automáticamente a esquemas de URL personalizados.

5. Implementa el inicio de sesión y el cierre de sesión

   Universal Login es la forma más sencilla de configurar la autenticación en su aplicación. Recomendamos usarlo para obtener la mejor experiencia, la máxima seguridad y la gama más completa de funcionalidades.

   Implementar el inicio de sesión:

   Importe el SDK de Auth0 para Flutter y cree una instancia de Auth0:

   lib/auth_service.dart

   import 'package:auth0_flutter/auth0_flutter.dart';
   
   class AuthService {
     final auth0 = Auth0('{yourDomain}', '{yourClientId}');
   
     Future<Credentials> login() async {
       final credentials = await auth0.webAuthentication().login(useHTTPS: true);
   
       // Token de acceso -> credentials.accessToken
       // token de ID -> credentials.idToken
       // Perfil de usuario -> credentials.user
   
       return credentials;
     }
   }
   

   Implementar el cierre de sesión:

   lib/auth_service.dart

   Future<void> logout() async {
     await auth0.webAuthentication().logout(useHTTPS: true);
   
     // El usuario ha cerrado sesión
     // Las credenciales se han eliminado del almacenamiento seguro
   }
   

   iOS/macOS: El parámetro useHTTPS: true habilita Universal Links en iOS 17.4+ y macOS 14.4+ para mejorar la seguridad.

   Android: si está usando un esquema personalizado, pase este esquema al método de inicio de sesión para que el SDK pueda enrutar correctamente a la página de inicio de sesión y de vuelta:

   await auth0.webAuthentication(scheme: 'YOUR CUSTOM SCHEME').login();
   
6. Mostrar la información del perfil del usuario

   El perfil del usuario se obtiene automáticamente cuando el usuario inicia sesión. El objeto Credentials contiene una propiedad user con toda la información del perfil del usuario, que se rellena al decodificar el token de ID.

   lib/profile_screen.dart

   void displayUserProfile(Credentials credentials) {
     final user = credentials.user;
     
     print('User ID: ${user.sub}');
     print('Email: ${user.email}');
     print('Name: ${user.name}');
     print('Picture: ${user.pictureUrl}');
     print('Nickname: ${user.nickname}');
   }
   

   Solicita los alcances adecuados al iniciar sesión para acceder a campos específicos del perfil del usuario. Los alcances predeterminados son openid, profile, email y offline_access.

7. Ejecuta tu aplicación

   Compila y ejecuta tu aplicación Flutter.

   En tu terminal:

   # Listar dispositivos disponibles
   flutter devices
   
   # Ejecutar en Android
   flutter run -d android
   
   # Ejecutar en el simulador de iOS
   flutter run -d ios
   
   # Ejecutar en macOS
   flutter run -d macos
   

   Flujo esperado:

   1. La aplicación se inicia con tu interfaz de inicio de sesión
   2. El usuario toca Log In → Se abre el navegador o una pestaña personalizada con Universal Login de Auth0
   3. El usuario completa la autenticación
   4. El navegador redirige de vuelta a tu aplicación
   5. El usuario ya está autenticado y las credenciales quedan almacenadas

Punto de verificación

Ahora deberías tener una experiencia de inicio de sesión con Auth0 totalmente funcional en tu aplicación Flutter. La aplicación utiliza autenticación segura basada en el navegador y almacena automáticamente las credenciales para mantener la sesión.

---

​

Solución de problemas y uso avanzado

Problemas comunes y soluciones

​

La URL de callback no coincide

Síntoma: Error “redirect_uri_mismatch” o la autenticación falla sin mostrar ningún error.

Soluciones:

1. Comprueba que Allowed Callback URLs en Auth0 Dashboard coincidan exactamente con la configuración de tu aplicación
2. Verifica el esquema (https:// frente a http://)
3. Asegúrate de que el nombre del paquete (Android) o el identificador del paquete (iOS/macOS) sean correctos
4. Comprueba si hay barras diagonales al final

​

Android: Chrome Custom Tab no se abre

Síntoma: No ocurre nada al llamar a login().

Solución:

1. Verifica que manifestPlaceholders esté configurado correctamente en build.gradle
2. Asegúrate de que el permiso de Internet esté en AndroidManifest.xml:
   <uses-permission android:name="android.permission.INTERNET" />
   
3. Comprueba que Chrome u otro navegador esté instalado en el dispositivo

​

iOS: alerta “Open in App”

Síntoma: Aparece un cuadro de diálogo preguntando si quieres abrirlo en tu aplicación.

Solución: Este comportamiento es el esperado con ASWebAuthenticationSession. Para quitarlo:

• Usa Universal Links (requiere iOS 17.4+ y una cuenta de pago de Apple Developer)
• O establece useEphemeralSession: true (desactiva el SSO):

await auth0.webAuthentication().login(
  useHTTPS: true,
  useEphemeralSession: true,
);

​

Autenticación cancelada por el usuario

Gestiona este caso correctamente en el control de errores:

try {
  final credentials = await auth0.webAuthentication().login(useHTTPS: true);
  // Gestiona el inicio de sesión correcto
} on WebAuthenticationException catch (e) {
  if (e.code == 'USER_CANCELLED') {
    showMessage('Login was cancelled');
  } else {
    showMessage('Login failed: ${e.message}');
  }
}

Gestión de credenciales

El SDK de Auth0 para Flutter incluye un Credentials Manager integrado que almacena de forma segura las credenciales del usuario. En las plataformas móviles, las credenciales se cifran y se almacenan en el almacenamiento seguro de la plataforma (Keychain en iOS/macOS y SharedPreferences cifrado en Android).

​

Comprobar si hay credenciales almacenadas

Antes de pedir al usuario que inicie sesión, comprueba si ya existen credenciales válidas:

lib/auth_service.dart

Future<bool> checkAuthentication() async {
  return await auth0.credentialsManager.hasValidCredentials();
}

​

Recuperar credenciales almacenadas

Recupera las credenciales para acceder a tokens o a la información del usuario. El Credentials Manager actualiza automáticamente los tokens caducados cuando es posible:

lib/auth_service.dart

Future<Credentials> getCredentials() async {
  return await auth0.credentialsManager.credentials();
}

No necesitas almacenar manualmente las credenciales después de iniciar sesión: el SDK lo hace automáticamente. Tampoco necesitas actualizar manualmente los tokens; el Credentials Manager los actualiza cuando es necesario.

Gestión de errores

Gestiona los errores de autenticación correctamente para ofrecer una buena experiencia de usuario.

lib/auth_service.dart

import 'package:auth0_flutter/auth0_flutter.dart';

Future<void> login() async {
  try {
    final credentials = await auth0.webAuthentication().login(useHTTPS: true);
    // Gestiona el inicio de sesión correcto
  } on WebAuthenticationException catch (e) {
    if (e.code == 'USER_CANCELLED') {
      // El usuario canceló el inicio de sesión
      print('Inicio de sesión cancelado por el usuario');
    } else {
      // Gestiona otros errores
      print('Error de inicio de sesión: ${e.message}');
    }
  }
}

Future<Credentials> getCredentials() async {
  try {
    return await auth0.credentialsManager.credentials();
  } on CredentialsManagerException catch (e) {
    if (e.isNoCredentialsFound) {
      // No hay credenciales almacenadas; el usuario debe iniciar sesión
      throw Exception('Inicia sesión primero');
    } else if (e.isTokenRenewFailed) {
      // El Token de actualización caducó; se requiere reautenticación
      return await auth0.webAuthentication().login(useHTTPS: true);
    }
    rethrow;
  }
}

Integración avanzada de Flutter

​

Seguridad reforzada de credenciales con biometría

Implementa autenticación biométrica para acceder a las credenciales en dispositivos móviles:

lib/secure_auth_service.dart

class SecureAuthService {
  final auth0 = Auth0('{yourDomain}', '{yourClientId}');
  
  Future<void> enableBiometrics() async {
    // Habilitar autenticación local (Face ID, Touch ID, huella digital)
    await auth0.credentialsManager.enableLocalAuthentication(
      title: 'Authenticate to access your account',
      cancelTitle: 'Cancel',
      fallbackTitle: 'Use passcode',
    );
  }
  
  Future<Credentials> getCredentialsWithBiometrics() async {
    // Esto ahora requerirá autenticación biométrica
    return await auth0.credentialsManager.credentials();
  }
}

Android: Requiere que MainActivity extienda FlutterFragmentActivity, como se configuró en el paso 4.

iOS/macOS: Requiere agregar NSFaceIDUsageDescription a tu Info.plist.

​

Alcances personalizados y audiencia

Solicita alcances específicos y una audiencia para tu API:

lib/auth_service.dart

Future<Credentials> loginWithCustomScopes() async {
  return await auth0.webAuthentication().login(
    useHTTPS: true,
    scopes: {'openid', 'profile', 'email', 'offline_access', 'read:posts'},
    audience: 'https://myapi.example.com',
    parameters: {'prompt': 'login'},
  );
}

​

Organizaciones (B2B/empresarial)

Autentica a los usuarios dentro de una organización específica:

lib/auth_service.dart

Future<Credentials> loginWithOrganization(String organizationId) async {
  return await auth0.webAuthentication().login(
    useHTTPS: true,
    organizationId: organizationId,
  );
}

// O pedir al usuario que seleccione una organización
Future<Credentials> loginWithOrganizationName(String organizationName) async {
  return await auth0.webAuthentication().login(
    useHTTPS: true,
    organizationName: organizationName,
  );
}

Implementación en producción

​

Preparación para App Store

• Configura Universal Links (iOS) y App Links (Android) para una autenticación fluida
• Prueba la aplicación en varios tamaños de dispositivo y versiones del sistema operativo
• Implementa un manejo de errores adecuado para fallos de red
• Agrega reglas de ProGuard para Android si usas ofuscación de código
• Sigue las políticas específicas de la plataforma para App Store/Play Store

​

Consideraciones de seguridad

• Usa el Credentials Manager integrado para almacenar credenciales en producción
• Habilita la autenticación biométrica para operaciones sensibles
• Considera la fijación de certificados para reforzar la seguridad de la API
• Implementa un manejo adecuado de la renovación de tokens
• Usa useHTTPS: true para Universal Links en las plataformas compatibles

---

​

Próximos pasos

Consulta el archivo EXAMPLES.md del repositorio del SDK para ver ejemplos de código detallados que cubren escenarios avanzados, como DPoP, autenticación biométrica, inicio de sesión sin contraseña y muchas otras funcionalidades.