Auth0 Flutter SDK Quickstarts: Add Login to Your Flutter Application

Use AI to integrate Auth0

If you use an AI coding assistant like Claude Code, Cursor, or GitHub Copilot, you can add Auth0 authentication automatically in minutes using agent skills.Install:

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

Then ask your AI assistant:

Add Auth0 authentication to my Flutter app

Your AI assistant will automatically create your Auth0 application, fetch credentials, add the auth0_flutter SDK dependency, configure the Android and iOS callback URLs, and implement Web Auth login/logout with secure credential storage. Full agent skills documentation →

This guide demonstrates how to integrate Auth0 with a Flutter application using the Auth0 Flutter SDK. This guide covers setup for Android, iOS, and macOS platforms.

The Auth0 Flutter SDK also supports Web and Windows (beta). These platforms have dedicated quickstarts:

Flutter Web Quickstart — for Flutter apps targeting the browser
Flutter Windows Quickstart — for Flutter desktop apps on Windows (beta)

Get Started

Create a new Flutter project

Create a new Flutter project for this quickstart.In your terminal:

Navigate to your workspace directory
Run: flutter create auth0_flutter_sample
Navigate into the project: cd auth0_flutter_sample
Open in your IDE:
- VS Code: code .
- Android Studio: open -a "Android Studio" .

# Create new Flutter project
flutter create auth0_flutter_sample

# Navigate into project directory
cd auth0_flutter_sample

# Open in VS Code
code .

This creates a modern Flutter app with the latest project structure. Run flutter doctor to verify your environment is set up correctly.

Install the Auth0 Flutter SDK

Add the Auth0 Flutter SDK to your project using the Flutter CLI.

flutter pub add auth0_flutter

This will add auth0_flutter to your pubspec.yaml dependencies:

pubspec.yaml

dependencies:
  auth0_flutter: ^2.0.0-beta.1

The Auth0 Flutter SDK requires Flutter 3.24.0+ and Dart 3.5.0+. Run flutter doctor to verify your environment meets these requirements.

Setup your Auth0 App

Next up, you need to create a new app on your Auth0 tenant and configure the callback URLs.

Head to the Auth0 Dashboard
Click on Applications > Applications > Create Application
In the popup, enter a name for your app, select Native as the app type and click Create
Switch to the Settings tab on the Application Details page
Note down the Domain and Client ID values - you’ll need these later

On the Settings tab, configure the following URLs based on your target platform(s):Allowed Callback URLs:

Android
iOS
macOS

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

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

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

Allowed Logout URLs:Add the same URLs from the callback configuration above to the Allowed Logout URLs field.

Allowed Callback URLs are a critical security measure to ensure users are safely returned to your application after authentication. Without a matching URL, the login process will fail.Allowed Logout URLs are essential for providing a seamless user experience upon signing out. Without a matching URL, users will not be redirected back to your application after logout.For example, if your Auth0 domain is example.us.auth0.com and your Android package name is com.example.myapp, your Android callback URL would be: https://example.us.auth0.com/android/com.example.myapp/callback

Important: Ensure the package name (Android) or bundle identifier (iOS/macOS) in your callback URLs matches your actual app identifier. If authentication fails, verify these values are identical.

Configure Your Application

Platform-specific configuration is required to enable the authentication flow. Follow the instructions for each platform you’re targeting.

Android
iOS
macOS

Open the android/app/build.gradle file and add the following manifest placeholders inside android > defaultConfig:

android/app/build.gradle

android {
    // ...
    defaultConfig {
        // Add the following line
        manifestPlaceholders += [auth0Domain: "{yourDomain}", auth0Scheme: "https"]
    }
    // ...
}

Replace {yourDomain} with your Auth0 domain (e.g., example.us.auth0.com).https schemeTo use https scheme for your callback url, set up Android app links for your application.For Biometric Authentication (Optional):If you plan to use biometric authentication, update your MainActivity.kt to extend FlutterFragmentActivity:

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

import io.flutter.embedding.android.FlutterFragmentActivity

class MainActivity: FlutterFragmentActivity() {
}

To use Universal Links (HTTPS callback URLs) on iOS 17.4+, configure an Associated Domain:

