Amazon SNS

Amazon Simple Notification Service (SNS) is a highly available, durable, secure, fully managed pub/sub messaging service that enables you to decouple microservices, distributed systems, and serverless applications. Amazon SNS provides topics for high-throughput, push-based, many-to-many messaging. Using Amazon SNS topics, your publisher systems can fan out messages to a large number of subscriber endpoints for parallel processing, including Amazon SQS queues, AWS Lambda functions, and HTTP/S webhooks. Additionally, SNS can be used to fan out notifications to end users using mobile push, SMS, and email.

You can send multi-factor authentication (MFA) text messages using the Amazon Simple Notification Service (SNS). Amazon Simple Notification Service (SNS) is a pub/sub messaging service that enables Auth0 to deliver multi-factor verification via text messages. To learn more, see the Amazon SNS Overview.

Note: The following steps will add text-message-based MFA to the login flow for the tenant in which you're working. We highly recommend testing this setup on a staging or development server before making the changes to your production login flow.

Prerequisites

• Sign up for Amazon Web Services.
• Capture your Amazon Web Service region.
• Create a new Amazon IAM User with the AmazonSNSFullAccess role.
• Capture the user's access key and secret key details.

Create Send Phone Message Hook

You will need to create a Send Phone Message Hook, which will hold the code and secrets of your custom implementation. You can only have one Send Phone Message Hook active at a time.

Configure hook secrets

Add the following Hook secrets with values from your AWS account:

• AWS_ACCESS_KEY_ID
• AWS_SECRET_ACCESS_KEY
• AWS_REGION

Add AWS SNS API call

To make the call to AWS SNS, add the appropriate code to the hook. Copy one of the code blocks below and edit the Send Phone Message Hook to include it. This function will run each time a user requires MFA, calling AWS SNS to send a verification code via SMS.

// Load the SDK
const AWS = require("aws-sdk");

/**
@param {string} recipient - phone number
@param {string} text - message body
@param {object} context - additional authorization context
@param {string} context.factor_type - 'first' or 'second'
@param {string} context.message_type - 'sms' or 'voice'
@param {string} context.action - 'enrollment' or 'authentication'
@param {string} context.language - language used by login flow
@param {string} context.code - one time password
@param {string} context.ip - ip address
@param {string} context.user_agent - user agent making the authentication request
@param {string} context.client_id - to send different messages depending on the client id
@param {string} context.name - to include it in the SMS message
@param {object} context.client_metadata - metadata from client
@param {object} context.user - To customize messages for the user
@param {function} cb - function (error, response)
*/
module.exports = function(recipient, text, context, cb) {

  const awsSNS = new AWS.SNS({
    apiVersion: "2010-03-31",
    region: context.webtask.secrets.AWS_REGION,
    credentials: new AWS.Credentials(context.webtask.secrets.AWS_ACCESS_KEY_ID, context.webtask.secrets.AWS_SECRET_ACCESS_KEY)
  });

  const params = { Message: text, PhoneNumber: recipient };

  const publishTextPromise = awsSNS
    .publish(params)
    .promise();

  publishTextPromise
    .then(function() {
      cb(null, {});
    })
    .catch(function(err) {
      cb(err);
    });
};

Add the AWS SDK NPM package

The hook uses the AWS SDK for JavaScript in Node.js, so you'll need to include this package in your Hook.

• Click the Settings icon and select NPM Modules.
• Search for aws-sdk and add the module that appears.

Test hook implementation

Click the Run icon on the top right to test the hook. Edit the parameters to specify the phone number to receive the SMS, and click the Run button.

Activate custom SMS factor

To use the SMS factor, your tenant needs to have MFA enabled globally or required for specific contexts using rules. To learn how to enable the MFA feature, see:

• Enable MFA
• Customize MFA

The hook is now ready to send MFA codes. The last steps are to configure the SMS Factor to use the custom code and test the MFA flow.

1. Go to Dashboard > Multifactor Auth and click the SMS factor box.
2. In the modal that appears, select Custom for the SMS Delivery Provider, then make any adjustments you'd like to the templates. Click Save when complete, and close the modal.
3. Enable the SMS factor using the toggle switch.

Test MFA flow

Trigger an MFA flow and verify that everything works as intended.

Troubleshoot

If you do not receive the text message, look at the Hook logs. Look for a failed SMS log entry. To learn which event types to search, see the Log Event Type Code list, or you can use the Filter control to find MFA errors.

Make sure that:

• The Hook is active and the SMS configuration is set to use Custom.
• The configured hook secrets are the same ones you created in the Amazon Web Services portal.
• Your Amazon Web Services user has access to the AmazonSNSFullAccess role.
• Your Amazon Web Services account is active (not suspended).
• Your phone number is formatted using the E.164 format.