Skip to main contentArrow Right
Blog post cover with the label "Developer Guide" at the top, the Descope logo mark next to the Flutter logo in the center, and the title "Add Auth to Flutter" in glowing teal text below.

Table of Contents

Summarize with AI

Don't have the time to read the entire post? Our human writers will be sad, but we understand. Summarize the post with your preferred LLM here instead.

This tutorial was written by Dedan Ndungu, a software engineer with experience in mobile app development using Java, Kotlin, and Flutter. Connect with him on LinkedIn or X to see more of his work!


Flutter is a modern framework for building beautiful and highly performative cross-platform apps. You can quickly ship apps for different platforms from a single codebase, thus saving time and resources. User authentication is a common feature in modern apps, which requires app users to sign up and log in to provide them with an identity. This is important to prevent fraud and provide a well-curated user experience. However, setting up user authentication and roles can be challenging and complex when building from scratch.

Descope is a solution for seamlessly integrating secure authentication into your Flutter app, leaving you to focus on what matters most to you. Additionally, Descope supports both web and mobile platforms when building your app with Flutter.

In this article, you will learn how to integrate Descope with a Flutter app, authenticate a user from the app, and configure authentication options, user roles, and permissions on the Descope dashboard.

If you're a visual learner, you can watch the video tutorial below instead!

Prerequisites

To complete this tutorial, you need the following:

  • A Descope account (free tier available)

  • A basic understanding of Flutter development and Dart programming

  • A Flutter development environment set up (IDE or command line tools)

Setting up Descope

Once you have signed up to Descope, log in and check the Descope dashboard, which offers many options for configuring authentication in your application.

On the left, you should see a sidebar, as shown in the following screenshot:

Descope Console with the Getting Started page open, signed in as Dedan Ndungu on the Free Plan. The left sidebar lists Home and Getting Started (selected), then a Build section with Authentication Methods, Flows, Widgets, Styles, Localization, and Connectors, a Manage section with Users, Access Keys, Tenants, Applications, Authorization, and Audit, and a Settings section with Project. The main panel shows a three-step progress bar (1 Build, 2 Integrate, 3 Customize) with Build active, under the heading "We're now ready to show you Descope in action!" and the text "Clicking Next will generate the following flows for you to use:". Four flows are listed. Sign In: "Allows registered users to login to your app." Sign Up: "Allows users to register to your app for the first time." Sign Up or In: "A single flow that combines the sign up and sign in functionalities." Step Up: "Extra validation of the user, before performing high risk actions in your app." A warning box reads "If these flows have already been edited, clicking Next will override them." A preview panel on the right lists the primary methods as Passkeys (WebAuthn) and Social Login (OAuth / OIDC) and the secondary method as one-time password, above a sample login screen titled "Welcome!" with the buttons "Continue with Google," "Continue with Microsoft," and, after an "OR" divider, "Continue with Biometrics." Back and Next buttons sit below the preview.
Fig: Descope dashboard

The Getting Started tab allows you to quickly set up a sign-up and login screen flow with your preferred authentication methods for your app. In the Build section, you can configure the various authentication methods, create and edit authentication flows, design and style the authentication screens, and set up connections to third-party services. The Manage section is primarily used to view and organize users’ roles and other administration actions.

Configuring Descope authentication flows

Descope Flows is a no-code builder for defining authentication-related screens and flows for your app. The flows include authentication actions, conditions, and screen views, which can be created and edited in the Flows tab. To play around with the various options, check out Descope Explorer for the various integrations you can use for your app.

For this tutorial, you will configure the Passkeys and Social Login methods with the OTP MFA option. Open the Getting Started tab and start the flow setup, as shown subsequently:

Descope Getting Started wizard on step 1, Build, of three steps (Build, Integrate, Customize). A B2C tag sits beside the heading "Which method do you want to use for MFA?" with subtext explaining that multi-factor authentication (MFA) "provides a secondary layer of security using risk calculation." Seven method tiles are shown. Passkeys (WebAuthn) and Social Login (OAuth / OIDC), "e.g. Google, Microsoft," are both tagged Primary and outlined in blue. The one-time password tile is tagged Secondary and highlighted in purple as the selected MFA method. The magic link, Enchanted Link, and Authenticator Apps (TOTP) tiles are unselected, and SSO, "e.g. SAML," is grayed out. Back and Next buttons appear at the bottom right.
Fig: Setting up Descope Flows

