Integrate SMS And TOTP In Azure AD B2C Custom Policy

Azure AD B2C custom policies are XML files that identity developers can use for programming identity tasks. For example, authenticating a user using standard protocols such as OpenID Connect, OAuth or SAML. Custom policies also support REST API calls, which can be useful if you need an extra step to retrieve user claims using the user info endpoint. The Azure AD B2C custom policy starter pack comes with prebuilt policies to get started quickly. In this article I will show you how to integrate both SMS and TOTP multifactor authentication methods (MFA) into these policies. The user will be able to choose between one or the other and save its configuration in Azure AD B2C. During subsequent sign-ins, the user will be asked to authenticate using the configured MFA method.

Table of Contents

Prerequisites

Enabling both SMS and TOTP is an advanced scenario which we will built on top of the custom policies from Microsoft. In order to apply what comes next, I assume you have some level of knowledge and experience. For example, you need to know how to program behavior in these XML files. You also need an Azure AD B2C tenant and know how to deploy the XML files and run the custom policies. I won’t go into these details, so make sure you get to this level first.

When you’re ready, download the custom policy starter pack from GitHub. You can also clone the repository from https://github.com/Azure-Samples/active-directory-b2c-custom-policy-starterpack. Update the XML files in the SocialAndLocalAccountsWithMFA starter pack with your Azure AD B2C tenant name.

After that, download the custom policy files from https://github.com/azure-ad-b2c/samples/tree/master/policies/totp. You need these files to support TOTP. Update the XML files with your Azure AD B2C tenant name. Make sure to include TrustFrameworkExtensions.xml, TrustFrameworkLocalization.xml, and TrustFrameworkBase.xml XML files from the SocialAndLocalAccountsWithMFA starter pack.

Updating phone number causes problems due to incorrect format

The TrustFrameworkBase.xml file contains the PhoneFactor-InputOrVerify technical profile. It uses the PhoneFactorProtocolProvider which provides a user interface to interact with the user to verify, or enroll a phone number. This all works well until you want to update your phone number using the Graph API.

The problem is that the PhoneFactorProtocolProvider returns a verified phone number without space between country prefix and phone number (in Azure Portal it’s +11112223333, but should be +1 1112223333). The verified phone number is then saved in Azure AD B2C. If you ever want to update the phone number, the query for phone number using the Graph API returns an empty array. And if you try to delete the phone number, the Graph API returns a 404.

You can work around this problem by using the AzureMfaProtocolProvider and save the phone number in a custom claim. Read on to find out how this works.

Claim Types, Transformations & Technical Profiles

Claim types function like variables and are used to store values like the chosen MFA method and phone number. Some of these values need to be saved in the user object in Azure AD B2C. You also need to be able to retrieve these values during subsequent sign-ins. For example, after signing-in to check what MFA method the user has chosen. In order to do that, you need to add some technical profiles. Before you can work with these technical profiles, you need claim transformations to provide the correct input.

Add Claim Declarations

The claims declarations shown below are the extra claims you need on top of the claims in the starter pack. Add these claims to the TrustFrameworkExtensions_TOTP.xml. Claims that start with the extension prefix will be saved with the user in Azure AD B2C. The extension_mfaScenario is a custom claim that will hold the value SMS or TOTP. When the user signs in for the first time, he or she is required to choose one of these options. If the user chooses the SMS option, a phone number is also required and will be saved in the extension_mfaPhoneNumber claim. All the other claims are used to store user input and output from claims transformations during execution of the custom policy.

<ClaimType Id="extension_mfaScenario">
    <DisplayName>Select MFA method.</DisplayName>
    <DataType>string</DataType>
    <UserInputType>RadioSingleSelect</UserInputType>
    <Restriction>
        <Enumeration Text="SMS" Value="sms" SelectByDefault="true" />
        <Enumeration Text="TOTP" Value="totp" />
    </Restriction>
</ClaimType>

<ClaimType Id="extension_mfaPhoneNumber">
    <DataType>string</DataType>
    <Mask Type="Simple">XXX-XXX-</Mask>
    <UserInputType>Readonly</UserInputType>
</ClaimType>

<ClaimType Id="mfaSelected">
    <DisplayName>mfaSelected</DisplayName>
    <DataType>boolean</DataType>
</ClaimType>

<ClaimType Id="fullPhoneNumber">
    <DisplayName>Phone number</DisplayName>
    <DataType>phoneNumber</DataType>
    <UserInputType>Readonly</UserInputType>
</ClaimType>

<ClaimType Id="inputPhoneNumber">
    <DisplayName>Phone Number</DisplayName>
    <DataType>string</DataType>
    <UserInputType>TextBox</UserInputType>
</ClaimType>

<ClaimType Id="verificationCode">
    <DisplayName>Verification code</DisplayName>
    <DataType>string</DataType>
    <UserInputType>TextBox</UserInputType>
</ClaimType>

<ClaimType Id="inputCountryCode">
    <DisplayName>Country</DisplayName>
    <DataType>string</DataType>
    <UserHelpText>Country Code</UserHelpText>
    <UserInputType>DropdownSingleSelect</UserInputType>
    <Restriction>
        <Enumeration Text="Australia(+61)" Value="AU" />
        <Enumeration Text="Canada(+1)" Value="CA" />
        <Enumeration Text="France(+33)" Value="FR" />
        <Enumeration Text="Germany(+49)" Value="DE" />
        <Enumeration Text="India(+91)" Value="IN" />
        <Enumeration Text="Netherlands(+31)" Value="NL" SelectByDefault="true" />
        <Enumeration Text="Norway(+47)" Value="NO" />
        <Enumeration Text="United Kingdom(+44)" Value="GB" />
        <Enumeration Text="United States(+1)" Value="US" />
        <Enumeration Text="Sweden(+46)" Value="SE" />
    </Restriction>
</ClaimType>

Add Phone Number Claims Transformations

You need a few claims transformations in order to work with the technical profiles shown in the following chapters. The claims transformations shown below transform a phone number string to the phoneNumber data type and vice versa.

Add these claims transformations to the TrustFrameworkExtensions_TOTP.xml.

<ClaimsTransformation Id="ConvertStringToPhoneNumber" TransformationMethod="ConvertStringToPhoneNumberClaim">
    <InputClaims>
        <InputClaim ClaimTypeReferenceId="extension_mfaPhoneNumber" TransformationClaimType="phoneNumberString" />
    </InputClaims>
    <OutputClaims>
        <OutputClaim ClaimTypeReferenceId="fullPhoneNumber" TransformationClaimType="outputClaim" />
    </OutputClaims>
</ClaimsTransformation>

<ClaimsTransformation Id="ConvertStringToPhoneNumberWithCountryCode" TransformationMethod="ConvertStringToPhoneNumberClaim">
    <InputClaims>
        <InputClaim ClaimTypeReferenceId="inputPhoneNumber" TransformationClaimType="phoneNumberString" />
        <InputClaim ClaimTypeReferenceId="inputCountryCode" TransformationClaimType="country" />
    </InputClaims>
    <OutputClaims>
        <OutputClaim ClaimTypeReferenceId="fullPhoneNumber" TransformationClaimType="outputClaim" />
    </OutputClaims>
</ClaimsTransformation>

<ClaimsTransformation Id="ConvertPhoneNumberToString" TransformationMethod="ConvertPhoneNumberClaimToString">
    <InputClaims>
        <InputClaim ClaimTypeReferenceId="fullPhoneNumber" TransformationClaimType="phoneNumber" />
    </InputClaims>
    <OutputClaims>
        <OutputClaim ClaimTypeReferenceId="extension_mfaPhoneNumber" TransformationClaimType="phoneNumberString" />
    </OutputClaims>
</ClaimsTransformation>

Add Technical Profile: Create Full Phone Number

After a user has configured the SMS MFA method, the phone number is saved as a string in Azure AD B2C. The next time the user signs in, this phone number is retrieved from Azure AD B2C. In order to work with the other technical profiles, this string value needs to be transformed to a phoneNumber data type. The technical profile shown below transforms the extension_mfaPhoneNumber to a phoneNumber data type. It does so using the ConvertStringToPhoneNumber claims transformation. This technical profile is called by orchestration step three in the MultiFactorSubJourney.