Upraviť

Zdieľať cez

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

  • Článok

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 verifying an email address for self-service password reset (SSPR). Use the Microsoft Entra ID SSPR technical profile to generate and send a code to an email address, and then verify the code. The Microsoft Entra ID SSPR 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.

This 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 SSPR service to generate and send a code to an email address, and then verifies the code.
  • Validates an email address via 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.AadSsprProtocolProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null

The following example shows a Microsoft Entra ID SSPR technical profile:

<TechnicalProfile Id="AadSspr-SendCode">
  <DisplayName>Send Code</DisplayName>
  <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.AadSsprProtocolProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
    ...

Send email

The first mode of this technical profile is to generate a code and send it. The following options can be configured for this mode.

Input claims

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

ClaimReferenceId Required Description
emailAddress Yes The identifier for the user who owns the email address. The PartnerClaimType property of the input claim must be set to emailAddress.

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 Microsoft Entra SSPR service.

Output claims

The Microsoft Entra SSPR protocol provider does not return any OutputClaims, thus there is no need to specify output claims. You can, however, include claims that aren't returned by the Microsoft Entra SSPR protocol provider as long as you set the DefaultValue attribute.

The OutputClaimsTransformations element may contain a collection of OutputClaimsTransformation elements that are used to modify the output claims or generate new ones.

Metadata

Attribute Required Description
Operation Yes Must be SendCode.

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
UserMessageIfInternalError 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 email

The following example shows a Microsoft Entra ID SSPR technical profile that is used to send a code via email.

<TechnicalProfile Id="AadSspr-SendCode">
  <DisplayName>Send Code</DisplayName>
  <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.AadSsprProtocolProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
  <Metadata>
    <Item Key="Operation">SendCode</Item>
  </Metadata>
  <InputClaims>
    <InputClaim ClaimTypeReferenceId="email" PartnerClaimType="emailAddress"/>
  </InputClaims>
</TechnicalProfile>

Verify code

The second mode of this technical profile is to verify a code. The following options can be configured for this mode.

Input claims

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

ClaimReferenceId Required Description
emailAddress Yes Same email address as previously used to send a code. It is also used to locate an email verification session. The PartnerClaimType property of the input claim must be set to emailAddress.
verificationCode Yes The verification code provided by the user to be verified. The PartnerClaimType property of the input claim must be set to verificationCode.

The InputClaimsTransformations element may contain a collection of InputClaimsTransformation elements that are used to modify the input claims or generate new ones before calling the Microsoft Entra SSPR service.

Output claims

The Microsoft Entra SSPR protocol provider does not return any OutputClaims, thus there is no need to specify output claims. You can, however, include claims that aren't returned by the Microsoft Entra SSPR protocol provider as long as you set the DefaultValue attribute.

The OutputClaimsTransformations element may contain a collection of OutputClaimsTransformation elements that are used to modify the output claims or generate new ones.

Metadata

Attribute Required Description
Operation Yes Must be 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
UserMessageIfChallengeExpired The message to display to the user if the code verification session has expired. Either the code has expired or the code has never been generated for a given identifier.
UserMessageIfInternalError User error message if the server has encountered an internal error.
UserMessageIfThrottled User error message if a request has been throttled.
UserMessageIfVerificationFailedNoRetry The message to display to the user if they've provided an invalid code, and the user is not allowed to provide the correct code.
UserMessageIfVerificationFailedRetryAllowed The message to display to the user if they've provided an invalid code, and the user is allowed to provide the correct code.

Example: verify a code

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

<TechnicalProfile Id="AadSspr-VerifyCode">
  <DisplayName>Verify Code</DisplayName>
  <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.AadSsprProtocolProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
  <Metadata>
    <Item Key="Operation">VerifyCode</Item>
  </Metadata>
  <InputClaims>
    <InputClaim ClaimTypeReferenceId="verificationCode" PartnerClaimType="verificationCode" />
    <InputClaim ClaimTypeReferenceId="email" PartnerClaimType="emailAddress"/>
  </InputClaims>
</TechnicalProfile>