Add MFA Phone Number to an ID Token Claim

Knowledge Articles
, ,
1

Overview

This article details how to add the phone number (including the country code) of an MFA enrollment to an ID token claim.

Applies To

  • Multifactor Authentication (MFA)
  • SMS-based MFA

Solution

Follow these steps to retrieve MFA enrollment information and add it to the ID token:

  1. Disable phone number obfuscation
    First, disable phone number obfuscation by patching the tenant flags using the management API:
    PATCH https://<domain>/api/v2/tenants/settings
Content-Type: application/json
Authorization: Bearer <management API token>

{
  "flags": {
    "disable_management_api_sms_obfuscation": true
  }
}

This setting allows SMS phone numbers to be visible in the management API response.

  1. Create an action
    Create a post-login action to retrieve the phone number via the management API and add it to the ID token claim.

    Here is an example:

const axios = require('axios');

exports.onExecutePostLogin = async (event, api) => {
    try {
        const response = await axios.get(
          `https://${event.secrets.AUTH0_DOMAIN}/api/v2/users/${event.user.user_id}/enrollments`,
            {
                headers: {
                    Authorization: `Bearer ${event.secrets.MANAGEMENT_API_TOKEN}`
                }
            }
        );

        const smsEnrollment = response.data.find(
            enrollment => enrollment.auth_method === 'sms' && enrollment.status === 'confirmed'
        )

        if (smsEnrollment && smsEnrollment.phone_number) {
            api.idToken.setCustomClaim('phone_number', smsEnrollment.phone_number);
        }
    } catch (error) {
        console.log('Error retrieving enrollment:', error);
    }
};

  1. Configure secrets
    Add the following secrets to the action:

    • AUTH0_DOMAIN: The Auth0 domain name
    • MANAGEMENT_API_TOKEN: A Management API access token with the necessary permissions

    NOTE: The management API token must have the scope read:users.

    Also, since the secret value is limited to 2048 bytes, we recommend creating a separate machine-to-machine application specifically for the action and granting only the read:users scope to minimize the size of the access token.

  2. Retrieve the phone number from the ID token
    The phone number (including country code) will now be available in the ID token as a custom claim named phone_number.