Amplify V2 Multi-factor authentication

Amplify Auth supports Multi-factor Authentication (MFA) for user sign-in flows. MFA is an extra layer of security used to make sure that users trying to gain access to an account are who they say they are. It requires users to provide additional information to verify their identity. Amplify Auth supports the MFA methods with Time-based-One-Time Passwords (TOTP) as well as text messages (SMS). In this guide we will review how you can set up MFA using TOTP and SMS and the tradeoffs between these methods to help you choose the right set up for your application. We will also review how to set up MFA to remember a device and reduce sign-in friction for your users.

Configure multi-factor authentication

Use defineAuth to enable MFA for your app. The example below is setting up MFA with TOTP but not SMS as you can see that the phone number is not a required attribute. If you are using SMS, then the PhoneNumber attribute must be true.

　　amplify/auth/resource.ts

　　import { defineAuth } from '@aws-amplify/backend';

 

export const auth = defineAuth({

loginWith: {

email: true

},

 

multifactor: {

　　mode: 'OPTIONAL',

　　totp: true

　　}

});

When multi-factor authentication (MFA) is REQUIRED with SMS in your backend auth resource, you will need to pass the phone number during sign-up API call. If you are using the email or username as the primary sign-in mechanism, you will need to pass the phone_number attribute as a user attribute. This will change depending on if you enable SMS, TOTP, or both. Visit the multi-factor authentication documentation to learn more about enabling MFA on your backend auth resource.

Understand your MFA options

When enabling MFA you will have two key decisions to make:

• MFA enforcement: As part of this setup you will determine how MFA is enforced. If you require MFA by setting MFA login to "ON", all your users will need to complete MFA to sign in. If you keep it "Optional", your users will have the choice whether to enable MFA or not for their account.
• MFA methods: You will also specify which MFA method you are using - TOTP (Time-based One-time Password), SMS (text message), or both. We recommend that you use TOTP-based MFA as it is more secure and you can reserve SMS for account recovery.

Learn more

Compare TOTP and SMS MFA methods

Compare TOTP and SMS MFA methods

	Time-based One-time Password (TOTP)	Short Message Service (SMS)
Description	Generates a short-lived numeric code for user authentication that includes a shared secret key and current time using an authenticator app.	Generates a one-time code shared via text message that is entered with other credentials for user authentication.
Benefits	More secure than SMS since the code is generated locally and not transmitted over a network. TOTP also works without cell service as long as the TOTP app is installed.	Easy to set up with a user-provided phone number and is familiar to users as a common authentication method.
Constraints	Requires an app to generate codes and adds to the initial setup of an account. Codes also expire quickly and must be used promptly after it is generated.	SMS requires cell service and can include an additional cost for the user. Although rare, SMS messages can also be intercepted.

Multi-factor authentication with SMS

 

If you are using the Authenticator component with Amplify, this feature works without any additional code. The guide below is for writing your own implementation.

Once you have setup SMS as your second layer of authentication with MFA as shown above, your users will get an authentication code via a text message to complete sign-in after they sign in with their username and password.

 

Warning: In order to send SMS authentication codes, you must request an origination number. Learn more about configuring your auth resource for production workloads.

Enable SMS MFA during sign-up

You will need to pass phone_number as a user attribute to enable SMS MFA for your users during sign-up. However, if the primary sign-in mechanism for your Cognito resource is phone_number (without enabling username), then you do not need to pass it as an attribute.

