Use the Unified Phone Experience for Passwordless

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 Passwordless, read Passwordless Authentication with SMS.

If you already have a phone provider configured for Passwordless, 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 delivery methods

1. To verify your current Passwordless settings, navigate to Auth0 Dashboard > Authentication > Passwordless > SMS.

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 Passwordless, 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.

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. Navigate to Authentication > Passwordless > SMS.

   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 does not use the custom SMS gateway you configured for Passwordless SMS. You can use the Auth0 Dashboard or Management API to configure a custom phone provider with Auth0 Actions. To learn more, read Configure a Custom Phone Provider.

To configure your Custom SMS Gateway phone configuration via phone provider Action:

1. Navigate to Branding > Phone Provider.

2. Select your provider:

   1. Choose Custom.

   2. Under Provider Configuration, add your new custom-phone-provider Actions that forwards the Passwordless notification to a custom SMS gateway.

3. Save your changes.

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

5. Navigate to Authentication > Passwordless > SMS to enable the Use Tenant-level Messaging Provider.

6. Save your changes.

const request = require('<favorite_http_client>');
/**
* 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) => {
  const notificationType = event.notification.message_type;
  switch (notificationType) {
    case '<passwordless_type>': {
      const req = {
        url: event.secrets.GATEWAY_URL,
        method: 'POST',
        headers: {
          'User-Agent': 'Auth0'
        },
        body: {
          recipient: event.notification.recipient,
          body: event.notification.as_text, // or event.notification.as_voice
          sender: event.notification.from, // TODO: sender is missed we need to check if we want to add it.
          req: event.request || {}, // if not enabled, it will come as undefined
        }
      }
      const response = await request(req);
      console.log(response.statusCode);
      return
    }
    default: {
      // handle other notifications as usual
      return;
    }
  }
};

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