Saltar al contenido principal
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, macOS y Web.

​
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 (o Single Page Application si es solo para web) 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:
https://{yourDomain}/android/{yourPackageName}/callback
Allowed Logout URLs:Agrega al campo Allowed Logout URLs las mismas URL de la configuración de callback anterior.Allowed Web Origins (solo web):Si tu aplicación es para la plataforma web, agrega la URL de tu aplicación:
http://localhost:3000
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.
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 httpsPara 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() {
}
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:
lib/auth_service.dart
await auth0.webAuthentication(scheme: 'YOUR CUSTOM SCHEME').login();
Web: Debe llamar a onLoad() cuando se inicie su aplicación. Esto procesa el callback de redirección de Auth0 y restaura la sesión del usuario si ya está autenticado.
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 Web (usar el puerto 3000 para que coincida con las URLs de callback)
flutter run -d chrome --web-port 3000
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
Asegúrate de usar el puerto 3000 al ejecutar la aplicación web para que coincida con las URL de callback configuradas en Auth0. Puedes cambiar este puerto, pero asegúrate de que coincida con la configuración de Auth0.
Punto de verificaciónAhora 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

​
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,
);

​
Web: el usuario cierra sesión al recargar la página

Síntoma: El usuario parece haber cerrado sesión después de recargar la página.Solución:
  1. Asegúrate de llamar a onLoad() durante la inicialización de la aplicación
  2. Prueba a usar localStorage como ubicación de caché: 
    final auth0Web = Auth0Web(
  '{yourDomain}',
  '{yourClientId}',
  cacheLocation: CacheLocation.localStorage,
);
  3. Asegúrate de que tu dominio se haya añadido a Allowed Web Origins en Auth0 Dashboard

​
Web: error “Must run on a secure origin”

Síntoma: Error relacionado con el origen seguro en la consola del navegador.Solución: El SDK de Auth0 SPA requiere un contexto seguro. Usa localhost (que se considera seguro) o implementa la aplicación en un dominio HTTPS.

​
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}');
  }
}
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 {
  if (kIsWeb) {
    return await auth0Web.hasValidCredentials();
  } else {
    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 {
  if (kIsWeb) {
    return await auth0Web.credentials();
  } else {
    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.
Gestiona los errores de autenticación correctamente para ofrecer una buena experiencia de usuario.

​
Errores en dispositivos móviles/macOS

lib/auth_service.dart
import 'package:auth0_flutter/auth0_flutter.dart';

Future<void> login() async {
  try {
    final credentials = await auth0.webAuthentication().login(useHTTPS: true);
    // Gestionar el inicio de sesión exitoso
  } on WebAuthenticationException catch (e) {
    if (e.code == 'USER_CANCELLED') {
      // El usuario canceló el inicio de sesión
      print('Login cancelled by user');
    } else {
      // Gestionar otros errores
      print('Login error: ${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('Please log in first');
    } else if (e.isTokenRenewFailed) {
      // El Token de actualización expiró; es necesario volver a autenticarse
      return await auth0.webAuthentication().login(useHTTPS: true);
    }
    rethrow;
  }
}

​
Errores web

lib/web_auth_service.dart
import 'package:auth0_flutter/auth0_flutter_web.dart';

Future<void> login() async {
  try {
    await auth0Web.loginWithRedirect(redirectUrl: 'http://localhost:3000');
  } on WebException catch (e) {
    print('Login error: ${e.message}');
  }
}

​
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,
  );
}

​
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.