Skip to content

Latest commit

 

History

History
138 lines (111 loc) · 5.43 KB

send-phone-message.md

File metadata and controls

138 lines (111 loc) · 5.43 KB
title description toc topics contentType useCase v2
Send Phone Message
Learn how to provide your own code to send phone messages for MFA
true
hooks
extensibility-points
send-phone-message
custom-messaging-gateway
sms
voice
how-to
extensibility-hooks
true

Send Phone Message

If you decide to use SMS or Voice as a factor for Multi-factor Authentication (MFA), you can configure how you want Auth0 to send the messages in the MFA Phone configuration dialog.

If you select the 'Custom' delivery method, you must create a Send Phone Message Hook that will let you write your own code to send the message. This allows you to use whatever messaging provider you want.

Hooks at this extensibility point are blocking (synchronous), which means they execute as part of the trigger's process and will prevent the rest of the Auth0 pipeline from running until the Hook is complete.

::: note The triggerId for the Send Phone Message extensibility point is send-phone-message. To learn how to create Hooks for this extensibility point, see Create New Hooks. :::

To learn about other extensibility points, see Extensibility Points.

Starter code and parameters

When creating a Hook executed at the Send Phone Message extensibility point, you may find the following starter code helpful. Parameters that can be passed into and used by the Hook function are listed at the top of the code sample.

/**
@param {string} recipient - phone number
@param {string} text - message body
@param {object} context - additional authorization context
@param {string} context.message_type - 'sms' or 'voice'
@param {string} context.action - 'enrollment' or 'second-factor-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 {object} context.client - object with details about the Auth0 application
@param {string} context.client.client_id - Auth0 application ID
@param {string} context.client.name - Auth0 application name
@param {object} context.client.client_metadata - metadata from client
@param {object} context.user - object representing the user
@param {string} context.user.user_id - Auth0 user's ID
@param {string} context.user.name - user's name
@param {string} context.user.email - user 'semail
@param {object} context.user.app_metadata - metadata specific to user and application
@param {object} context.user.user_metadata - metadata specific to user
@param {function} cb - function (error, response)
*/
module.exports = function(recipient, text, context, cb) {
 // TODO: Add your code here
  cb(null, {});
};

::: note The callback function (cb) at the end of the sample code signals completion and must be included. :::

Example parameters

This is an example of the parameters:

{
  "recipient": "1-808-555-5555",
  "text": "Here is your one time password: 999111",
  "context": {
    "message_type": "sms",
    "action": "enrollment",
    "language": "en",
    "code": "123456",
    "ip": "127.0.0.1",
    "user_agent": "Mozilla/5.0",
    "client": {
      "client_id": "1235",
      "name": "Test Application",
      "client_metadata": { }
    },
    "user": {
      "user_id": "auth0|test12345",
      "name": "Billie Magnusson",
      "email": "[email protected]",
      "app_metadata": { },
      "user_metadata": { }
    }
  }
}

Starter code response

Once you have customized the Hook code, you can test it using the Runner embedded in the Editor. The Runner simulates a call to the Hook with the appropriate body and response.

<%= include('../_includes/_test_runner_save_warning') %>

When you run a Hook based on the starter code, the response object is:

{
    "MessageID": "998a9ad1-c9b9-4b85-97b1-ac0305aa5532"
}

Localization

The context.language parameter will always have one of the languages configured in the Tenant Settings. Depending on how you trigger the MFA flow, we will calculate which language to use in the following different ways:

  • If you use the MFA API, we will use the Accept-Language header from the request and map it to a tenant language. If the language is not available, we will set the parameter to the tenant default language.

  • If you use the New Universal Login Experience, we will use a combination of the Accept-Language header and the ui_locales parameter, as described in Universal Login Internationalization.

  • If you use the Classic Universal Login Experience, we will set the language to 'N/A'. This is a limitation that will be fixed in upcoming releases.

Examples

Learn how to integrate different messaging providers with the examples below:

Keep Reading