在 Azure AD B2C 自定义策略中定义一次性密码技术配置文件Define a one-time password 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 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

“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.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.

输入声明Input claims

InputClaims 元素包含发送到一次性密码协议提供程序所需的声明列表。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.

ClaimReferenceIdClaimReferenceId 必须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.

InputClaimsTransformations 元素可以包含 InputClaimsTransformation 元素的集合,这些元素用于在将声明发送到一次性密码协议提供程序之前修改输入声明或生成新的输入声明 。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

OutputClaims 元素包含由一次性密码协议提供程序生成的声明列表。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.

ClaimReferenceIdClaimReferenceId 必须Required 说明Description
otpGeneratedotpGenerated Yes 一段生成代码,由 Azure AD B2C 管理其会话。The generated code whose session is managed by Azure AD B2C.

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

以下设置可用于配置代码生成模式:The following settings can be used to configure code generation mode:

属性Attribute 必须Required 说明Description
CodeExpirationInSecondsCodeExpirationInSeconds No 代码过期之前的时间(秒)。Time in seconds until code expiration. 最小值:60;大值:1200;默认值:600Minimum: 60; Maximum: 1200; Default: 600.
CodeLengthCodeLength No 代码的长度。Length of the code. 默认值为 6The default value is 6.
CharacterSetCharacterSet No 代码的字符集,其格式设置为可在正则表达式中使用。The character set for the code, formatted for use in a regular expression. 例如,a-z0-9A-ZFor example, a-z0-9A-Z. 默认值为 0-9The default value is 0-9. 字符集必须在指定的集中至少包含 10 个不同的字符。The character set must include a minimum of 10 different characters in the set specified.
NumRetryAttemptsNumRetryAttempts No 代码被视为无效之前的验证尝试次数。The number of verification attempts before the code is considered invalid. 默认值为 5The default value is 5.
操作Operation Yes 要执行的操作。The operation to be performed. 可能的值:GenerateCodePossible value: GenerateCode.
ReuseSameCodeReuseSameCode No 给定代码未过期且仍然有效时,是否应提供重复的代码而不生成新代码。Whether a duplicate code should be given rather than generating a new code when given code has not expired and is still valid. 默认值为 falseThe default value is false.

示例Example

下面的示例 TechnicalProfile 用于生成代码: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="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

InputClaims 元素包含发送到一次性密码协议提供程序所需的声明列表。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.

ClaimReferenceIdClaimReferenceId 必须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.
otpToVerifyotpToVerify Yes 用户提供的验证码。The verification code provided by the user.

InputClaimsTransformations 元素可以包含 InputClaimsTransformation 元素的集合,这些元素用于在将声明发送到一次性密码协议提供程序之前修改输入声明或生成新的输入声明 。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.

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

以下设置可用于代码验证模式:The following settings can be used to code verification mode:

属性Attribute 必须Required 说明Description
操作Operation Yes 要执行的操作。The operation to be performed. 可能的值:VerifyCodePossible value: 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
UserMessageIfSessionDoesNotExistUserMessageIfSessionDoesNotExist 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.
UserMessageIfMaxRetryAttemptedUserMessageIfMaxRetryAttempted No 用户尝试验证的次数超过允许的最大值时显示的消息。The message to display to the user if they've exceeded the maximum allowed verification attempts.
UserMessageIfInvalidCodeUserMessageIfInvalidCode No 用户提供的代码无效时显示的消息。The message to display to the user if they've provided an invalid code.
UserMessageIfVerificationFailedRetryAllowedUserMessageIfVerificationFailedRetryAllowed No 在用户提供的代码无效且系统允许用户提供正确代码的情况下向用户显示的消息。The message to display to the user if they've provided an invalid code, and user is allowed to provide the correct code.
UserMessageIfSessionConflictUserMessageIfSessionConflict No 无法验证代码时要向用户显示的消息。The message to display to the user if the code cannot be verified.

示例Example

下面的示例 TechnicalProfile 用于验证代码: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>