Authenticator class

Amplify Authenticator

A prebuilt sign in/sign up experience for Amplify Auth. Simply provide a child widget which is your app's authenticated route, and the Authenticator will handle the logic behind managing user sessions and guiding users through the sign up and sign in process.

import 'package:amplify_auth_cognito/amplify_auth_cognito.dart';
import 'package:amplify_authenticator/amplify_authenticator.dart';
import 'package:amplify_flutter/amplify_flutter.dart';
import 'package:flutter/material.dart';

import 'amplifyconfiguration.dart';

void main() {
  runApp(const MyApp());
}

class MyApp extends StatefulWidget {
  const MyApp({Key? key}) : super(key: key);

  @override
  _MyAppState createState() => _MyAppState();
}

class _MyAppState extends State<MyApp> {
  @override
  void initState() {
    super.initState();
    _configureAmplify();
  }

  Future<void> _configureAmplify() async {
    try {
      await Amplify.addPlugin(AmplifyAuthCognito());
      await Amplify.configure(amplifyconfig);
    } on Exception catch (e) {
      print('Could not configure Amplify: $e');
    }
  }

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      theme: ThemeData.light(),
      darkTheme: ThemeData.dark(),
      home: Authenticator(
        child: const LoggedInScreen(),
      ),
    );
  }
}

class LoggedInScreen extends StatelessWidget {
  const LoggedInScreen({Key? key}) : super(key: key);

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Center(
        child: Column(
          children: const [
            Text('Logged In'),
            SignOutButton(),
          ],
        ),
      ),
    );
  }
}

Customization

Theming

By default, the Authenticator uses your app's Material theme for its styling.

Forms

The Authenticator uses your app's Cognito configuration (as defined in your amplifyconfiguration.dart file) to determine which fields are required. However, you may optionally add on additional fields using a custom form component. For example, to collect your user's address information on the s ign up form, use the SignUpForm.custom constructor:

Authenticator(
  signUpForm: SignUpForm.custom(fields: [
    SignUpFormField.address(
      required: false,
    ),
  ]),
  child: const LoggedInScreen(),
)

You can also override the validation of form fields if your app has custom requirements. The syntax for these follows Flutter's built-in FormFieldValidator class.

Authenticator(
  signUpForm: SignUpForm.custom(fields: [
    SignUpFormField.username(
      validator: (UsernameInput? input) {
        final username = input?.username;
        if (username == null || username.isEmpty) {
          return 'Username cannot be empty';
        }

        bool containsAmplify = username.contains('amplify');
        if (!containsAmplify) {
          return 'Username needs to include amplify';
        }

        return null;
      },
    ),
  ]),
  child: const LoggedInScreen(),
)

Localization

The Authenticator also supports localization by integrating with Flutter's built-in localization system. See the Flutter docs for an overview of how to get started, and check out a full example on our Github repo.

You can also use the localization mechanism to simply override the default strings used for the form fields and other widgets.

class CustomButtonResolver extends ButtonResolver {
  const CustomButtonResolver();

  @override
  String signout(BuildContext context) => 'Exit App';
}

Authenticator(
  stringResolver: const AuthStringResolver(
    buttons: CustomButtonResolver(),
  ),
  child: const LoggedInScreen(),
)

Custom UI

The authenticator provides prebuilt widgets for each step of the authentication flow based on the amplify config for your app. Some customizations can be achieved by providing custom forms (see signInForm and signUpForm) or through theming. To fully customize the authenticator UI, you can provide a custom builder method.

This can be used to change the layout of the authenticator, add your app's logo to certain views, add completely custom form fields (such as a terms and conditions field), and much more.

The example below shows a custom sign up view with an app bar and a flutter logo.

return Authenticator(
  authenticatorBuilder: (context, state) {
    switch (state.currentStep) {
      case AuthenticatorStep.signIn:
        return Scaffold(
          appBar: AppBar(title: const Text('My App')),
          body: Padding(
            padding: const EdgeInsets.all(16),
            child: Column(
              children: [
                // flutter logo
                const Center(child: FlutterLogo(size: 100)),
                // prebuilt sign in form from amplify_authenticator package
                SignInForm(),
              ],
            ),
          ),
        );
      default:
        return null;
    }
  },
  child: MaterialApp(
    builder: Authenticator.builder(),
    home: const RouteA(),
  ),
);

