在 Azure AD B2C 自定义策略中定义 Azure AD SSPR 技术配置文件Define an Azure AD SSPR technical profile in an Azure AD B2C custom policy

备注

在 Azure Active Directory B2C 中,custom policies 主要用于解决复杂方案。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.

Azure Active Directory B2C (Azure AD B2C) 支持验证自助式密码重置 (SSPR) 的电子邮件地址。Azure Active Directory B2C (Azure AD B2C) provides support for verifying an email address for self-service password reset (SSPR). 使用 Azure AD SSPR 技术配置文件生成代码并将其发送到电子邮件地址,然后验证该代码。Use the Azure AD SSPR technical profile to generate and send a code to an email address, and then verify the code. Azure AD SSPR 技术配置文件也可能返回错误消息。The Azure AD 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.
  • 使用 Azure AD SSPR 服务生成代码并将其发送到电子邮件地址,然后验证该代码。Uses the Azure AD 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.

备注

此功能目前以公共预览版提供。This feature is in public preview.

协议Protocol

“Protocol”元素的“Name”属性必须设置为 ProprietaryThe Name attribute of the Protocol element needs to be set to Proprietary. handler 属性必须包含 Azure AD B2C 使用的协议处理程序程序集的完全限定名称: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

以下示例演示了 Azure AD SSPR 技术配置文件:The following example shows an Azure AD 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

InputClaims 元素包含要发送到 Azure AD SSPR 的声明的列表。The InputClaims element contains a list of claims to send to Azure AD SSPR. 还可将声明名称映射到 SSPR 技术配置文件中定义的名称。You can also map the name of your claim to the name defined in the SSPR technical profile.

ClaimReferenceIdClaimReferenceId 必须Required 说明Description
emailAddressemailAddress Yes 拥有此电子邮件地址的用户的标识符。The identifier for the user who owns the email address. 输入声明的 PartnerClaimType 属性必须设置为 emailAddressThe PartnerClaimType property of the input claim must be set to emailAddress.

InputClaimsTransformations 元素可能包含一系列 InputClaimsTransformation 元素,这些元素用于修改输入声明,或者用于生成新的声明并将其发送到 Azure AD SSPR 服务。 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 Azure AD SSPR service.

输出声明Output claims

Azure AD SSPR 协议提供程序未返回任何 OutputClaims,因此无需指定输出声明。The Azure AD SSPR protocol provider does not return any OutputClaims, thus there is no need to specify output claims. 但是,只要设置了 DefaultValue 属性,就可以包含 Azure AD SSPR 协议提供程序不会返回的声明。You can, however, include claims that aren't returned by the Azure AD SSPR protocol provider as long as you set the DefaultValue attribute.

OutputClaimsTransformations 元素可能包含用于修改输出声明或生成新输出声明的 OutputClaimsTransformation 元素集合。The OutputClaimsTransformations element may contain a collection of OutputClaimsTransformation elements that are used to modify the output claims or generate new ones.

MetadataMetadata

AttributeAttribute 必需Required 说明Description
操作Operation Yes 必须是 SendCode。Must be SendCode.

UI 元素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
UserMessageIfInternalErrorUserMessageIfInternalError No 服务器遇到内部错误时显示的用户错误消息。User error message if the server has encountered an internal error.
UserMessageIfThrottledUserMessageIfThrottled No 请求被限制时显示的用户错误消息。User error message if a request has been throttled.

示例:发送电子邮件Example: send an email

以下示例显示了一个 Azure AD SSPR 技术配置文件,用于通过电子邮件发送代码。The following example shows an Azure AD 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

InputClaims 元素包含要发送到 Azure AD SSPR 的声明的列表。The InputClaims element contains a list of claims to send to Azure AD SSPR. 还可将声明名称映射到 SSPR 技术配置文件中定义的名称。You can also map the name of your claim to the name defined in the SSPR technical profile.

ClaimReferenceIdClaimReferenceId 必须Required 说明Description
emailAddressemailAddress Yes 与之前用于发送代码的电子邮件地址相同。Same email address as previously used to send a code. 它也用来定位电子邮件验证会话。It is also used to locate an email verification session. 输入声明的 PartnerClaimType 属性必须设置为 emailAddressThe PartnerClaimType property of the input claim must be set to emailAddress.
verificationCodeverificationCode Yes 待验证用户提供的验证码。The verification code provided by the user to be verified. 输入声明的 PartnerClaimType 属性必须设置为 verificationCodeThe PartnerClaimType property of the input claim must be set to verificationCode.

InputClaimsTransformations 元素可能包含一系列 InputClaimsTransformation 元素,这些元素用于修改输入声明,或者用于生成新的声明并调用 Azure AD SSPR 服务。 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 Azure AD SSPR service.

输出声明Output claims

Azure AD SSPR 协议提供程序未返回任何 OutputClaims,因此无需指定输出声明。The Azure AD SSPR protocol provider does not return any OutputClaims, thus there is no need to specify output claims. 但是,只要设置了 DefaultValue 属性,就可以包含 Azure AD SSPR 协议提供程序不会返回的声明。You can, however, include claims that aren't returned by the Azure AD SSPR protocol provider as long as you set the DefaultValue attribute.

OutputClaimsTransformations 元素可能包含用于修改输出声明或生成新输出声明的 OutputClaimsTransformation 元素集合。The OutputClaimsTransformations element may contain a collection of OutputClaimsTransformation elements that are used to modify the output claims or generate new ones.

MetadataMetadata

AttributeAttribute 必需Required 说明Description
操作Operation Yes 必须是 VerifyCodeMust be VerifyCode

UI 元素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
UserMessageIfChallengeExpiredUserMessageIfChallengeExpired 代码验证会话过期后向用户显示的消息。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.
UserMessageIfInternalErrorUserMessageIfInternalError 服务器遇到内部错误时显示的用户错误消息。User error message if the server has encountered an internal error.
UserMessageIfThrottledUserMessageIfThrottled 请求被限制时显示的用户错误消息。User error message if a request has been throttled.
UserMessageIfVerificationFailedNoRetryUserMessageIfVerificationFailedNoRetry 在用户提供的代码无效且系统不允许用户提供正确代码的情况下向用户显示的消息。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.
UserMessageIfVerificationFailedRetryAllowedUserMessageIfVerificationFailedRetryAllowed 在用户提供的代码无效且系统允许用户提供正确代码的情况下向用户显示的消息。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

以下示例显示了用来验证代码的 Azure AD SSPR 技术配置文件。The following example shows an Azure AD 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>