Integrating Descope with Flutter

Descope offers a Flutter package to simplify your integration experience. Before integrating, you will need a Flutter project. To create one, open your terminal and run the following command:

flutter create --org com.auth descope_app

When the project is created, open it using Visual Studio Code and let it sync. To add the Descope package to your app, run the following command:

flutter pub add descope

With the Descope package installed, you can now initialize it, preferably when the app starts.

Before setting up the SDK, you need to complete a few additional configuration steps for iOS and Android:

iOS configuration setup

Open the ios/Podfile file and edit the target platform to 13.0 as shown here:

# Uncomment this line to define a global platform for your project
platform :ios, '13.0'

Android configuration setup

Open android/app/build.gradle and change minSdk = flutter.minSdkVersion to minSdk = 24 to ensure the minimum supported Android version is 24.

To support Descope Flows in an Android app, you must configure Android App Links. Open the file android/app/src/main/AndroidManifest.xml and add the following code at the bottom of the activity tags:

<activity>
    <!-- add the following at the end of the activity tag -->
    <intent-filter  android:autoVerify="true">  <!-- autoVerify required for app links -->
    <action  android:name="android.intent.action.VIEW"  />
    <category  android:name="android.intent.category.DEFAULT"  />
    <category  android:name="android.intent.category.BROWSABLE"  />

    <!-- the path should correspond with the routing paths defined in Flutter routing configuration -->
    <data  android:scheme="https"  android:host="your.deeplink.url"  android:path="/auth-android"  />
    <!-- Necessary when using magic links as an authentication option -->
    <data  android:scheme="https"  android:host="your.deeplink.url"  android:path="/magiclink"  />
    </intent-filter>
</activity>

Replace your.deeplink.url with your actual host URL that is verifiable by the Android framework, as described in the “Verify Android App Links” section. You can also enable magic link authentication support by changing the android:launchMode="singleTop" value to singleTask mode in the manifest file earlier.

Descope SDK initialization

You need the project ID from your Descope account to initialize the Descope SDK. Head over to the Descope dashboard, scroll to the Settings section from the sidebar, and click the Project tab. You should see the project ID. Copy the ID and return to the Flutter app. You should keep your project ID secure, so it’s best not to add it directly to the code. One option for securing it is using an ENV file. Add the package to load the ENV file:

flutter pub add flutter_dotenv

Then, create an ENV file in your project root folder with the following contents:

DESCOPE_PROJECT_ID = "YOUR-PROJECT-ID"

Make sure to update your assets in the pubspec.yaml file to specify where the ENV file is located:

 assets:
    - .env

Next, you can initialize the Descope SDK by opening the main.dart file and editing the main function to match the following content:

Future<void> main() async {
  // WidgetsFlutterBinding must be initialized before loading the Descope session manager
  WidgetsFlutterBinding.ensureInitialized();
  await dotenv.load(fileName: ".env");
  Descope.setup(dotenv.get('DESCOPE_PROJECT_ID'), (config) {
    if (kDebugMode) {
      config.logger = DescopeLogger();
    }
  });
  await Descope.sessionManager.loadSession();

  runApp(const MyApp());
}

In the preceding code, you ensure WidgetsFlutterBinding is initialized and then get the DESCOPE_PROJECT_ID from the ENV file. You then pass the project ID to set up the Descope SDK while enabling logging in debug mode.

Finally, you load the Descope session manager, which checks if a user is already authenticated for the current app instance.

Implementing the signup / login functionality

Your app will have two screens—the welcome and home screens. You will use the go_router package to handle navigation within the app. Please run this command to add it to your app:

flutter pub add go_router

To configure your navigation routes, update the MyApp class in the main.dart file, as shown in the following code:

