Define a one-time password technical profile in an Azure AD B2C custom policy
Note
In Azure Active Directory B2C, custom policies are designed primarily to address complex scenarios. For most scenarios, we recommend that you use built-in user flows. If you've not done so, learn about custom policy starter pack in Get started with custom policies in Active Directory B2C.
Azure Active Directory B2C (Azure AD B2C) provides support for managing the generation and verification of a one-time password. Use a technical profile to generate a code, and then verify that code later.
The one-time password technical profile can also return an error message during code verification. Design the integration with the one-time password by using a Validation technical profile. A validation technical profile calls the one-time password technical profile to verify a code. The validation technical profile validates the user-provided data before the user journey continues. With the validation technical profile, an error message is displayed on a self-asserted page.
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.OneTimePasswordProtocolProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null
The following example shows a one-time password technical profile:
<TechnicalProfile Id="VerifyCode">
<DisplayName>Validate user input verification code</DisplayName>
<Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.OneTimePasswordProtocolProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
...
Generate code
The first mode of this technical profile is to generate a code. Below are the options that can be configured for this mode. Codes generated and attempts are tracked within the session.
Input claims
The InputClaims element contains a list of claims required to send to the one-time password protocol provider. You can also map the name of your claim to the name defined below.
| ClaimReferenceId | Required | Description |
|---|---|---|
| identifier | Yes | The identifier to identify the user who needs to verify the code later. It is commonly used as the identifier of the destination where the code is delivered to, for example email address or phone number. |
The InputClaimsTransformations element may contain a collection of InputClaimsTransformation elements that are used to modify the input claims or generate new ones before sending to the one-time password protocol provider.
Output claims
The OutputClaims element contains a list of claims generated by the one-time password protocol provider. You can also map the name of your claim to the name defined below.
| ClaimReferenceId | Required | Description |
|---|---|---|
| otpGenerated | Yes | The generated code whose session is managed by Azure AD B2C. |
The OutputClaimsTransformations element may contain a collection of OutputClaimsTransformation elements that are used to modify the output claims or generate new ones.
Metadata
The following settings can be used to configure code generation mode:
| Attribute | Required | Description |
|---|---|---|
| Operation | Yes | The operation to be performed. Possible value: GenerateCode. |
| CodeExpirationInSeconds | No | Time in seconds until code expiration. Minimum: 60; Maximum: 1200; Default: 600. Every time a code is provided (same code using ReuseSameCode, or a new code), the code expiration is extended. This time is also used to set retry timeout (once max attempts are reached, user is locked out from attempting to obtain new codes until this time expires) |
| CodeLength | No | Length of the code. The default value is 6. |
| CharacterSet | No | The character set for the code, formatted for use in a regular expression. For example, a-z0-9A-Z. The default value is 0-9. The character set must include a minimum of 10 different characters in the set specified. |
| NumRetryAttempts | No | The number of verification attempts before the code is considered invalid. The default value is 5. For example, if you set NumRetryAttempts to 2 it will allow you only 2 attempts in total (first + 1 retry). For the 3rd attempt it will throw max attempts reached irrespective of whether the code is correct or not. |
| NumCodeGenerationAttempts | No | The number of maximum code generation attempts per identifier. The default value is 10 if not specified. |
| ReuseSameCode | No | Whether the same code should be given rather than generating a new code when given code has not expired and is still valid. The default value is false. |
Example
The following example TechnicalProfile is used for generating a code:
<TechnicalProfile Id="GenerateCode">
<DisplayName>Generate Code</DisplayName>
<Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.OneTimePasswordProtocolProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
<Metadata>
<Item Key="Operation">GenerateCode</Item>
<Item Key="CodeExpirationInSeconds">600</Item>
<Item Key="CodeLength">6</Item>
<Item Key="CharacterSet">0-9</Item>
<Item Key="NumRetryAttempts">5</Item>
<Item Key="NumCodeGenerationAttempts">10</Item>
<Item Key="ReuseSameCode">false</Item>
</Metadata>
<InputClaims>
<InputClaim ClaimTypeReferenceId="identifier" PartnerClaimType="identifier" />
</InputClaims>
<OutputClaims>
<OutputClaim ClaimTypeReferenceId="otpGenerated" PartnerClaimType="otpGenerated" />
</OutputClaims>
</TechnicalProfile>
Verify code
The second mode of this technical profile is to verify a code. Below are the options that can be configured for this mode.
Input claims
The InputClaims element contains a list of claims required to send to the one-time password protocol provider. You can also map the name of your claim to the name defined below.
| ClaimReferenceId | Required | Description |
|---|---|---|
| identifier | Yes | The identifier to identify the user who has previously generated a code. It is commonly used as the identifier of the destination where the code is delivered to, for example email address or phone number. |
| otpToVerify | Yes | The verification code provided by the user. |
The InputClaimsTransformations element may contain a collection of InputClaimsTransformation elements that are used to modify the input claims or generate new ones before sending to the one-time password protocol provider.
Output claims
There are no output claims provided during code verification of this protocol provider.
The OutputClaimsTransformations element may contain a collection of OutputClaimsTransformation elements that are used to modify the output claims or generate new ones.
Metadata
The following settings can be used to code verification mode:
| Attribute | Required | Description |
|---|---|---|
| Operation | Yes | The operation to be performed. Possible value: VerifyCode. |
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 |
|---|---|---|
| UserMessageIfSessionDoesNotExist | No | The message to display to the user if the code verification session has expired. It is either the code has expired or the code has never been generated for a given identifier. |
| UserMessageIfMaxRetryAttempted | No | The message to display to the user if they've exceeded the maximum allowed verification attempts. |
| UserMessageIfMaxNumberOfCodeGenerated | No | The message to display to the user if the code generation has exceeded the maximum allowed number of attempts. |
| UserMessageIfInvalidCode | No | The message to display to the user if they've provided an invalid code. |
| UserMessageIfVerificationFailedRetryAllowed | No | The message to display to the user if they've provided an invalid code, and user is allowed to provide the correct code. |
| UserMessageIfSessionConflict | No | The message to display to the user if the code cannot be verified. |
Example
The following example TechnicalProfile is used for verifying a code:
<TechnicalProfile Id="VerifyCode">
<DisplayName>Verify Code</DisplayName>
<Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.OneTimePasswordProtocolProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
<Metadata>
<Item Key="Operation">VerifyCode</Item>
</Metadata>
<InputClaims>
<InputClaim ClaimTypeReferenceId="identifier" PartnerClaimType="identifier" />
<InputClaim ClaimTypeReferenceId="otpGenerated" PartnerClaimType="otpToVerify" />
</InputClaims>
</TechnicalProfile>
Next steps
See the following article for example of using one-time password technical profile with custom email verification: