Use Auth0's Unified Phone Experience for Multi-Factor Authentication

The Unified Phone Experience centralizes all your phone provider configurations in one location in your tenant. You won’t need to configure a phone provider multiple times for various phone authentication factors. To learn more about phone factors for MFA, read SMS and voice notifications for MFA.

If you already have a phone provider configured for Multi-Factor Authentication (MFA), you can migrate your configuration to the Unified Phone Experience and apply your configuration at the tenant-level.

To use the Unified Phone Experience, you need to:

• Verify current settings

• Configure your provider:

  • Configure Twilio

  • Configure a custom phone provider

• Update your phone factors and delivery methods

• Update Management API endpoints

• Update Auth0 Actions triggers

1. To verify your current MFA settings, navigate to Auth0 Dashboard > Security > Multi-factor Auth.

2. Select Phone Message.

3. If you are able to use the Unified Phone Experience, a banner advises you to configure a tenant-level provider:

   

If you are using Twilio as your phone provider for Multi-Factor Authentication, you must add the Twilio SID and AuthToken to the Unified Phone Experience. You can copy the Twilio SID from your existing configuration, but you will need to get the value of the AuthToken from Twilio.

1. Navigate to Branding > Phone Provider.

2. Select and configure your provider:

   

   1. Choose Twilio as your phone provider.

   2. Choose your delivery methods.

   3. Enter Twilio settings.

      Desired MFA factors must be a subset of the delivery methods you configure at the tenant-level.

3. Save your changes.

4. Select Send Test Message to test the tenant-level provider before using it in a production environment.

5. Enable a tenant-level provider.

   1. For MFA, navigate to Security > Multi-factor Auth > Phone Message.

   2. Select Use Tenant-level Messaging Provider.

      If no toggle exists in your tenant, you are already using the Unified Phone experience.

6. Save your changes.

The Unified Phone Experience uses the custom-phone-provider Actions Trigger for phone notifications rather than the send-phone-message Actions Trigger for custom phone notifications.

You cannot directly migrate your send-phone-message Actions trigger to the custom-phone-provider Actions trigger because:

• There is no 1:1 mapping between message and notification types.

• Migrating secrets and dependencies associated with the send-phone-message Actions trigger could cause security concerns or break the tenant experience.

• Actions can support more than one trigger and could be difficult to migrate. For example, Actions can support both the send-phone-message and post-login triggers.

• The send-phone-message and custom-phone-provider Actions triggers support different event types:

  • send-phone-message supports the SMS and Voice message types. To learn more, read Action triggers: send-phone-message Event Object.

  • custom-phone-provider supports the otp_verify, otp_enroll, blocked_account, change_password, and password_breach notification types. To learn more, read Actions triggers: custom-phone-provider Event Object.

• You can only set one Action per custom phone provider. If you have already set an Action for a custom phone provider, you must disable it before associating it with a new Action.

As a result, you need to translate your existing send-phone-message into a new custom-phone-provider using the new contextual variables:

Review the custom phone provider example:

const { fetch } = require('undici');
/**
* Handler to be executed while sending a phone notification
* @param {Event} event - Details about the user and the context in which they are logging in.
* @param {CustomPhoneProviderAPI} api - Methods and utilities to help change the behavior of sending a phone notification.
*/
exports.onExecuteCustomPhoneProvider = async (event, api) => {

  if (event.notification.message_type.startsWith('otp')) {
    const body = {
      from: event.notification.from,
      action: event.notification.message_type === 'otp_verify' ? 'second-factor-authenticator' : 'enrollment',
      language: event.notification.locale,
      recipient: event.notification.recipient,
      message_type: event.notification.delivery_method,
      text: event.notification.as_text,
      code: event.notification.code,
    };

    const response = await fetch(event.secrets['MY_ENDPOINT'], {
      method: 'POST',
      headers: {
        authorization: `Bearer ${event.secrets['MY_SECRET']}`,
      },
      body: JSON.stringify(body),
    });

    console.log(response.status); // 200
    console.log(await response.text()); // request's response body!
  }

  return;
};

To continue and configure your MFA custom-phone-provider trigger:

1. Navigate to Branding > Phone Provider.

2. Select your provider:

   1. Choose Custom.

   2. Under Provider Configuration, add your translated send-phone-message Action code in the embedded code editor.

3. Save your changes.

4. Select Send Test Message to test the tenant-level provider before using it in a production environment.

5. Navigate back to Security > Multi-factor Auth > Phone Message to enable the Use Tenant-level Messaging Provider.

6. Save your changes.

If you have not enabled a tenant-level provider in the Auth0 Dashboard, you won’t be able to configure phone SMS and voice phone factors for MFA.

If you want to update the current notification MFA factor(s) to a different type during the migration to the Unified Phone Experience, some configuration changes may be necessary.

If you want to update the current tenant-level phone provider delivery method(s) to a different type during the migration to the Unified Phone Experience, some configuration changes may be necessary.

The Unified Phone Experience uses specific endpoints for notifications. If you’ve been using Auth0 Guardian for push notifications and one-time passwords, you must update your configuration to use the new Phone Provider Branding endpoints.

The following Guardian endpoints will no longer work with the Unified Phone Experience:

Replace the Guardian endpoints with the new Phone Provider Branding endpoints and scopes:

The following Guardian endpoints work with the Unified Phone Experience and will not need to be updated:

If you configure the Unified Phone Experience and then disable it, existing integrations with your phone provider, including MFA, could break.