Vonage

Verify users by reaching their mobile device with SMS or voice codes: easily adding a layer of security. We designed the Verify API to make it simple to implement. Your application simply gives us a phone number and we take care of the rest. We've got you covered for SMS, voice, and SMS to voice failover scenarios. We even make sure the messages comply with local regulations so they are not filtered by the carriers. Our comprehensive backend provides the secure code and identity management capabilities, all behind a simple to use API.

Our many direct-to-carrier relationships around the world, combined with our proprietary Adaptive Routing algorithm, allow us to work in real-time to find the best routes for your messages. Add to that our Compliance Engine, which knows how and when to deliver messages according to country and carrier requirements, and you have the industry’s highest deliverability rates.

You can send multi-factor authentication (MFA) text messages using the Vonage (previously Nexmo) SMS API. Vonage provides an SMS API that can be used by Auth0 to deliver multi-factor verification via text messages. To learn more, see Vonage's SMS API 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 with Vonage and complete your profile and confirmation steps.
• Go to the SMS API screen of the Vonage dashboard and test the API with a test number. Once you've successfully tested the SMS API and can receive a text message, you're ready to integrate with Auth0.

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 the Twilio console above:

• VONAGE_API_KEY
• VONAGE_API_SECRET
• VONAGE_FROM_NUMBER

Include the nexmo module

The Hook uses the Nexmo Client Library for Node.js, so you'll need to include this package in your Hook.

Next, you'll need to include the nexmo module in your hook.

1. Click the Settings icon again, and select NPM Modules.

2. Search for nexmo and add the module that appears.

Add the Vonage API call

To make the call to the Vonage API, add the appropriate code to the Hook. Copy the code block below and paste it into the Hooks code editor. This function will run each time a user requires MFA, calling the Vonage API to send a verification code via SMS.

1. Copy the code block below and paste it into the Hooks code editor. This function will run each time a user requires MFA, calling the Vonage API to send a verification code via SMS.

module.exports = function(toNumber, text, context, cb) {
  const Nexmo = require('nexmo');
  const nexmo = new Nexmo({
    apiKey: context.webtask.secrets.VONAGE_API_KEY,
    apiSecret: context.webtask.secrets.VONAGE_API_SECRET,
  });

  const fromNumber = context.webtask.secrets.VONAGE_FROM_NUMBER;
  toNumber = toNumber.replace(/\D/g, '');

  nexmo.message.sendSms(fromNumber, toNumber, text, (err, responseData) => {
    if (err) {
      return cb(err);
    }

    const firstMsg = responseData.messages[0];
    if (firstMsg['status'] !== '0') {
      return cb(new Error('Message failed: ' + firstMsg['error-text']));
    }

    return cb(null, {});
  });
};

Test hook implementation

Click the Runner button to try the completed Hook. Make sure to change the recipient value in the body to your test number from the Vonage API. You should receive a test text message, and the webtask should complete successfully.

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:

• Check the Vonage SMS API logs for a sent message and check its status. If there is no record of the message with Vonage, then the API call likely failed and the problem is in the Hook code.
• The Hook is active and the SMS configuration is set to use Custom.
• You have configured the hook secrets.
• The configured hook secrets are the same ones you created in the Vonage dashboard.
• Your phone number is formatted using the E.164 format.