Switching authentication flows

For client side authentication there are four different flows:

1. USER_SRP_AUTH: The USER_SRP_AUTH flow uses the SRP protocol (Secure Remote Password) where the password never leaves the client and is unknown to the server. This is the recommended flow and is used by default.

2. USER_PASSWORD_AUTH: The USER_PASSWORD_AUTH flow will send user credentials to the backend without applying SRP encryption. If you want to migrate users to Cognito using the "Migration" trigger and avoid forcing users to reset their passwords, you will need to use this authentication type because the Lambda function invoked by the trigger needs to verify the supplied credentials.

3. CUSTOM_WITH_SRP & CUSTOM_WITHOUT_SRP: Allows for a series of challenge and response cycles that can be customized to meet different requirements.

4. USER_AUTH: The USER_AUTH flow is a choice-based authentication flow that allows the user to choose from the list of available authentication methods. This flow is useful when you want to provide the user with the option to choose the authentication method. The choices that may be available to the user are EMAIL_OTP, SMS_OTP, WEB_AUTHN, PASSWORD or PASSWORD_SRP.

The Auth flow can be customized when calling signIn, for example:

await signIn({
  username: "hello@mycompany.com",
  password: "hunter2",
  options: {
      authFlowType: 'USER_AUTH'
  }
})

For more information about authentication flows, please visit AWS Cognito developer documentation

USER_AUTH flow

The USER_AUTH sign in flow supports the following methods as first factors for authentication: WEB_AUTHN, EMAIL_OTP, SMS_OTP, PASSWORD, and PASSWORD_SRP.

If the desired first factor is known when authentication is initiated, it can be passed to the signIn API as the preferredChallenge to initiate the corresponding authentication flow.

// PASSWORD_SRP / PASSWORD
// sign in with preferred challenge as password
// note password must be provided in same step
const { nextStep } = await signIn({
    username: "hello@mycompany.com",
    password: "hunter2",
    options: {
        authFlowType: "USER_AUTH",
        preferredChallenge: "PASSWORD_SRP" // or "PASSWORD"
    },
});

// WEB_AUTHN / EMAIL_OTP / SMS_OTP
// sign in with preferred passwordless challenge
// no additional user input required at this step 
const { nextStep } = await signIn({
    username: "hello@example.com",
    options: {
        authFlowType: "USER_AUTH",
        preferredChallenge: "WEB_AUTHN" // or "EMAIL_OTP" or "SMS_OTP"
    },
});

If the desired first factor is not known or you would like to provide users with the available options, preferredChallenge can be omitted from the initial signIn API call.

This allows you to discover which authentication first factors are available for a user via the CONTINUE_SIGN_IN_WITH_FIRST_FACTOR_SELECTION step. You can then present the available options to the user and use the confirmSignIn API to respond with the user's selection.

const { nextStep: signInNextStep } = await signIn({
	username: '+15551234567',
	options: {
		authFlowType: 'USER_AUTH',
	},
});

if (
	signInNextStep.signInStep === 'CONTINUE_SIGN_IN_WITH_FIRST_FACTOR_SELECTION'
) {
	// present user with list of available challenges
	console.log(`Available Challenges: ${signInNextStep.availableChallenges}`);

	// respond with user selection using `confirmSignIn` API
	const { nextStep: nextConfirmSignInStep } = await confirmSignIn({
		challengeResponse: 'SMS_OTP', // or 'EMAIL_OTP', 'WEB_AUTHN', 'PASSWORD', 'PASSWORD_SRP'
	});
}

Also, note that if the preferredChallenge passed to the initial signIn API call is unavailable for the user, Amplify will also respond with the CONTINUE_SIGN_IN_WITH_FIRST_FACTOR_SELECTION next step.

USER_PASSWORD_AUTH flow

A use case for the USER_PASSWORD_AUTH authentication flow is migrating users into Amazon Cognito

Set up auth backend

In order to use the authentication flow USER_PASSWORD_AUTH, your Cognito app client has to be configured to allow it. In the AWS Console, this is done by ticking the checkbox at General settings > App clients > Show Details (for the affected client) > Enable username-password (non-SRP) flow. If you're using the AWS CLI or CloudFormation, update your app client by adding USER_PASSWORD_AUTH to the list of "Explicit Auth Flows".

Migrate users with Amazon Cognito

Amazon Cognito provides a trigger to migrate users from your existing user directory seamlessly into Cognito. You achieve this by configuring your User Pool's "Migration" trigger which invokes a Lambda function whenever a user that does not already exist in the user pool authenticates, or resets their password.

In short, the Lambda function will validate the user credentials against your existing user directory and return a response object containing the user attributes and status on success. An error message will be returned if an error occurs. Visit Amazon Cognito user pools import guide for migration flow and more detailed instruction, and Amazon Cognito Lambda trigger guide on how to set up lambda to handle request and response objects.

CUSTOM_WITH_SRP & CUSTOM_WITHOUT_SRP flows

Amazon Cognito user pools supports customizing the authentication flow to enable custom challenge types, in addition to a password in order to verify the identity of users. These challenge types may include CAPTCHAs or dynamic challenge questions. The CUSTOM_WITH_SRP flow requires a password when calling signIn. Both of these flows map to the CUSTOM_AUTH flow in Cognito.

Custom authentication flow

To initiate a custom authentication flow in your app, call signIn without a password. A custom challenge needs to be answered using the confirmSignIn API:

import { signIn, confirmSignIn } from 'aws-amplify/auth';

const challengeResponse = 'the answer for the challenge';

const { nextStep } = await signIn({
  username,
  options: {
    authFlowType: 'CUSTOM_WITHOUT_SRP',
  },
});

if (nextStep.signInStep === 'CONFIRM_SIGN_IN_WITH_CUSTOM_CHALLENGE') {
  // to send the answer of the custom challenge
  await confirmSignIn({ challengeResponse });
}

CAPTCHA authentication

To create a CAPTCHA challenge with a Lambda Trigger, please visit AWS Amplify Google reCAPTCHA challenge example for detailed examples.