Add SMS flows

There are a few ways to integrate phone numbers into an Amplify project's sign-in and verification process.

• As a username*: Users login with a username and password where their phone number acts as the username.
• As a verification method: Users login by any means, but must verify their account with an OTP (one time password) sent to their phone.
• MFA (Multi-Factor Authentication): Users must verify every login with an OTP sent to their phone.

*Note: This is different from using a phone number alias, which is currently unsupported by the Amplify CLI.

These methods may be combined with each other or used independently but they all require the same prerequisites for sending SMS messages via Amazon SNS, the notification service used by Amplify.

Prerequisites

Sandbox Mode

Upon enabling any of the above settings in Amplify, the CLI may prompt you with the following message:

You have enabled SMS based auth workflow. Verify your SNS account mode in the SNS console: https://console.aws.amazon.com/sns/v3/home#/mobile/text-messaging
If your account is in "Sandbox" mode, you can only send SMS messages to verified recipient phone numbers.

Follow the link to visit your SNS account. If your account is in "Sandbox" mode, you'll need to verify a phone number before you're able to send SMS messages.

Set up an Origination Entity

If you see the following banner at the top of your SNS homepage, you'll need to perform some additional steps before adding a phone number. If not, you can skip to Verify a Phone Number.

Clicking Manage origination entities will bring you to Pinpoint, where you can register an originating entity. Depending on which country you'll be sending SMS messages from, you may choose to register either a Sender ID or an Origination number.

You can find the complete list of supported options for your country here.

Sender ID

If your country supports using sender IDs, follow the instructions here to request one and enable it in your account.

Origination number

If your country does not support sender IDs, you must purchase an origination number.

In Pinpoint, scroll to Number settings and click on Request phone number. This will bring you to a page where you can obtain a Toll-free number for sending SMS messages. Choose the country from which you'll be sending SMS messages, then follow the prompts for requesting a new number.

After successfully requesting a toll-free number, you can return to SNS to verify your phone number.

Verify a Phone Number

Return to SNS, and scroll to the Sandbox destination phone numbers section. Click Add phone number and follow the instructions to verify your phone number.

You are now ready to setup auth for OTP.

Setup

$ amplify add auth

? 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?
# Phone Number
? Do you want to configure advanced settings?
# No, I am done.

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

$ amplify add auth
 
? Do you want to use the default authentication and security configuration?
# Manual configuration

... Answer as appropriate

? Email based user registration/forgot password:
# Disabled (Uses SMS/TOTP as an alternative)
? Please specify an SMS verification message:
# Your verification code is {####}

... Answer as appropriate

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

$ amplify add auth
 
? Do you want to use the default authentication and security configuration?
# Manual configuration

... Answer as appropriate

? Multifactor authentication (MFA) user login options:
# ON (Required for all logins, can not be enabled later)
? For user login, select the MFA types:
# SMS Text Message
? Please specify an SMS authentication message:
# Your authentication code is {####}

... Answer as appropriate

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

$ amplify update auth

? What do you want to do?
# Walkthrough all the auth configurations

... Answer as appropriate

? Email based user registration/forgot password:
# Disabled (Uses SMS/TOTP as an alternative)
? Please specify an SMS verification message:
# Your verification code is {####}

... Answer as appropriate

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

$ amplify update auth

? What do you want to do?
# Walkthrough all the auth configurations

... Answer as appropriate

? Multifactor authentication (MFA) user login options:
# OPTIONAL (Individual users can use MFA)
? For user login, select the MFA types:
# SMS Text Message
? Please specify an SMS authentication message:
# Your authentication code is {####}

... Answer as appropriate

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

Sign Up

Sign up users normally with the chosen Username type and password. Certain attributes may be required in the userAttributes map depending on the options chosen above:

• "email" is required if:
  • One of the following are true:
    • Email verification is enabled (default)
    • Email was marked as a required attribute (default)
  • and users sign up with a chosen username or phone number
• "phone_number" is required if:
  • One of the following are true:
    • MFA is ON, or manually enabled for the user
    • Phone number verification is enabled
    • Phone number was marked as a required attribute
  • and users sign up with a chosen username or email

func signUpUser(
    username: String,
    password: String
) async throws {

    var userAttributes = [
        AuthUserAttribute(.email, value: "test@example.com"),
        AuthUserAttribute(.phoneNumber, value: "+18885551234")
    ]

    let options = AuthSignUpRequest.Options(
        userAttributes: userAttributes)
    let result = try await Amplify.Auth.signUp(
        username: username,
        password: password,
        options: options)

    print("Sign up next step: \(result.nextStep)")
}

Verification of user accounts is done via the confirmSignUp method with the OTP sent to their phone or email.

func confirmSignUpPhoneVerification(
    username: String,
    otpCode: String
) async throws {

    let result = try await Amplify.Auth.confirmSignUp(
        for: username,
        confirmationCode: otpCode
    )

    print("Sign up complete: \(result.isSignUpComplete)")
}

Sign In

Sign in users normally with the chosen Username type and password.

func signIn(username: String, password: String) async {
    do {
        let signInResult = try await Amplify.Auth.signIn(
            username: username,
            password: password
        )

        if case .confirmSignInWithSMSMFACode(let deliveryDetails, let info) = signInResult.nextStep {
            print("SMS code send to \(deliveryDetails.destination)")
            print("Additional info \(String(describing: info))")

            // Prompt the user to enter the SMSMFA code they received
            // Then invoke `confirmSignIn` api with the code
        }
    } catch let error as AuthError {
        print("Sign in failed \(error)")
    } catch {
        print("Unexpected error: \(error)")
    }
}

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)")
    }
}