I wrote before a post about B2C in general, how to use our own custom domain thru Azure Front door and how to use custom policies.
I prefer that you read these out to get clearer picture of B2C functionality. There is still lot more to cover but it’s a start.
So, now you know it all, right? Maybe not but you should. B2C is a really powerful tool for external multi-tenant, single-tenant application publishing and can be used with Social accounts also.
But now to the main topic of this post.
B2C TOTP (Time-based One-time Password)
Why to use?
Integrating a time-based OTP with an authenticator app as a second factor in B2C scenarios user flows enables a higher level of security compared to existing email and phone factors.
OTP was already enabled for majority of tenants in January 2022
What is the difference with OTP and TOTP?
In order to authenticate a transaction or grant access to an account, a one-time password (OTP) is generated at random and sent to the registered phone number or email on file with the recipient. OTPs typically last between 5 and 10 minutes, as opposed to a TOTP, which is only valid for 30 to 60 seconds. A TOTP is produced in a mobile app instead of being delivered to you like an OTP is.
What is TOTP?
OATH TOTP (Time-based One Time Password) is an open standard that specifies how one-time password (OTP) codes are generated. OATH TOTP can be implemented using either software or hardware to generate the codes.
OATH software tokens
Software OATH tokens are typically applications such as the Microsoft Authenticator app and other authenticator apps. Azure AD generates the secret key, or seed, that’s input into the app and used to generate each OTP.
The Authenticator app automatically generates codes when set up to do push notifications so a user has a backup even if their device doesn’t have connectivity. Third-party applications that use OATH TOTP to generate codes can also be used.
How to enable TOTP with custom policies?
Set multifactor authentication
To enable multifactor authentication, get the custom policy starter pack from GitHub as follows:
- Download the .zip file or clone the repository from
https://github.com/Azure-Samples/active-directory-b2c-custom-policy-starterpack, and then update the XML files in the SocialAndLocalAccountsWithMFA starter pack with your Azure AD B2C tenant name. The SocialAndLocalAccountsWithMFA enables social and local sign in options, and multifactor authentication options, except for the Authenticator app – TOTP option.
- To support the Authenticator app – TOTP MFA option, download the custom policy files from
https://github.com/azure-ad-b2c/samples/tree/master/policies/totp, and then update the XML files with your Azure AD B2C tenant name. Make sure to include
TrustFrameworkBase.xmlXML files from the SocialAndLocalAccounts starter pack.
- Update your [page layout] to version
2.1.14. For more information, see Select a page layout.
In this mode, the user is required to install any authenticator app that supports time-based one-time password (TOTP) verification, such as the Microsoft Authenticator app, on a device that they own.
During the first sign-up or sign-in, the user scans a QR code, opens a deep link, or enters the code manually using the authenticator app. To verify the TOTP code, use the Begin verify OTP followed by Verify TOTP validation technical profiles.
For subsequent sign-ins, use the Get available devices method to check if the user has already enrolled their device. If the number of available devices is greater than zero, this indicates the user has enrolled before. In this case, the user needs to type the TOTP code that appears in the authenticator app.
- Doesn’t provide an interface to interact with the user. Instead, the user interface is called from a self-asserted technical profile, with the TOTP display controls.
- Uses the Azure AD MFA service to validate the TOTP code.
- Checks if a user has already enrolled their device.
The get available device mode checks the number of devices available for the user. If the number of available devices is zero, this indicates the user hasn’t enrolled yet.
To enable TOTP within your custom policy, use the following display controls:
- totpQrCodeControl – Render the QR code and a deep link. When the user scans the QR code or opens the deep link, the authenticator app opens so the user can complete the enrollment process.
- AuthenticatorAppIconControl – Render the Microsoft Authenticator app icon with a link to download the app to the user’s mobile device.
- AuthenticatorInfoControl – Render the TOTP introduction.
Add these to your TrustFrameworkExtensions xml-file under Technical profile
<!-- Render the QR code by taking the URI (qrCodeContent) input claim and rendering it as a QR code-->
<DisplayControl Id="totpQrCodeControl" UserInterfaceControlType="QrCodeControl">
<InputClaim ClaimTypeReferenceId="qrCodeContent" />
<DisplayClaim ClaimTypeReferenceId="qrCodeContent" ControlClaimType="QrCodeContent" />
<!-- Render the TOTP information by taking the totpIdentifier and the secretKey input claims and rendering them in plain text-->
<DisplayControl Id="authenticatorInfoControl" UserInterfaceControlType="AuthenticatorInfoControl">
<InputClaim ClaimTypeReferenceId="totpIdentifier" />
<InputClaim ClaimTypeReferenceId="secretKey" />
<DisplayClaim ClaimTypeReferenceId="totpIdentifier" />
<DisplayClaim ClaimTypeReferenceId="secretKey" />
<!-- Render the authenticator apps icon. -->
<DisplayControl Id="authenticatorAppIconControl" UserInterfaceControlType="AuthenticatorAppIconControl" />
The display controls are referenced from a self-asserted technical profile. The self-asserted technical profile uses input claims transformation to prepare the required
secretKey input claims.
The input claims transformations must be called in the following order:
CreateSecretclaims transformation type of CreateOtpSecret. The claims transformation creates a TOTP secret key. This key is later stored in the user’s profile in Azure AD B2C, and is shared with the authenticator app. The authenticator app uses the key to generate a TOTP code the user needs to go through MFA. Your custom policy uses the key to validate the TOTP code provided by the user.
CreateIssuerclaims transformation type of CreateStringClaim. The claims transformation creates the TOTP issuer name. The issuer name is your tenant name, such as “Contoso demo”.
CreateUriLabelclaims transformation type of FormatStringMultipleClaims. The claims transformation creates the TOTP URI label. The label is a combination of the user’s unique identifier, such as email address, and the issuer name, for example,
CreateUriStringclaims transformation type of BuildUri. The claims transformation creates the TOTP URI string. The string is a combination of the URI label and the secret key, for example,
otpauth://totp/Contoso%20demo:firstname.lastname@example.org?secret=fay2lj7ynpntjgqa&issuer=Contoso+demo. This URI label is rendered by the display control in a QR code format and a deep link.
Add also these to your TrustFrameworkExtensions xml-file under Technical profile
<DisplayName>Sign up with Authenticator app</DisplayName>
<Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.SelfAssertedAttributeProvider, Web.TPEngine, Version=220.127.116.11, Culture=neutral, PublicKeyToken=null" />
<Key Id="issuer_secret" StorageReferenceId="B2C_1A_TokenSigningKeyContainer" />
<InputClaimsTransformation ReferenceId="CreateSecret" />
<InputClaimsTransformation ReferenceId="CreateIssuer" />
<InputClaimsTransformation ReferenceId="CreateUriLabel" />
<InputClaimsTransformation ReferenceId="CreateUriString" />
<InputClaim ClaimTypeReferenceId="qrCodeContent" />
<InputClaim ClaimTypeReferenceId="secretKey" />
<DisplayClaim DisplayControlReferenceId="authenticatorAppIconControl" />
<DisplayClaim ClaimTypeReferenceId="QrCodeScanInstruction" />
<DisplayClaim DisplayControlReferenceId="totpQrCodeControl" />
<DisplayClaim DisplayControlReferenceId="authenticatorInfoControl" />
<OutputClaim ClaimTypeReferenceId="objectId" />
<OutputClaim ClaimTypeReferenceId="secretKey" />
<UseTechnicalProfileForSessionManagement ReferenceId="SM-MFA-TOTP" />
How to setup in Azure AD?
You can do it with Conditional access. See below how to use CA policies and enable MFA.
Authenticator app – TOTP – The user must install an authenticator app that supports time-based one-time password (TOTP) verification, such as the Microsoft Authenticator app, on a device that they own. During the first sign-up or sign-in, the user scans a QR code or enters a code manually using the authenticator app. During subsequent sign-ins, the user types the TOTP code that appears on the authenticator app. See how to set up the Microsoft Authenticator app.
At first login you will be displayed for the old style “more information required” box. And you will add other account to Authenticator.
Once you are done the user journey will ask for the code in your Authenticator app.
And you will be able to login.
B2C user auth methods
Once it’s enabled you will see the software TOTP under users authentication methods.
How to access methods thru API?
|List softwareOathMethods||softwareOathAuthenticationMethod collection||Retrieve a list of a user’s softwareOathAuthenticationMethod objects and their properties.|
|Get softwareOathAuthenticationMethod||softwareOathAuthenticationMethod||Read the properties of a user’s softwareOathAuthenticationMethod object.|
|Delete softwareOathAuthenticationMethod||None||Delete a user’s softwareOathAuthenticationMethod object.|
Most of the time it’s easier to do it programmatically than via Azure portal.
If you want to learn more from Microsoft Graph and the transition from old PowerShell modules, see post below.
Why not to use SMS and Phone for verification?
Alex Weinert wrote an excellent blog back in 2020
Like he says in the blog “Hang up on PSTN and pick up the Microsoft Authenticator – your users will be happier and more secure because you did.”