Authentication support for Flutter apps with AWS Amplify

7 min readOct 13, 2020

Overview

Amplify Flutter plugin helps to integrate Flutter Apps with the following AWS services:

AWS Cognito
AWS S3
AWS Pinpoint

In this post, we are going to use AWS Cognito integration. I followed the steps documented on @ Amplify Flutter page. The objective of this post is to see what is happening behind the scenes when Amplify CLI commands run. Note that, as of today, Amplify Flutter is in preview mode.

Setup

All the commands used in this post have been tested on Windows 10.

Prerequisites

In order to use Amplify for Flutter plugin, the following dependencies need to be installed.

Node.js
npm
Flutter

Verify the dependencies

Install AWS Amplify for Flutter

npm install -g @aws-amplify/cli@flutter-preview

This installs the Amplify plugin.

...
----------------------------------------
Successfully installed the Amplify CLI
----------------------------------------

JavaScript Getting Started - https://docs.amplify.aws/start
Android Getting Started - https://docs.amplify.aws/start/q/integration/android
iOS Getting Started - https://docs.amplify.aws/start/q/integration/ios
Flutter Getting Started - https://docs.amplify.aws/start/q/integration/flutter
Amplify CLI collects anonymized usage data, which is used to help understand
how to improve the product. If you don't wish to send anonymized Amplify CLI
usage data to AWS, run amplify configure --usage-data-off  to opt-out.

...
+ @aws-amplify/cli@4.26.1-flutter-preview.0
added 1132 packages from 727 contributors in 82.102s

Configure Amplify CLI

This step sets a profile for an IAM (Identity & Access Management) user locally. It requires an IAM user and access keys (Access Key ID and Secret Key).

During the process, AWS Web Console opens in a web browser, and then, tries to create an IAM user. However, we don’t have to follow these. If an IAM user is already created with Admin access and we know their Access Key/Secret key, the browser windows can be closed.

C:\>amplify configure

Sample execution

Follow these steps to set up access to your AWS account:

Sign in to your AWS administrator account:
https://console.aws.amazon.com/
Press Enter to continue

Specify the AWS Region
? region:  us-east-2
Specify the username of the new IAM user:
? user name:  xxxxxxx
Complete the user creation using the AWS console
https://console.aws.amazon.com/iam/home?region=undefined#/users$new?step=final&accessKey&userNames=xxxxxxx&permissionType=policies&policies=arn:aws:iam::aws:policy%2FAdministratorAccess
Press Enter to continue

Enter the access key of the newly created user:
? accessKeyId:  ********************
? secretAccessKey:  ****************************************
This would update/create the AWS Profile in your local machine
? Profile Name:  default

Successfully set up the new user.

C:\>

Create a Flutter App

Create an app login_with_aws

$ cd C:\Users\ravis\Desktop\Flutter-projects
$ flutter create login_with_aws

Add Amplify dependencies for Cognito by updating the pubspec.yaml file

Provision the backend

Execute this at the root of the project

cd C:\Users\ravis\Desktop\Flutter-projects\login_with_aws
amplify init

Sample execution

Note: It is recommended to run this command from the root of your app directory
? Enter a name for the project loginwithaws
? Enter a name for the environment dev
? Choose your default editor: IntelliJ IDEA
? Choose the type of app that you're building flutter
Please tell us about your project
  Flutter project support in the Amplify CLI is in DEVELOPER PREVIEW.
Only the following categories are supported:
 * Auth
 * Analytics
 * Storage
? Where do you want to store your configuration file? ./lib/
Using default provider  awscloudformation

For more information on AWS Profiles, see:
https://docs.aws.amazon.com/cli/latest/userguide/cli-multiple-profiles.html

? Do you want to use an AWS profile? Yes
? Please choose the profile you want to use default
Adding backend environment dev to AWS Amplify Console app: d3tcuozprazrob
| Initializing project in the cloud...

...
User Initiated
√ Successfully created initial AWS cloud resources for deployments.


...
√ Initialized provider successfully.
Initialized your environment successfully.

Your project has been successfully initialized and connected to the cloud!