import 'package:descope_app/home_screen.dart';
import 'package:descope_app/welcome_screen.dart';
import 'package:flutter/foundation.dart';
import 'package:flutter/material.dart';
import 'package:descope/descope.dart';
import 'package:flutter_dotenv/flutter_dotenv.dart';
import 'package:go_router/go_router.dart';

Future<void> main() async {
  // WidgetsFlutterBinding must be initialized before loading the Descope session manager
  WidgetsFlutterBinding.ensureInitialized();
  await dotenv.load(fileName: ".env");
  Descope.setup(dotenv.get('DESCOPE_PROJECT_ID'), (config) {
    if (kDebugMode) {
      config.logger = DescopeLogger();
    }
  });
  await Descope.sessionManager.loadSession();

  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp.router(
      title: 'Descope Flutter Sample App',
      theme: ThemeData(
        colorScheme: ColorScheme.fromSeed(seedColor: Colors.green),
        useMaterial3: true,
      ),
      routerConfig: GoRouter(
        routes: [
          GoRoute(
            path: '/',
            builder: (_, __) {
              final Uri currentUri = Uri.base;
              return Descope.sessionManager.session?.refreshToken.isExpired ==
                      false
                  ? const HomeScreen()
                  : WelcomeScreen(
                      code: currentUri.queryParameters['code'],
                    );
            },
            routes: [
              GoRoute(
                path: 'home',
                name: 'home',
                builder: (_, __) => const HomeScreen(),
              ),
              GoRoute(
                path: 'welcome',
                name: 'welcome',
                builder: (_, __) => const WelcomeScreen(),
              ),
              GoRoute(
                path: 'auth-android',
                redirect: (context, state) {
                  try {
                    Descope.flow.exchange(state.uri);
                  } catch (e) {
                    print(e);
                  }
                  return '/';
                },
              ),
              GoRoute(
                path: 'magiclink',
                redirect: (context, state) async {
                  try {
                    await Descope.flow.resume(state.uri);
                  } catch (e) {
                    print(e);
                  }
                  return '/';
                },
              ),
            ],
          ),
        ],
      ),
    );
  }
}

In the preceding code, the initial route checks if there is a Descope refreshToken and if it’s expired. If it is valid, the app navigates to the home screen; otherwise, it displays the welcome screen and passes an optional parameter, code, which is present during OAuth authentication.

You also included the auth-android and magiclink routes, which you configured earlier in the manifest. The Android platform uses these routes to receive login status from Descope.

At this point, you should notice an error that indicates that the WelcomeScreen is not defined. To resolve this, please create a new file, welcome_screen.dart, in the lib folder and add the following code to facilitate Descope authentication:

import 'package:descope/descope.dart';
import 'package:flutter/material.dart';
import 'package:flutter_dotenv/flutter_dotenv.dart';
import 'package:go_router/go_router.dart';

class WelcomeScreen extends StatefulWidget {
  final String? code;
  const WelcomeScreen({super.key, this.code});

  @override
  State<WelcomeScreen> createState() => _WelcomeScreenState();
}

class _WelcomeScreenState extends State<WelcomeScreen> {
  @override
  void initState() {
    super.initState();
    if (widget.code != null) {
      signupOrLogin();
    }
  }