Open your app in Xcode: open ios/Runner.xcworkspace
Select the Runner target and go to Signing & Capabilities
Click + Capability and add Associated Domains
Add the entry: webcredentials:{yourDomain}
In the Auth0 Dashboard, go to Settings > Advanced Settings > Device Settings
In the iOS section, set your Team ID and App ID (bundle identifier)

Universal Links configuration is optional. Skip this if you don’t need Universal Links support - the SDK will fall back to custom URL schemes automatically.

Follow the same steps as iOS, but open macos/Runner.xcworkspace instead.

Android: Ensure the auth0Domain value matches your Auth0 domain exactly. If authentication fails, verify this value is identical to the domain shown in your Auth0 Dashboard.iOS/macOS: Universal Links require a paid Apple Developer account and iOS 17.4+/macOS 14.4+. On older versions, the SDK automatically falls back to custom URL schemes.

Implement Login and Logout

Universal Login is the easiest way to set up authentication in your application. We recommend using it for the best experience, best security, and the fullest array of features.Implement Login:Import the Auth0 Flutter SDK and create an Auth0 instance:

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

    // Access token -> credentials.accessToken
    // ID token -> credentials.idToken
    // User profile -> credentials.user

    return credentials;
  }
}

Implement Logout:

lib/auth_service.dart

Future<void> logout() async {
  await auth0.webAuthentication().logout(useHTTPS: true);

  // User is now logged out
  // Credentials have been cleared from secure storage
}

iOS/macOS: The useHTTPS: true parameter enables Universal Links on iOS 17.4+ and macOS 14.4+ for enhanced security.Android: If you are using a custom scheme, pass this scheme to the login method so that the SDK can route to the login page and back again correctly:

await auth0.webAuthentication(scheme: 'YOUR CUSTOM SCHEME').login();

Show User Profile Information

The user profile is automatically retrieved when the user logs in. The Credentials object contains a user property with all the user profile information, populated by decoding the ID token.

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}');
}

Request the appropriate scopes during login to access specific user profile fields. The default scopes are openid, profile, email, and offline_access.

Run your app

Build and run your Flutter application.In your terminal:

# List available devices
flutter devices

# Run on Android
flutter run -d android

# Run on iOS Simulator
flutter run -d ios

# Run on macOS
flutter run -d macos

Expected flow:

App launches with your login UI
User taps Log In → Browser/Custom Tab opens with Auth0 Universal Login
User completes authentication
Browser redirects back to your app
User is now authenticated and credentials are stored

CheckpointYou should now have a fully functional Auth0 login experience in your Flutter application. The app uses secure browser-based authentication and automatically stores credentials for session persistence.

Troubleshooting & Advanced Usage

Common Issues & Solutions

Callback URL Mismatch

Symptom: Error “redirect_uri_mismatch” or authentication fails silently.Solutions:

Check Allowed Callback URLs in Auth0 Dashboard match your app configuration exactly
Verify the scheme (https:// vs http://)
Ensure the package name (Android) or bundle identifier (iOS/macOS) is correct
Check for trailing slashes

Android: Chrome Custom Tab Doesn’t Open

Symptom: Nothing happens when calling login().Fix:

Verify manifestPlaceholders are correctly set in build.gradle

Ensure internet permission is in AndroidManifest.xml:

<uses-permission android:name="android.permission.INTERNET" />

Check that Chrome or another browser is installed on the device

iOS: “Open in App” Alert

Symptom: Alert box appears asking to open in your app.Fix: This is expected behavior with ASWebAuthenticationSession. To remove it:

Use Universal Links (requires iOS 17.4+ and paid Apple Developer account)
Or set useEphemeralSession: true (disables SSO):

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

Authentication cancelled by user

Handle gracefully in your error handling:

try {
  final credentials = await auth0.webAuthentication().login(useHTTPS: true);
  // Handle successful login
} on WebAuthenticationException catch (e) {
  if (e.code == 'USER_CANCELLED') {
    showMessage('Login was cancelled');
  } else {
    showMessage('Login failed: ${e.message}');
  }
}

Handling Credentials

The Auth0 Flutter SDK includes a built-in Credentials Manager that securely stores user credentials. On mobile platforms, credentials are encrypted and stored in the platform’s secure storage (Keychain on iOS/macOS, encrypted SharedPreferences on Android).

Check for Stored Credentials

Before prompting the user to log in, check if valid credentials already exist:

lib/auth_service.dart

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

Retrieve Stored Credentials

Retrieve credentials to access tokens or user information. The Credentials Manager automatically refreshes expired tokens when possible:

lib/auth_service.dart

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

You don’t need to manually store credentials after login—the SDK handles this automatically. You also don’t need to manually refresh tokens; the Credentials Manager refreshes them when needed.

Error Handling

Handle authentication errors gracefully to provide a good user experience.

lib/auth_service.dart

import 'package:auth0_flutter/auth0_flutter.dart';

Future<void> login() async {
  try {
    final credentials = await auth0.webAuthentication().login(useHTTPS: true);
    // Handle successful login
  } on WebAuthenticationException catch (e) {
    if (e.code == 'USER_CANCELLED') {
      // User cancelled the login
      print('Login cancelled by user');
    } else {
      // Handle other errors
      print('Login error: ${e.message}');
    }
  }
}

Future<Credentials> getCredentials() async {
  try {
    return await auth0.credentialsManager.credentials();
  } on CredentialsManagerException catch (e) {
    if (e.isNoCredentialsFound) {
      // No stored credentials, user needs to log in
      throw Exception('Please log in first');
    } else if (e.isTokenRenewFailed) {
      // Refresh token expired, re-authentication required
      return await auth0.webAuthentication().login(useHTTPS: true);
    }
    rethrow;
  }
}

Advanced Flutter Integration

Enhanced Credential Security with Biometrics

Implement biometric authentication for credential access on mobile:

lib/secure_auth_service.dart

class SecureAuthService {
  final auth0 = Auth0('{yourDomain}', '{yourClientId}');
  
  Future<void> enableBiometrics() async {
    // Enable local authentication (Face ID, Touch ID, Fingerprint)
    await auth0.credentialsManager.enableLocalAuthentication(
      title: 'Authenticate to access your account',
      cancelTitle: 'Cancel',
      fallbackTitle: 'Use passcode',
    );
  }
  
  Future<Credentials> getCredentialsWithBiometrics() async {
    // This will now require biometric authentication
    return await auth0.credentialsManager.credentials();
  }
}

Android: Requires MainActivity to extend FlutterFragmentActivity as configured in Step 4.iOS/macOS: Requires adding NSFaceIDUsageDescription to your Info.plist.

Custom Scopes and Audience

Request specific scopes and audience for your 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'},
  );
}

Organizations (B2B/Enterprise)

Authenticate users within a specific organization:

lib/auth_service.dart

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

// Or prompt user to select an organization
Future<Credentials> loginWithOrganizationName(String organizationName) async {
  return await auth0.webAuthentication().login(
    useHTTPS: true,
    organizationName: organizationName,
  );
}

Production Deployment

App Store Preparation

Configure Universal Links (iOS) and App Links (Android) for seamless authentication
Test on multiple device sizes and OS versions
Implement proper error handling for network failures
Add ProGuard rules for Android if using code obfuscation
Follow platform-specific App Store/Play Store policies

Security Considerations

Use the built-in Credentials Manager for production credential storage
Enable biometric authentication for sensitive operations
Consider certificate pinning for additional API security
Implement proper token refresh handling
Use useHTTPS: true for Universal Links on supported platforms

Next Steps

Check out the EXAMPLES.md file in the SDK repository for comprehensive code examples covering advanced scenarios like DPoP, biometric authentication, passwordless login and many more features.

​Get Started

​Troubleshooting & Advanced Usage

​Callback URL Mismatch

​Android: Chrome Custom Tab Doesn’t Open

​iOS: “Open in App” Alert

​Authentication cancelled by user

​Check for Stored Credentials

​Retrieve Stored Credentials

​Enhanced Credential Security with Biometrics

​Custom Scopes and Audience

​Organizations (B2B/Enterprise)

​App Store Preparation

​Security Considerations

​Next Steps

Get Started

Troubleshooting & Advanced Usage

Callback URL Mismatch

Android: Chrome Custom Tab Doesn’t Open

iOS: “Open in App” Alert

Authentication cancelled by user

Check for Stored Credentials

Retrieve Stored Credentials

Enhanced Credential Security with Biometrics

Custom Scopes and Audience

Organizations (B2B/Enterprise)

App Store Preparation

Security Considerations

Next Steps