func signUp(username: String, password: String, email: String, phonenumber: String) async {

　　do {

　　　　let signUpResult = try await Amplify.Auth.signUp(

　　　　username: username,

　　　　password: password,

　　　　options: .init(userAttributes: [

　　　　AuthUserAttribute(.email, value: email),

　　AuthUserAttribute(.phoneNumber, value: phonenumber)

　　　　　　])

　　　　)

　　if case let .confirmUser(deliveryDetails, _, userId) = signUpResult.nextStep {

　　print("Delivery details \(String(describing: deliveryDetails)) for userId: \(String(describing: userId)))")

　　　　　　} else {

　　　　　　print("SignUp Complete")

　　　　　　} catch let error as AuthError {

　　　　　　print("An error occurred while registering a user \(error)")

　　　　} catch {

　　　　　　print("Unexpected error: \(error)")

　　　　　　}

　　　　}

By default, you have to verify a user account after they sign up using the confirmSignUp API, which will send a one-time password to the user's phone number or email, depending on your Amazon Cognito configuration.

 

func confirmSignUp(for username: String, with confirmationCode: String) async {

　　do {

　　　　　　let confirmSignUpResult = try await Amplify.Auth.confirmSignUp(

　　　　　　for: username,

　　　　confirmationCode: confirmationCode

　　　　)

　　　　　　print("Confirm sign up result completed: \(confirmSignUpResult.isSignUpComplete)")

　　　　　　} catch let error as AuthError {

　　　　print("An error occurred while confirming sign up \(error)")

　　　　　　} catch {

　　　　print("Unexpected error: \(error)")

　　　　　　}

　　}

Manage SMS MFA during sign-in

After a user signs in, if they have MFA enabled for their account, a challenge will be returned that you would need to call the confirmSignIn API where the user provides their confirmation code sent to their phone number.

If MFA is ON or enabled for the user, you must call confirmSignIn with the OTP sent to their phone.

 

func confirmSignIn() async {

　　　　do {

　　　　　　let signInResult = try await Amplify.Auth.confirmSignIn(

　　　　　　challengeResponse: "<confirmation code received via SMS>")

　　　　　　print("Confirm sign in succeeded. Next step: \(signInResult.nextStep)")

　　　　　　} catch let error as AuthError {

　　　　print("Confirm sign in failed \(error)")

　　　　　　} catch {

　　　　　　　　print("Unexpected error: \(error)")

　　　　　　}

　　　　}

After a user has been signed in, call updateMFAPreference to record the MFA type as enabled for the user and optionally set it as preferred so that subsequent logins default to using this MFA type.

func updateMFAPreferences() async throws {

　　　　let authCognitoPlugin = try Amplify.Auth.getPlugin(

　　　　　　for: "awsCognitoAuthPlugin") as? AWSCognitoAuthPlugin

　　　　　　let smsMfaPreference: MFAPreference = .preferred

　　　　try await authCognitoPlugin?.updateMFAPreference(

　　　　　　sms: smsMfaPreference)

　　　　}

Multi-factor authentication with TOTP

If you are using the Authenticator component with Amplify, this feature works without any additional code. The guide below is for writing your own implementation.

You can use Time-based One-Time Password (TOTP) for multi-factor authentication (MFA) in your web or mobile applications. The Amplify Auth category includes support for TOTP setup and verification using authenticator apps, offering an integrated solution and enhanced security for your users. These apps, such as Google Authenticator, Microsoft Authenticator, have the TOTP algorithm built-in and work by using a shared secret key and the current time to generate short-lived, six digit passwords.

Set up TOTP for a user

After you initiate a user sign in with the signIn API where a user is required to set up TOTP as an MFA method, the API call will return continueSignInWithTOTPSetup as a challenge and next step to handle in your app. You will get that challenge if the following conditions are met:

• MFA is marked as Required in your user pool.
• TOTP is enabled in your user pool.
• User does not have TOTP MFA set up already.

The continueSignInWithTOTPSetup step signifies that the user must set up TOTP before they can sign in. The step returns an associated value of type TOTPSetupDetails which must be used to configure an authenticator app like Microsoft Authenticator or Google Authenticator. TOTPSetupDetails provides a helper method called getSetupURI which generates a URI that can be used, for example, in a button to open the user's installed authenticator app. For more advanced use cases, TOTPSetupDetails also contains a sharedSecret which can be used to either generate a QR code or be manually entered into an authenticator app.

Once the authenticator app is set up, the user can generate a TOTP code and provide it to the library to complete the sign in process.

 

func signIn(username: String, password: String) async {

　　　　do {

　　　　　　let signInResult = try await Amplify.Auth.signIn(

　　　　　　username: username,

　　　　　　password: password

　　　　　　)

 

　　if case .continueSignInWithTOTPSetup(let setUpDetails) = signInResult.nextStep {

　　　　print("Received next step as continue sign in by setting up TOTP")

　　　　print("Shared secret that will be used to set up TOTP in the authenticator app \(setUpDetails.sharedSecret)")

 

// appName parameter will help distinguish the account in the Authenticator app

　　　　　　let setupURI = try setUpDetails.getSetupURI(appName: "<Your_App_Name>>")

　　　　　　print("TOTP Setup URI: \(setupURI)")

 

// Prompt the user to enter the TOTP code generated in their authenticator app

// Then invoke `confirmSignIn` api with the code

　　　　　　}

　　　　} catch let error as AuthError {

　　　　　　print("Sign in failed \(error)")

　　　　} catch {

　　　　　　print("Unexpected error: \(error)")

　　　　　　}

　　　　}

The TOTP code can be obtained from the user via a text field or any other means. Once the user provides the TOTP code, call confirmSignIn with the TOTP code as the challengeResponse parameter.

 

func confirmSignIn() async {

　　do {

　　　　　　let signInResult = try await Amplify.Auth.confirmSignIn(

　　　　　　challengeResponse: "<confirmation code received from Authenticator app>")

　　　　　　print("Confirm sign in succeeded. Next step: \(signInResult.nextStep)")

　　　　} catch let error as AuthError {

　　　　　　print("Confirm sign in failed \(error)")

　　　　} catch {

　　print("Unexpected error: \(error)")

　　　　　　}

　　　　}

After a user has been signed in, call updateMFAPreference to record the MFA type as enabled for the user and optionally set it as preferred so that subsequent logins default to using this MFA type.

 

func updateMFAPreferences() async throws {

　　　　let authCognitoPlugin = try Amplify.Auth.getPlugin(

　　　　for: "awsCognitoAuthPlugin") as? AWSCognitoAuthPlugin

　　　　let totpMfaPreference: MFAPreference = .preferred

 

　　　　try await authCognitoPlugin?.updateMFAPreference(

　　　　totp: totpMfaPreference)

　　　　}

Enable TOTP after a user is signed in

TOTP MFA can be set up after a user has signed in. This can be done when the following conditions are met:

• MFA is marked as Optional or Required in your user pool.
• TOTP is marked as an enabled MFA method in your user pool.

TOTP can be set up by calling the setUpTOTP and verifyTOTPSetup APIs in the Auth category.

Invoke the setUpTOTP API to generate a TOTPSetupDetails object which should be used to configure an Authenticator app like Microsoft Authenticator or Google Authenticator. TOTPSetupDetails provides a helper method called getSetupURI which generates a URI that can be used, for example, in a button to open the user's installed Authenticator app. For more advanced use cases, TOTPSetupDetails also contains a sharedSecret which can be used to either generate a QR code or be manually entered into an Authenticator app.

that contains the sharedSecret which will be used to either to generate a QR code or can be manually entered into an Authenticator app.

 

func setUpTOTP() async {

　　　　do {

　　　　　　let setUpDetails = try await Amplify.Auth.setUpTOTP()

　　　　　　print("Received next step as continue sign in by setting up TOTP")

　　　　print("Shared secret that will be used to set up TOTP in the authenticator app \(setUpDetails.sharedSecret)")

 

// appName parameter will help distinguish the account in the Authenticator app

　　　　let setupURI = try setUpDetails.getSetupURI(appName: "<Your_App_Name>>") 

　　　　print("TOTP Setup URI: \(setupURI)")

 

// Prompt the user to enter the TOTP code generated in their authenticator app

// Then invoke `confirmSignIn` api with the code

　　　　} catch {

　　　　　　print("TOTP Setup Initiation failed \(error)")

　　　　　　}

　　　　}

Once the Authenticator app is set up, the user must generate a TOTP code and provide it to the library. Pass the code to verifyTOTPSetup to complete the TOTP setup process.

func verifyTOTPSetup(totpCodeFromAuthenticatorApp: String) async {

　　　　do {

　　　　　　try await Amplify.Auth.verifyTOTPSetup(

　　　　　　code: totpCodeFromAuthenticatorApp)

　　　　　} catch {

　　　　　　print("TOTP Setup Verification failed \(error)")

　　　　　　}

　　　　}

After TOTP setup is complete, call updateMFAPreference to record the MFA type as enabled for the user and optionally set it as preferred so that subsequent logins default to using this MFA type.

func updateMFAPreferences() async throws {

　　　　let authCognitoPlugin = try Amplify.Auth.getPlugin(

　　　　　　for: "awsCognitoAuthPlugin") as? AWSCognitoAuthPlugin

　　　　　　let smsMfaPreference: MFAPreference = .enabled

　　　　　　let totpMfaPreference: MFAPreference = .preferred

　　　　　　try await authCognitoPlugin?.updateMFAPreference(

　　　　sms: smsMfaPreference,

　　　　　　totp: totpMfaPreference)

　　}

Recover from a lost TOTP device

If a user loses access to their TOTP device, they will need to contact an administrator to get help accessing their account. Based on the Cognito user pool configuration, the administrator can use the AdminSetUserMFAPreference to either change the MFA preference to a different MFA method or to disable MFA for the user.

In a scenario where MFA is marked as "Required" in the Cognito User Pool and another MFA method is not set up, the administrator would need to first initiate an AdminUpdateUserAttributes call and update the user's phone number attribute. Once this is complete, the administrator can continue changing the MFA preference to SMS as suggested above.

Set up a user's preferred MFA method

Fetch the current user's MFA preferences

Invoke the following API to get the current MFA preference and enabled MFA types, if any, for the current user.

func getMFAPreferences() async throws {

　　　　let authCognitoPlugin = try Amplify.Auth.getPlugin(

　　　　for: "awsCognitoAuthPlugin") as? AWSCognitoAuthPlugin

　　let result = try await authCognitoPlugin?.fetchMFAPreference()

　　　　print("Enabled MFA types: \(result?.enabled)")

　　　　print("Preferred MFA type: \(result?.preferred)")

}

Update the current user's MFA preferences

Invoke the following API to update the MFA preference for the current user.

Only one MFA method can be marked as preferred at a time. If the user has multiple MFA methods enabled and tries to mark more than one MFA method as preferred, the API will throw an error.

func updateMFAPreferences() async throws {

　　　let authCognitoPlugin = try Amplify.Auth.getPlugin(

　　　　for: "awsCognitoAuthPlugin") as? AWSCognitoAuthPlugin

　　　　let smsMfaPreference: MFAPreference = .enabled

　　　　let totpMfaPreference: MFAPreference = .preferred

　　　　try await authCognitoPlugin?.updateMFAPreference(

　　　　sms: smsMfaPreference,

　　　　totp: totpMfaPreference)

}

If multiple MFA methods are enabled for the user, the signIn API will return continueSignInWithMFASelection as the next step in the auth flow. During this scenario, the user should be prompted to select the MFA method they want to use to sign in and their preference should be passed to confirmSignIn.

func signIn(username: String, password: String) async {

　　　do {

　　　　let signInResult = try await Amplify.Auth.signIn(username: username, password: password)

　　　　switch signInResult.nextStep {

　　　　case .continueSignInWithMFASelection(let allowedMFATypes):

　　　　print("Received next step as continue sign in by selecting MFA type")

　　　　print("Allowed MFA types \(allowedMFATypes)")

// Prompt the user to select the MFA type they want to use

// Then invoke `confirmSignIn` api with the MFA type

　　　　default:

// Use has successfully signed in to the app

　　　　print("Step: \(signInResult.nextStep)")

　　　　　　}

　　　　} catch let error as AuthError{

　　　　print ("Sign in failed \(error)")

　　　　} catch {

　　　　print("Unexpected error: \(error)")

　　　　　　}

　　　　}

 

func confirmSignInWithTOTPAsMFASelection() async {

　　　do {

　　　　　let signInResult = try await Amplify.Auth.confirmSignIn(

　　　　challengeResponse: MFAType.totp.challengeResponse)

　　　　if case .confirmSignInWithTOTPCode = signInResult.nextStep {

　　　　print("Received next step as confirm sign in with TOTP")

　　　　　　}

　　　　} catch {

　　　　print("Confirm sign in failed \(error)")

　　　　　　}

　　　　}

Remember a device

Remembering a device is useful in conjunction with MFA because it allows the second factor requirement to be automatically met when your user signs in on that device and reduces friction in their sign-in experience. By default, this feature is turned off.

Note: The device tracking and remembering features are not available if any of the following conditions are met:

• the federated OAuth flow with Cognito User Pools or Hosted UI is used, or
• when the signIn API uses the USER_PASSWORD_AUTH as the authFlowType.

Configure device tracking

You can configure device tracking with deviceTracking construct.

amplify/backend.ts

import { defineBackend } from '@aws-amplify/backend';

import { auth } from './auth/resource';

import { data } from './data/resource';

 

const backend = defineBackend({

　　　　auth,

　　　　data

　　});

const { cfnUserPool } = backend.auth.resources.cfnResources;

cfnUserPool.addPropertyOverride('DeviceConfiguration', {

ChallengeRequiredOnNewDevice: true,

DeviceOnlyRememberedOnUserPrompt: false

});

 

https://docs.amplify.aws/swift/build-a-backend/auth/concepts/multi-factor-authentication/#recover-from-a-lost-totp-device