Changes coming to AWS Amplify’s SMS-based authentication workflows

Starting June 1, 2021, US telecom carriers require that you register an origination phone number before you can send SMS messages to US phone numbers.

As a consequence of this new requirement, when you use AWS Amplify to enable SMS-based authentication workflows for your U.S. based app users after June 1st, you must now register an origin phone number with Amazon Pinpoint. Once registered, Amplify will detect this phone number automatically. If you do not register an origination phone number, your app users might not receive the SMS messages they need to sign up, activate their accounts, or sign in.

In addition, if you enable authentication workflows after June 1st, 2021, you may find your account to be in the Amazon Simple Notification Service (SNS) SMS sandbox environment. With support for the SMS sandbox from Amazon SNS, as a new Amplify customer, you can perform development and testing activities involving SMS text messages for your application with verified recipient phone numbers. You can take steps to comply with country-specific requirements, purchase required resources like Sender ID or origination phone numbers, and secure the SMS throughput needed for your application, before your solution is deployed for general use.

Am I affected by this change?

If you already use a dedicated toll-free number (TFN), ten-digit long code (10DLC), or a short code configured via the Amazon Pinpoint console to send SMS to US recipient phone numbers, then you’re not affected by this change.

Additionally, as of June 1, 2021, if you’ve used SMS-based auth workflows within the last 6 months but do not have a dedicated phone number, we have allocated one dedicated toll-free number (TFN) to your account to comply with US carrier requirements.

How do I verify that my account is correctly configured for SMS-based auth workflows?

Your app backend is correctly configured for SMS-based auth workflows if

1. your account has been upgraded to production status in Amazon SNS console
2. if you have users in the U.S., you need an SMS-enabled US origination phone number listed in Amazon Pinpoint console and

Verify that the origination phone number listed in Amazon Pinpoint Console has the appropriate message throughput for your app. Review how to request a number and which number is best for you in the Amazon Pinpoint documentation.

How do I configure SMS-based authentication workflows with AWS Amplify starting June 1st, 2021?

This change is not going to affect your app’s frontend client code. It’ll only affect the backend configuration. AWS Amplify provides two main mechanisms to configure your auth backend: Amplify CLI and Amplify Admin UI.

Configuring auth using the Amplify Admin UI

1. In the Admin UI, first select “Authentication” from the left-hand navigation bar, then configure SMS-based auth workflows, such as signing in using a phone number.
2. The Amplify Admin UI will auto-detect if you have an appropriate origination phone number. If you don’t have one, the Admin UI will prompt you to request a new phone number via the Amazon Pinpoint console.
3. Click “Save and deploy” to deploy your authentication backend.
   
4. Add a verified phone number to your account via the Admin UI to allowlist SMS recipients. Remember: when your account is in the SMS sandbox environment, only verified phone numbers can receive SMS messages.
   
5. Integrate the Amplify Libraries into your frontend to configure authentication workflows with verified phone numbers. Review how to set up sign-in, sign-up, and other auth workflows as outlined in the Amplify Library documentation.
6. Once ready, request a move of out of SMS sandbox to send SMS messages globally to unverified destination phone numbers. Click the “Request move to production” button from Admin UI’s Authentication page or refer to Moving out of the SMS sandbox in the Amazon SNS Developer Guide.
   

Configuring auth using Amplify CLI

1. Make sure you’re running the latest version of Amplify CLI by running amplify upgrade or npm install -g @aws-amplify/cli.
2. In your Amplify project folder, run amplify add auth and select any SMS-based auth workflows, such as signing in using phone number.
   
3. If you don’t have an SMS-enabled origination phone number, request a new one in the Amazon Pinpoint Console.
   
4. Run amplify push to deploy your auth backend configuration.
   
5. Add a verified phone number to your SNS account via the SNS console. Remember: as long as your account is in Amazon Simple Notification Service’s sandbox environment, only verified phone numbers can receive SMS messages.
   
6. Integrate the Amplify Libraries into your frontend to configure authentication workflows with verified phone numbers. Review how to set up sign-in, sign-up, and other auth workflows as outlined in the Amplify Library documentation.
7. Once ready, request a move of out of SMS sandbox to send SMS messages globally to unverified destination phone numbers. For more information about exiting the sandbox, refer to Moving out of the SMS sandbox in the Amazon SNS Developer Guide.