Documentation

• Quickstarts: Native / Web - our interactive guide for quickly adding login, logout and user information to your app using Auth0
• Sample app - a full-fledged sample app integrated with Auth0
• API documentation - documentation auto-generated from the code comments that explains all the available features
• Examples - examples that demonstrate the different ways in which this SDK can be used
• FAQ - frequently asked questions about the SDK
• Docs Site - explore our Docs site and learn more about Auth0

Getting Started

Requirements

Installation

Add auth0_flutter into your project:

flutter pub add auth0_flutter

Configure Auth0

📱 Mobile/Desktop

Head to the Auth0 Dashboard and create a new Native application.

Configure the callback and logout URLs

The callback and logout URLs are the URLs that Auth0 invokes to redirect back to your app. Auth0 invokes the callback URL after authenticating the user, and the logout URL after removing the session cookie.

💡 On iOS 17.4+ and macOS 14.4+ it is possible to use Universal Links as callback and logout URLs. When enabled, auth0_flutter will fall back to using a custom URL scheme on older iOS / macOS versions.

This feature requires Xcode 15.3+ and a paid Apple Developer account.

Under the Application URIs section of the Settings page, configure the following URLs for your application for both Allowed Callback URLs and Allowed Logout URLs:

• Android: SCHEME://YOUR_DOMAIN/android/YOUR_PACKAGE_NAME/callback
• iOS: https://YOUR_DOMAIN/ios/YOUR_BUNDLE_ID/callback,YOUR_BUNDLE_ID://YOUR_DOMAIN/ios/YOUR_BUNDLE_ID/callback
• macOS: https://YOUR_DOMAIN/macos/YOUR_BUNDLE_ID/callback,YOUR_BUNDLE_ID://YOUR_DOMAIN/macos/YOUR_BUNDLE_ID/callback

Take note of the client ID and domain values under the Basic Information section. You'll need these values in the next step.

🌐 Web

Head to the Auth0 Dashboard and create a new Single Page application.

Next, configure the following URLs for your application under the Application URIs section of the Settings page:

• Allowed Callback URLs: http://localhost:3000
• Allowed Logout URLs: http://localhost:3000
• Allowed Web Origins: http://localhost:3000

💡 These URLs should reflect the origins that your app is running on. Allowed Callback URLs may also include a path, depending on where you're calling auth0_flutter's onLoad() method –see below.

💡 Make sure to use port 3000 when running your app: flutter run -d chrome --web-port 3000.

Take note of the client ID and domain values under the Basic Information section. You'll need these values in the next step.

Configure the SDK

📱 Mobile/Desktop

Start by importing auth0_flutter/auth0_flutter.dart.

import 'package:auth0_flutter/auth0_flutter.dart';

Then, instantiate the Auth0 class, providing your domain and client ID values from the previous step:

final auth0 = Auth0('YOUR_AUTH0_DOMAIN', 'YOUR_AUTH0_CLIENT_ID');

Android: Configure manifest placeholders

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

// android/build.gradle

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

manifestPlaceholders = [auth0Domain: "company.us.auth0.com", auth0Scheme: "https"]

<!-- android/src/main/AndroidManifest.xml -->

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    package="com.company.myapp">
    <application android:theme="@style/AppTheme">
        <!-- ... -->
        <activity
            android:name="com.auth0.android.provider.AuthenticationActivity"
            tools:node="remove"/>
        <!-- Optional: Remove RedirectActivity -->
        <activity
            android:name="com.auth0.android.provider.RedirectActivity"
            tools:node="remove"/>
        <!-- ... -->
    </application>
</manifest>

💡 https schemes require enabling Android App Links. You can read more about setting this value in the Auth0.Android SDK README.

💡 If your Android app is using product flavors, you might need to specify different manifest placeholders for each flavor.

iOS/macOS: Configure the associated domain

⚠️ This step requires a paid Apple Developer account. It is needed to use Universal Links as callback and logout URLs. Skip this step to use a custom URL scheme instead.

Select the Settings tab of your application's page, scroll to the end, and open Advanced Settings > Device Settings. In the iOS section, set Team ID to your Apple Team ID, and App ID to your app's bundle identifier.

This will add your app to your Auth0 tenant's apple-app-site-association file.

Next, open your app in Xcode by running open ios/Runner.xcworkspace (or open macos/Runner.xcworkspace for macOS). Go to the Signing and Capabilities tab of the Runner target settings, and press the + Capability button. Then select Associated Domains.