Some next steps:
"amplify status" will show you what you've added already and if it's locally configured or deployed
"amplify add <category>" will allow you to add features like user login or a backend API
"amplify push" will build all your local backend resources and provision it in the cloud
"amplify console" to open the Amplify Console and view your project status
"amplify publish" will build all your local backend and frontend resources (if you have hosting category added) and provision it in the cloud

Pro tip:
Try "amplify add api" to create a backend API and then "amplify publish" to deploy everything

The following directories are created in the root of the Flutter project.

A directory called amplify
A file amplifyconfiguration.dart in lib folder.

PS C:\Users\ravis\Desktop\Flutter-projects\login_with_aws> tree /f
...
│
├───amplify
│   │   team-provider-info.json
│   │
│   ├───#current-cloud-backend
│   │       amplify-meta.json
│   │
│   ├───.config
│   │       local-aws-info.json
│   │       local-env-info.json
│   │       project-config.json
│   │
│   └───backend
│amplify-meta.json
│           backend-config.json
│
...
│
├───lib
│       amplifyconfiguration.dart
│       main.dart
│
...
PS C:\Users\ravis\Desktop\Flutter-projects\login_with_aws>

At this point, the file amplifyconfiguration.dart looks like this:

const amplifyconfig = ''' {
    "UserAgent": "aws-amplify-cli/2.0",
    "Version": "1.0"
}''';

The file amplifyconfiguration.dart is required to initialize Amplify.

Add support for Cognito

This step creates many AWS resources in the backend. Some of them are

User Pool
Identity Pool
Roles required for Authenticated, and Unauthenticated users (Used by Identity pool)
App Clients

amplify add auth

Sample execution

Using service: Cognito, provided by: awscloudformation

 The current configured provider is Amazon Cognito.

 Do you want to use the default authentication and security configuration? Default configuration
 Warning: you will not be able to edit these selections.
 How do you want users to be able to sign in? Username
 Do you want to configure advanced settings? No, I am done.
Successfully added resource loginwithawsbe5eafa5 locally

Some next steps:
"amplify push" will build all your local backend resources and provision it in the cloud
"amplify publish" will build all your local backend and frontend resources (if you have hosting category added) and provision it in the cloud

Push the changes to AWS. This step executes a CloudFormation stack to create different resources.

amplify push

Sample execution

√ Successfully pulled backend environment dev from the cloud.

Current Environment: dev

| Category | Resource name        | Operation | Provider plugin   |
| -------- | -------------------- | --------- | ----------------- |
| Auth     | loginwithawsbe5eafa5 | Create    | awscloudformation |
? Are you sure you want to continue? Yes
/ Updating resources in the cloud. This may take a few minutes...

...
- Updating resources in the cloud. This may take a few minutes...

UPDATE_COMPLETE amplify-loginwithaws-dev-194552 AWS::CloudFormation::Stack Tue Oct 06 2020 20:20:13 GMT+1100 (Australian Eastern Daylight Time)
√ All resources are updated in the cloud

Using AWS Web console, if we look at CloudFormation stack, it will look like this:

How does the Flutter app know which User pool to use?

After the following commands are successfully executed, the CLI creates a file amplifyconfiguration.dart in the lib folder of the app (This is the default location). It is the configuration about Cognito backend. It contains the User pool, Identity Pool details.

amplify init
amplify add auth
amplify push

At this point, lib/amplifyconfiguration.dart looks like this:

Note that, the amplifyconfiguration.dart is stored in lib folder. It contains AppClientSecret which should be kept secret. It may be a good idea to remove the secret from when pushing the project to public repos such as GitHub.

How `amplifyconfiguration.dart is` used?

The file is used to initialize Amplify.

Using Amplify Cognito APIs

SignUp

Confirm User

SignIn

Check If the User is signed In

Fetching Credentials

Current User

Signout

Handling Exceptions

When any of the API calls fails, an AuthError exception is returned. It has an attribute exceptionList which is a list of AuthException objects. Each AuthException holds an exception of type String and detail of type dynamic.

Sample Error messages

Login Failed with Password Reset required message

cause: AMPLIFY_SIGNIN_FAILED
exceptionList Length: 2

exception: PASSWORD_RESET_REQUIRED
detail: Password reset required for the user