  Future<void> signupOrLogin() async {
    try {
      final options = DescopeFlowOptions(
          mobile: DescopeMobileFlowOptions(
              flowUrl:
                  'https://auth.descope.io/${dotenv.get('DESCOPE_PROJECT_ID')}?flow=sign-up-or-in&debug=true',
              deepLinkUrl: 'https://your.deeplink.url/auth-android'),
          web: DescopeWebFlowOptions(
            flowId: 'sign-up-or-in',
            flowContainerCss: {
              "background-color": "antiquewhite",
              "width": "500px",
              "min-height": "300px",
              "margin": "auto",
              "position": "relative",
              "top": "50%",
              "transform": "translateY(-50%)",
              "display": "flex",
              "flex-direction": "column",
              "align-items": "center",
              "justify-content": "center",
              "box-shadow": "0px 0px 10px gray",
            },
          ));
      Descope.flow.start(options).then((authResponse) {
        final session = DescopeSession.fromAuthenticationResponse(authResponse);
        Descope.sessionManager.manageSession(session);
        if (!mounted) return;
        context.pushReplacementNamed('home');
      });
    } on DescopeException catch (e) {
      switch (e) {
        case DescopeException.wrongOTPCode:
        case DescopeException.invalidRequest:
        case DescopeException.flowCancelled:
          print(e);
        default:
          print(e);
      }
    }
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('Authenticate With Descope'),
      ),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: <Widget>[
            Text(
              '',
              textAlign: TextAlign.center,
            ),
            const SizedBox(height: 20),
            ElevatedButton(
              onPressed: signupOrLogin,
              child: const Text('Sign Up or Login'),
            )
          ],
        ),
      ),
    );
  }
}

In the preceding code, the function signupOrLogin handles Descope authentication. Within this function, you first configure the DescopeFlowOptions for both mobile and web platforms. For the mobile flow options, you specify a flowUrl where the previously defined flows are hosted (in this case, at Descope) and a deepLinkUrl to return to with the result after authenticating. For the web flow options, you configure the flowId of the desired flow from those configured earlier; in this case, sign-up-or-in. Additionally, you provide custom CSS code to design the Descope authentication screen.

After declaring the flow options, you initiate, start, and wait for the flow result. Once the authentication response is back, you transform it to a DescopeSession, which you then use to manage the user. After successful authentication, the app navigates to the home screen; otherwise, it throws an error.

For Flutter web, OAuth authentication methods redirect back to the app with query parameters. Ensure these parameters remain intact and call the signupOrLogin function to automatically continue and complete the flow.

To define the HomeScreen class, create a new file, home_screen.dart, in the lib folder and add the following code:

import 'package:descope/descope.dart';
import 'package:flutter/material.dart';
import 'package:go_router/go_router.dart';

class HomeScreen extends StatefulWidget {
  const HomeScreen({super.key});

  @override
  State<HomeScreen> createState() => _HomeScreenState();
}

class _HomeScreenState extends State<HomeScreen> {
  DescopeSession? session = Descope.sessionManager.session;

  Future<void> _logout() async {
    final refreshJwt = Descope.sessionManager.session?.refreshJwt;
    if (refreshJwt != null) {
      await Descope.auth.logout(refreshJwt);
      Descope.sessionManager.clearSession();
    }

    if (!mounted) return;
    context.pushReplacementNamed('welcome');
  }

  @override
  Widget build(BuildContext context) {
    if (session == null) {
      return const Scaffold(
        body: Center(
          child: Text('No user data available'),
        ),
      );
    }
    DescopeUser userInfo = session!.user;
    return Scaffold(
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: <Widget>[
            Text(
              'Hi, ${userInfo.name}!',
              textAlign: TextAlign.center,
            ),
            const SizedBox(height: 20),
            ElevatedButton(
              onPressed: _logout,
              child: const Text('Log out'),
            )
          ],
        ),
      ),
    );
  }
}

On the home screen, you display the authenticated user name and a logout button, which clears the user’s Descope session when pressed. To run and test the Flutter app on the web with ease, execute the following command on the terminal:

flutter run -d web-server --web-port 8080 --web-hostname 0.0.0.0

Implementing role-based access control

To improve security, users are granted different permissions. However, with role-based access control (RBAC), instead of assigning permissions to users, you create and attach specific permissions to a role, which is then assigned to a specific user. For example, you can assign ledger and book editing permissions to a role called accountant, which can then be assigned to a user who performs accounting tasks.

Descope supports RBAC by enabling you to create permissions that can be attached to a specific role. These roles can then be assigned to users who have signed up from your application.

To create permissions on Descope, click Authorization on the sidebar and then select the Permissions tab. Selecting the + Permission button displays a dialog where you can create a permission. For this tutorial, create a permission named Approve Transactions, as shown in the following screenshot:

Descope Console on the Authorization page, with the Permissions tab selected and an Add Permission dialog open. The page description reads "Configure Role-Based Access Control (RBAC) for your users, by creating Roles and Permissions," followed by a Learn More link. In the dialog, the required Name field contains "Approve Transactions," the Description field is empty, and Cancel and Add buttons sit at the bottom right. Behind the dialog, the permissions table lists three existing rows, SSO Admin, Impersonate, and User Admin, each with a created time of June 09, 2024 21:06, and the footer shows "Total Rows: 3." A "+ Permission" button appears at the upper right of the table, and Authorization is highlighted in the left sidebar.
Fig: Permissions

Next, select the Roles tab and click the + Roles button to display the input dialog. Create a role named Accountant and assign the permission you created earlier:

Descope Console on the Authorization page, with the Roles tab selected and an Add Role dialog open. In the dialog, the required Name field contains "Accountant," the Description field is empty, and the Permissions field holds one selected chip, "Approve Transactions." Cancel and Add buttons sit at the bottom right. Behind the dialog, the roles table shows one existing row, Tenant Admin, with the type Project and a created time of June 09, 2024 21:06, and the footer shows "Total Rows: 1." A "+ Role" button appears at the upper right of the table, and Authorization is highlighted in the left sidebar.
Fig: Roles

With a role defined, you can now assign it to a user. Initially, you need to register the user from the app and then open the Users tab in the Descope dashboard. Locate the registered user from the list and assign them the role by clicking Edit in the options list. You can assign as many roles as you need and then save the configuration:

Descope Console on the Users page with an edit dialog open for the user Tidtech Enterprises, whose status is Active. The Given Name field contains "Tidtech," Middle Name is empty, and Family Name contains "Enterprises." The Email and Phone values are redacted with red bars. Under the Authorization heading, the text "Define user access to tenants, and assign roles:" sits above a Tenants dropdown and a Roles field holding two chips, "Tenant Admin" and "Accountant," with plus and minus buttons beside it. Under "Define user access to applications:" the Applications field holds the chip "All Applications." Cancel and Save buttons sit at the bottom right. Behind the dialog, the Users table shows two partially hidden rows created June 11, 2024 09:16 and June 15, 2024 01:22, and the project selector in the sidebar reads "neat-red-roentgen."
Fig: Role assignment

After the previous step, you can view the user’s permissions and roles from the app after a successful login. You can add the following code in the build method of the HomeScreen class to get the permissions and roles assigned to the logged-in user:

    List<String> permissions =
        Descope.sessionManager.session?.permissions() ?? [];
    List<String> roles = Descope.sessionManager.session?.roles() ?? [];

Protecting app content with RBAC

User roles can control access to content and display relevant information to different users. You can assign different users different roles and then use conditional statements to filter content that you would like displayed to them or actions they are allowed to perform. For instance, you can add the following code in the Column widget of the home screen to check if the user has the role of Accountant and display a button that enables them to view transactions if they do:

Text('Your roles in the company are: ${roles}'),
roles.contains("Accountant")
                ? ElevatedButton(
                    onPressed: () {}, child: const Text('View Transactions'))
                : SizedBox.shrink(),

Depending on how complex your app is, there are various practices to consider when working with RBAC, especially when designing the app’s UI and performing navigations. To reduce clutter, display only the UI elements relevant to a user’s role and ensure they can perform only the tasks assigned to that role. Furthermore, you can leverage RBAC to structure your app navigation so that different roles have different dashboards or screens.

Conclusion

In this article, you configured authentication flows on the Descope dashboard, which you integrated into your Flutter app. You learned how to set up Descope to support authentication in both mobile and web apps. You also touched on RBAC and configured roles and permissions on Descope while using them to control access to your app. You can find the code to the tutorial in this GitHub repository.

Descope simplifies your app development experience by abstracting user authentication and providing fully-fledged access management. Their Flutter app integration is smooth and provides many options for managing user sessions. With Descope, you can focus on building the crucial parts, saving you lots of stress and resources. Sign up for a free account or book a demo.