Under Associated Domains, add the following entry:

webcredentials:YOUR_AUTH0_DOMAIN

webcredentials:example.us.auth0.com

If you have a custom domain, replace YOUR_AUTH0_DOMAIN with your custom domain.

⚠️ For the associated domain to work, your app must be signed with your team certificate even when building for the iOS simulator. Make sure you are using the Apple Team whose Team ID is configured in the Settings page of your application.

🌐 Web

Start by importing auth0_flutter/auth0_flutter_web.dart.

import 'package:auth0_flutter/auth0_flutter_web.dart';

Then, instantiate the Auth0Web class, providing your domain and client ID values from the previous step:

final auth0Web = Auth0Web('YOUR_AUTH0_DOMAIN', 'YOUR_AUTH0_CLIENT_ID');

⚠️ You should have only one instance of this class.

Finally, in your index.html add the following <script> tag:

<script src="https://cdn.auth0.com/js/auth0-spa-js/2.0/auth0-spa-js.production.js" defer></script>

Logging in

📱 Mobile/Desktop

Present the Universal Login page in the onPressed callback of your Login button.

// Use a Universal Link callback URL on iOS 17.4+ / macOS 14.4+
// useHTTPS is ignored on Android
final credentials = await auth0.webAuthentication().login(useHTTPS: true);

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

auth0_flutter automatically stores the user's credentials using the built-in Credentials Manager instance. You can access this instance through the credentialsManager property.

final credentials = await auth0.credentialsManager.credentials();

For other comprehensive examples, see the EXAMPLES.md document.

🌐 Web

Start by calling the onLoad() method in your app's initState().

@override
  void initState() {
    super.initState();

    if (kIsWeb) {
      auth0Web.onLoad().then((final credentials) => {
        if (credentials != null) {
          // Logged in!
          // auth0_flutter automatically stores the user's credentials in the
          // built-in cache.
          //
          // Access token -> credentials.accessToken
          // User profile -> credentials.user
        } else {
          // Not logged in
        }
      });
    }
  }

Then, redirect to the Universal Login page in the onPressed callback of your Login button.

if (kIsWeb) {
  await auth0Web.loginWithRedirect(redirectUrl: 'http://localhost:3000');
}

if (kIsWeb) {
  final credentials = await auth0Web.loginWithPopup();
}

final popup = window.open('', '', 'width=400,height=800');
final credentials = await auth0Web.loginWithPopup(popupWindow: popup);

💡 You need to import the 'flutter/foundation.dart' library to access the kIsWeb constant. If your app does not support other platforms, you can remove this condition.

For other comprehensive examples, see the EXAMPLES.md document.

iOS SSO Alert Box

Check the FAQ for more information about the alert box that pops up by default when using web authentication on iOS.

💡 See also this blog post for a detailed overview of Single Sign-On (SSO) on iOS.

Common Tasks

📱 Mobile/Desktop

• Check for stored credentials - check if the user is already logged in when your app starts up.
• Retrieve stored credentials - fetch the user's credentials from the storage, automatically renewing them if they have expired.
• Retrieve user information - fetch the latest user information from the /userinfo endpoint.

🌐 Web

• Handling credentials on the web - how to check and retrieve credentials on the web platform.

API reference

📱 Mobile/Desktop

Web Authentication

• login
• logout

API

• login
• loginWithOtp
• multifactorChallenge
• renewCredentials
• resetPassword
• signup
• userProfile

Credentials Manager

• credentials
• hasValidCredentials
• storeCredentials
• clearCredentials

🌐 Web

• loginWithRedirect
• loginWithPopup
• onLoad
• logout
• credentials
• hasValidCredentials

Feedback

Contributing

We appreciate feedback and contribution to this repo! Before you get started, please see the following:

• Auth0's general contribution guidelines
• Auth0's code of conduct guidelines

Raise an issue

To provide feedback or report a bug, please raise an issue on our issue tracker.

Vulnerability Reporting

Please do not report security vulnerabilities on the public GitHub issue tracker. The Responsible Disclosure Program details the procedure for disclosing security issues.

Auth0 is an easy-to-implement, adaptable authentication and authorization platform. To learn more check out Why Auth0?

This project is licensed under the MIT license. See the LICENSE file for more info.