Define a Microsoft Entra ID multifactor authentication technical profile in an Azure AD B2C custom policy

  • Article

Azure Active Directory B2C (Azure AD B2C) provides support for verifying a phone number by using a verification code.

Protocol

The Name attribute of the Protocol element needs to be set to Proprietary. The handler attribute must contain the fully qualified name of the protocol handler assembly that is used by Azure AD B2C:

Web.TPEngine.Providers.AzureMfaProtocolProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null

The following example shows a Microsoft Entra ID multifactor authentication technical profile:

<TechnicalProfile Id="AzureMfa-SendSms">
    <DisplayName>Send Sms</DisplayName>
    <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.AzureMfaProtocolProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
    ...

Verify phone mode

In the verify phone mode, the technical profile generates and sends a code to a phone number, and then verifies the code. The Microsoft Entra ID multifactor authentication technical profile may also return an error message. The validation technical profile validates the user-provided data before the user journey continues. With the validation technical profile, an error message displays on a self-asserted page. The technical profile:

  • Doesn't provide an interface to interact with the user. Instead, the user interface is called from a self-asserted technical profile, or a display control as a validation technical profile.
  • Uses the Microsoft Entra multifactor authentication service to generate and send a code to a phone number, and then verifies the code.
  • Validates a phone number via text messages.

The technical profile provides methods to send the verification code via SMS text message, and verify the code. The following screenshot shows the phone verifier flow.

Screenshot showing TOTP flow

Send SMS

To verify a phone, the first step generates a code and sends it to the phone number. The following options can be configured for this step.

Input claims

The InputClaims element contains a list of claims to send to Microsoft Entra multifactor authentication. You can also map the name of your claim to the name defined in the MFA technical profile.

ClaimReferenceId Required Description
userPrincipalName Yes The identifier for the user who owns the phone number.
phoneNumber Yes The phone number to send an SMS code to.
companyName No The company name in the SMS. If not provided, the name of your application is used.
locale No The locale of the SMS. If not provided, the browser locale of the user is used.

Output claims

The Microsoft Entra multifactor authentication protocol provider doesn't return any output claims, so there's no need to specify output claims.

Metadata

The Metadata element contains the following attribute.

Attribute Required Description
Operation Yes Must be OneWaySMS.
UI elements

The following metadata can be used to configure the error messages displayed upon sending SMS failure. The metadata should be configured in the self-asserted technical profile. The error messages can be localized.

Attribute Required Description
UserMessageIfCouldntSendSms No User error message if the phone number provided does not accept SMS.
UserMessageIfInvalidFormat No User error message if the phone number provided is not a valid phone number.
UserMessageIfServerError No User error message if the server has encountered an internal error.
UserMessageIfThrottled No User error message if a request has been throttled.

Example: send an SMS

The following example shows a Microsoft Entra ID multifactor authentication technical profile that is used to send a code via SMS.

<TechnicalProfile Id="AzureMfa-SendSms">
  <DisplayName>Send Sms</DisplayName>
  <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.AzureMfaProtocolProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
  <Metadata>
    <Item Key="Operation">OneWaySMS</Item>
  </Metadata>
  <InputClaimsTransformations>
    <InputClaimsTransformation ReferenceId="CombinePhoneAndCountryCode" />
    <InputClaimsTransformation ReferenceId="ConvertStringToPhoneNumber" />
  </InputClaimsTransformations>
  <InputClaims>
    <InputClaim ClaimTypeReferenceId="userPrincipalName" />
    <InputClaim ClaimTypeReferenceId="fullPhoneNumber" PartnerClaimType="phoneNumber" />
  </InputClaims>
</TechnicalProfile>

Verify code

The verify code step verifies a code sent to the user. The following options can be configured for this step.

Input claims

The InputClaims element contains a list of claims to send to Microsoft Entra multifactor authentication. You can also map the name of your claim to the name defined in the MFA technical profile.

ClaimReferenceId Required Description
phoneNumber Yes Same phone number as previously used to send a code. It is also used to locate a phone verification session.
verificationCode Yes The verification code provided by the user to be verified

Output claims

The Microsoft Entra multifactor authentication protocol provider doesn't return any output claims, so there's no need to specify output claims.

Metadata

The Metadata element contains the following attribute.

Attribute Required Description
Operation Yes Must be Verify.
UI elements

The following metadata can be used to configure the error messages displayed upon code verification failure. The metadata should be configured in the self-asserted technical profile. The error messages can be localized.

Attribute Required Description
UserMessageIfMaxAllowedCodeRetryReached No User error message if the user has attempted a verification code too many times.
UserMessageIfServerError No User error message if the server has encountered an internal error.
UserMessageIfThrottled No User error message if the request is throttled.
UserMessageIfWrongCodeEntered No User error message if the code entered for verification is wrong.

Example: verify a code

The following example shows a Microsoft Entra ID multifactor authentication technical profile used to verify the code.

<TechnicalProfile Id="AzureMfa-VerifySms">
    <DisplayName>Verify Sms</DisplayName>
    <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.AzureMfaProtocolProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
    <Metadata>
        <Item Key="Operation">Verify</Item>
    </Metadata>
    <InputClaims>
        <InputClaim ClaimTypeReferenceId="phoneNumber" PartnerClaimType="phoneNumber" />
        <InputClaim ClaimTypeReferenceId="verificationCode" />
    </InputClaims>
</TechnicalProfile>

Next steps