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

​

Update your phone provider

• 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

​

Verify current settings

1. To verify your current MFA settings, navigate to Auth0 Dashboard > Security > Multi-factor Auth.
2. Select Phone Message.
3. New Auth0 tenants are able to use the Unified Phone Experience, a banner advises you to configure a tenant phone provider:
   

• Existing tenants prior to March 2025 are able to configure SMS and Voice notificatiosn for Multi-Factor Authentication (MFA) along with the Unified Phone Experience.
  

4. To verify your tenant settings, navigate to Dashboard > Tenant Settings.
5. Select Advanced.
6. Locate Unified Phone Experience.
   
7. Toggle to enable, if needed.

​

Configure Twilio as a tenant-level provider

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.

​

Configure a custom provider with Auth0 Actions

• 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.

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;
};

​

Configure MFA custom-phone-provider

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.

​

Update MFA phone factors and delivery methods

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.

​

Update Guardian endpoints with Management API

​

Disable phone provider