在 Azure AD B2C 自定义策略中定义 Azure MFA 技术配置文件Define an Azure MFA 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) 使用 Azure 多重身份验证 (MFA) 为验证电话号码提供支持。Azure Active Directory B2C (Azure AD B2C) provides support for verifying a phone number by using Azure Multi-Factor Authentication (MFA). 使用此技术配置文件生成代码并将其发送到一定的手机号,然后验证该代码。Use this technical profile to generate and send a code to a phone number, and then verify the code. Azure MFA 技术配置文件也可能返回错误消息。The Azure MFA 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 MFA 服务生成代码并将其发送到某个手机号,然后验证该代码。Uses the Azure MFA service to generate and send a code to a phone number, and then verifies the code.
  • 通过文本消息验证电话号码。Validates a phone number via text messages.

备注

此功能目前以公共预览版提供。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.AzureMfaProtocolProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null

以下示例演示了 Azure MFA 的技术配置文件:The following example shows an Azure MFA technical profile:

<TechnicalProfile Id="AzureMfa-SendSms">
    <DisplayName>Send Sms</DisplayName>
    <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.AzureMfaProtocolProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
    ...

发送短信Send SMS

此技术配置文件的第一种模式是生成并发送代码。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 MFA 的声明的列表 。The InputClaims element contains a list of claims to send to Azure MFA. 还可将声明名称映射到 MFA 技术配置文件中定义的名称。You can also map the name of your claim to the name defined in the MFA technical profile.

ClaimReferenceIdClaimReferenceId 必选Required 说明Description
userPrincipalNameuserPrincipalName Yes 拥有此电话号码的用户的标识符。The identifier for the user who owns the phone number.
phoneNumberphoneNumber Yes 要将短信代码发送到的电话号码。The phone number to send an SMS code to.
companyNamecompanyName No 短信中的公司名称。The company name in the SMS. 如果未提供,则使用应用程序的名称。If not provided, the name of your application is used.
区域设置locale No 短信的区域设置。The locale of the SMS. 如果未提供,则使用用户的浏览器区域设置。If not provided, the browser locale of the user is used.

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

输出声明Output claims

Azure MFA 协议提供程序未返回任何 OutputClaims,因此无需指定输出声明 。The Azure MFA protocol provider does not return any OutputClaims, thus there is no need to specify output claims. 但是,只要设置了 DefaultValue 属性,就可以包含 Azure MFA 标识提供者不会返回的声明。You can, however, include claims that aren't returned by the Azure MFA identity 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.

元数据Metadata

AttributeAttribute 必选Required 说明Description
OperationOperation Yes 必须是 OneWaySMS 。Must be OneWaySMS.

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.

AttributeAttribute 必选Required 说明Description
UserMessageIfCouldntSendSmsUserMessageIfCouldntSendSms No 提供的电话号码不可接收短信时显示的用户错误消息。User error message if the phone number provided does not accept SMS.
UserMessageIfInvalidFormatUserMessageIfInvalidFormat No 提供的电话号码不是有效电话号码时显示的用户错误消息。User error message if the phone number provided is not a valid phone number.
UserMessageIfServerErrorUserMessageIfServerError 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 SMS

以下示例显示了一个 Azure MFA 技术配置文件(用于通过短信发送代码)。The following example shows an Azure MFA technical profile that is used to send a code via SMS.

<TechnicalProfile Id="AzureMfa-SendSms">
  <DisplayName>Send Sms</DisplayName>
  <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.AzureMfaProtocolProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
  <Metadata>
    <Item Key="Operation">OneWaySMS</Item>
  </Metadata>
  <InputClaimsTransformations>
    <InputClaimsTransformation ReferenceId="CombinePhoneAndCountryCode" />
    <InputClaimsTransformation ReferenceId="ConvertStringToPhoneNumber" />
  </InputClaimsTransformations>
  <InputClaims>
    <InputClaim ClaimTypeReferenceId="userPrincipalName" />
    <InputClaim ClaimTypeReferenceId="fullPhoneNumber" PartnerClaimType="phoneNumber" />
  </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 MFA 的声明的列表 。The InputClaims element contains a list of claims to send to Azure MFA. 还可将声明名称映射到 MFA 技术配置文件中定义的名称。You can also map the name of your claim to the name defined in the MFA technical profile.

ClaimReferenceIdClaimReferenceId 必选Required 说明Description
phoneNumberphoneNumber Yes 与之前用于发送代码的手机号相同。Same phone number as previously used to send a code. 它也用来定位电话验证会话。It is also used to locate a phone verification session.
verificationCodeverificationCode Yes 待验证用户提供的验证码The verification code provided by the user to be verified

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

输出声明Output claims

Azure MFA 协议提供程序未返回任何 OutputClaims,因此无需指定输出声明 。The Azure MFA protocol provider does not return any OutputClaims, thus there is no need to specify output claims. 但是,只要设置了 DefaultValue 属性,就可以包含 Azure MFA 标识提供者不会返回的声明。You can, however, include claims that aren't returned by the Azure MFA identity 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.

元数据Metadata

AttributeAttribute 必选Required 说明Description
OperationOperation Yes 必须是“验证” Must be Verify

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.

AttributeAttribute 必选Required 说明Description
UserMessageIfMaxAllowedCodeRetryReachedUserMessageIfMaxAllowedCodeRetryReached No 用户多次尝试提交某验证码时显示的用户错误消息。User error message if the user has attempted a verification code too many times.
UserMessageIfServerErrorUserMessageIfServerError No 服务器遇到内部错误时显示的用户错误消息。User error message if the server has encountered an internal error.
UserMessageIfThrottledUserMessageIfThrottled No 请求受限制时显示的用户错误消息。User error message if the request is throttled.
UserMessageIfWrongCodeEnteredUserMessageIfWrongCodeEntered No 输入的验证码错误时显示的用户错误消息。User error message if the code entered for verification is wrong.

示例:验证代码Example: verify a code

以下示例显示了用来验证代码的 Azure MFA 技术配置文件。The following example shows an Azure MFA technical profile used to verify the code.

<TechnicalProfile Id="AzureMfa-VerifySms">
    <DisplayName>Verify Sms</DisplayName>
    <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.AzureMfaProtocolProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
    <Metadata>
        <Item Key="Operation">Verify</Item>
    </Metadata>
    <InputClaims>
        <InputClaim ClaimTypeReferenceId="phoneNumber" PartnerClaimType="phoneNumber" />
        <InputClaim ClaimTypeReferenceId="verificationCode" />
    </InputClaims>
</TechnicalProfile>