Inheritance

• Object
• DiagnosticableTree
• Widget
• StatefulWidget
• Authenticator

Constructors

Authenticator({Key? key, SignInForm? signInForm, SignUpForm? signUpForm, ConfirmSignInNewPasswordForm? confirmSignInNewPasswordForm, AuthStringResolver stringResolver = const AuthStringResolver(), required Widget child, ExceptionHandler? onException, ExceptionBannerLocation exceptionBannerLocation = ExceptionBannerLocation.auto, bool preferPrivateSession = false, AuthenticatorStep initialStep = AuthenticatorStep.signIn, AuthenticatorBuilder? authenticatorBuilder, EdgeInsets padding = const EdgeInsets.all(32), DialCodeOptions dialCodeOptions = const DialCodeOptions(), TotpOptions? totpOptions, @visibleForTesting StateMachineBloc? authBlocOverride})

Amplify Authenticator

Properties

authBlocOverride → StateMachineBloc?

final

authenticatorBuilder → AuthenticatorBuilder?

A method to build a custom UI for the authenticator

final

child → Widget

This widget will be displayed after a user has signed in.

final

confirmSignInNewPasswordForm → ConfirmSignInNewPasswordForm?

The form displayed when prompted for a password change upon signing in.

final

dialCodeOptions → DialCodeOptions

final

exceptionBannerLocation → ExceptionBannerLocation

The location on the screen to show error banners.

final

hashCode → int

The hash code for this object.

no setter, inherited

initialStep → AuthenticatorStep

The initial step that the authenticator will display if the user is not already authenticated.

final

key → Key?

Controls how one widget replaces another widget in the tree.

final, inherited

onException → ExceptionHandler?

A user-specified exception handler for errors originating within the Authenticator.

final

padding → EdgeInsets

final

preferPrivateSession → bool

iOS-only: Starts the webUI signin in a private browser session, if supported by the current browser.

final

runtimeType → Type

A representation of the runtime type of the object.

no setter, inherited

signInForm → SignInForm?

The form displayed during sign in.

final

signUpForm → SignUpForm?

The form displayed during sign up.

final

stringResolver → AuthStringResolver

An optional, user-defined string resolver, used for localizing the Authenticator or overriding default messages.

final

totpOptions → TotpOptions?

Options for configuring the TOTP MFA Experience

final

Methods

createElement() → StatefulElement

Creates a StatefulElement to manage this widget's location in the tree.

inherited

createState() → State<Authenticator>

Creates the mutable state for this widget at a given location in the tree.

override

debugDescribeChildren() → List<DiagnosticsNode>

Returns a list of DiagnosticsNode objects describing this node's children.

inherited

debugFillProperties(DiagnosticPropertiesBuilder properties) → void

Add additional properties associated with the node.

override

noSuchMethod(Invocation invocation) → dynamic

Invoked when a nonexistent method or property is accessed.

inherited

toDiagnosticsNode({String? name, DiagnosticsTreeStyle? style}) → DiagnosticsNode

Returns a debug representation of the object that is used by debugging tools and by DiagnosticsNode.toStringDeep.

inherited

toString({DiagnosticLevel minLevel = DiagnosticLevel.info}) → String

A string representation of this object.

inherited

toStringDeep({String prefixLineOne = '', String? prefixOtherLines, DiagnosticLevel minLevel = DiagnosticLevel.debug}) → String

Returns a string representation of this node and its descendants.

inherited

toStringShallow({String joiner = ', ', DiagnosticLevel minLevel = DiagnosticLevel.debug}) → String

Returns a one-line detailed description of the object.

inherited

toStringShort() → String

A short, textual description of this widget.

inherited

Operators

operator ==(Object other) → bool

The equality operator.

inherited

Static Methods

builder() → TransitionBuilder

Wraps user-defined navigators for integration with MaterialApp and Navigator.