auth0_flutter

📚 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
SDK 3.0+	Android API 21+	iOS 12+
Dart 2.17+	Java 8+	Swift 5.5+
		Xcode 13.x / 14.x

Installation

Add auth0_flutter into your project:

flutter pub add auth0_flutter

Configure Auth0

📱 Mobile

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 verify the following:

• Ensure that Application Type is set to Native
• Ensure that the Token Endpoint Authentication Method setting has a value of None

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

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

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

• Android: SCHEME://YOUR_DOMAIN/android/YOUR_PACKAGE_NAME/callback
• iOS: YOUR_BUNDLE_ID://YOUR_DOMAIN/ios/YOUR_BUNDLE_ID/callback

Example

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

• Android: https://company.us.auth0.com/android/com.company.myapp/callback
• iOS: com.company.myapp://company.us.auth0.com/ios/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 verify the following:

• Ensure that Application Type is set to Single Page Application
• Ensure that the Token Endpoint Authentication Method setting has a value of None

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

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

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

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

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

iOS: Configure custom URL scheme

Open the ios/Runner/Info.plist file and add the following snippet inside the top-level <dict> tag. This registers your iOS bundle identifier as a custom URL scheme, so the callback and logout URLs can reach your app.

<!-- ios/Runner/Info.plist -->

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<!-- ... -->
    <key>CFBundleURLTypes</key>
    <array>
        <dict>
            <key>CFBundleTypeRole</key>
            <string>None</string>
            <key>CFBundleURLName</key>
            <string>auth0</string>
            <key>CFBundleURLSchemes</key>
            <array>
                <string>$(PRODUCT_BUNDLE_IDENTIFIER)</string>
            </array>
        </dict>
    </array>
<!-- ... -->
</dict>
</plist>

💡 If you're opening the Info.plist file in Xcode and it is not being shown in this format, you can Right Click on Info.plist in the Xcode project navigator and then select Open As > Source Code.

🖥️ 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

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

final credentials = await auth0.webAuthentication().login();
// 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

• 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

Web authentication

• login
• logout

API

• login
• 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.

What is Auth0?

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

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