auth0_flutter 1.7.2

Auth0 SDK for Flutter. Easily integrate Auth0 into Android / iOS Flutter apps.

📚 Documentation • 🚀 Getting started • 🌐 API reference • 💬 Feedback

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

Flutter	Android	iOS	macOS
SDK 3.0+	Android API 21+	iOS 13+	macOS 11+
Dart 2.17+	Java 8+	Swift 5.7+	Swift 5.7+
		Xcode 14.x / 15.x	Xcode 14.x / 15.x

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.

Using an existing Native application?

Select the Settings tab of your application's page and ensure that Application Type is set to Native. Avoid using other application types, as they have different configurations and may cause errors.

Scroll down and select the Show Advanced Settings link. Under Advanced Settings, select the OAuth tab and verify the following:

• Ensure that JsonWebToken Signature Algorithm is set to RS256
• Ensure that OIDC Conformant is enabled

Finally, if you made any changes don't forget to scroll to the end and press the Save Changes button.

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

Example

If your Auth0 domain was company.us.auth0.com and your package name (Android) or bundle ID (iOS/macOS) was com.company.myapp, then these values would be:

• Android: https://company.us.auth0.com/android/com.company.myapp/callback
• iOS: https://company.us.auth0.com/ios/com.company.myapp/callback,com.company.myapp://company.us.auth0.com/ios/com.company.myapp/callback
• macOS: https://company.us.auth0.com/macos/com.company.myapp/callback,com.company.myapp://company.us.auth0.com/macos/com.company.myapp/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.

Using an existing Single Page application?

Select the Settings tab of your application's page and ensure that Application Type is set to Single Page Application.

Then, scroll down and select the Show Advanced Settings link. Under Advanced Settings, select the OAuth tab and verify the following:

• Ensure that JsonWebToken Signature Algorithm is set to RS256
• Ensure that OIDC Conformant is enabled

If you made any changes don't forget to scroll to the end and press the Save Changes button.

Finally, head over to the Credentials tab and ensure that Authentication Methods is set to None.

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"]
    }
    // ...
}

Example

If your Auth0 domain was company.us.auth0.com, then the manifest placeholders line would be:

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

Not using web authentication?

If you don't plan to use web authentication, you will notice that the compiler will still prompt you to provide the manifestPlaceholders values, since the RedirectActivity included in this library will require them, and the Gradle tasks won't be able to run without them.

Re-declare the activity manually using tools:node="remove" in the android/src/main/AndroidManifest.xml file to make the manifest merger remove it from the final manifest file. Additionally, one more unused activity can be removed from the final APK by using the same process. A complete snippet to achieve this is:

<!-- 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

Example

If your Auth0 Domain were example.us.auth0.com, then this value would be:

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

Using a popup

Instead of redirecting to the Universal Login page, you can open it in a popup window.

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

To provide your own popup window, create it using the window.open() HTML API and set popupWindow to the result. You may want to do this if certain browsers (like Safari) block the popup by default; in this scenario, creating your own and passing it to loginWithPopup() may fix it.

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

⚠️ This requires that dart:html be imported into the plugin package, which may generate the warning 'avoid_web_libraries_in_flutter'.

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