exception: PLATFORM_EXCEPTIONS
detail: {platform: Android, localizedErrorMessage: Sign in failed, recoverySuggestion: See attached exception for more details, errorString: AmplifyException {message=Sign in failed, cause=com.amazonaws.services.cognitoidentityprovider.model.PasswordResetRequiredException: Password reset required for the user (Service: AmazonCognitoIdentityProvider; Status Code: 400; Error Code: PasswordResetRequiredException; Request ID: a5447cb5-07e3-42fc-8d80-6e8e76432820), recoverySuggestion=See attached exception for more details}}

User does not exist

cause: AMPLIFY_SIGNIN_FAILED
exceptionList Length: 2

exception: PLATFORM_EXCEPTIONS
detail: {platform: Android, localizedErrorMessage: Sign in failed, recoverySuggestion: See attached exception for more details, errorString: AmplifyException {message=Sign in failed, cause=com.amazonaws.services.cognitoidentityprovider.model.UserNotFoundException: User does not exist. (Service: AmazonCognitoIdentityProvider; Status Code: 400; Error Code: UserNotFoundException; Request ID: 5e646790-0e98-413d-9913-151ef120a143), recoverySuggestion=See attached exception for more details}}

exception: AMAZON_CLIENT_EXCEPTION
detail: User does not exist. (Service: AmazonCognitoIdentityProvider; Status Code: 400; Error Code: UserNotFoundException; Request ID: 5e646790-0e98-413d-9913-151ef120a143)

Incorrect Password

cause: AMPLIFY_SIGNIN_FAILED
exceptionList Length: 2

exception: PLATFORM_EXCEPTIONS
detail: {platform: Android, localizedErrorMessage: Sign in failed, recoverySuggestion: See attached exception for more details, errorString: AmplifyException {message=Sign in failed, cause=com.amazonaws.services.cognitoidentityprovider.model.NotAuthorizedException: Incorrect username or password. (Service: AmazonCognitoIdentityProvider; Status Code: 400; Error Code: NotAuthorizedException; Request ID: aa34bd13-0ae9-4da3-9459-2b1f59c8c8f1), recoverySuggestion=See attached exception for more details}}

exception: NOT_AUTHORIZED
detail: Incorrect username or password.

We may not want to show the entire list to the end-user. A better user-friendly error message can be picked using this code.

Amplify Demos #1

There are example projects present in the Amplify repo that demonstrate Amplify Flutter plugin usage.
This demo is from the example

Amplify Demos #2

Teddy is the most lively login form I have ever seen. I have taken code from Teddy and extended it by adding Authentication with AWS Cognito using the Amplify plugin.

Source: https://github.com/ryandam9/auth-flutter-aws-amplify

Please go to https://thetechfirewall.com/ for more How to series documents.

Authentication support for Flutter apps with AWS Amplify

Overview

Setup

Prerequisites

Verify the dependencies

Install AWS Amplify for Flutter

Configure Amplify CLI

Create a Flutter App

Provision the backend

Add support for Cognito

How does the Flutter app know which User pool to use?

How `amplifyconfiguration.dart is` used?

Using Amplify Cognito APIs

SignUp

Confirm User

SignIn

Check If the User is signed In

Fetching Credentials

Current User

Signout

Handling Exceptions

Sample Error messages

Login Failed with Password Reset required message

User does not exist

Incorrect Password

Amplify Demos #1

Amplify Demos #2

Sign up to discover human stories that deepen your understanding of the world.

Free

Membership

Written by ryandam

No responses yet

Authentication support for Flutter apps with AWS Amplify

Overview

Setup

Prerequisites

Verify the dependencies

Install AWS Amplify for Flutter

Configure Amplify CLI

Create a Flutter App

Provision the backend

Add support for Cognito

How does the Flutter app know which User pool to use?

How amplifyconfiguration.dart is used?

Using Amplify Cognito APIs

SignUp

Confirm User

SignIn

Check If the User is signed In

Fetching Credentials

Current User

Signout

Handling Exceptions

Sample Error messages

Login Failed with Password Reset required message

User does not exist

Incorrect Password

Amplify Demos #1

Amplify Demos #2

Sign up to discover human stories that deepen your understanding of the world.

Free

Membership

Written by ryandam

No responses yet

How `amplifyconfiguration.dart is` used?