在 Azure AD B2C 自定义策略中定义一次性密码技术配置文件

注意

在 Azure Active Directory B2C 中,自定义策略主要用于解决复杂的情况。 在大多数情况下,建议你使用内置用户流。 如果尚未这样做,请从 Active Directory B2C 中的自定义策略入门了解自定义策略新手包。

Azure Active Directory B2C (Azure AD B2C) 为管理一次性密码的生成和验证提供了支持。 使用技术配置文件生成代码,并稍后验证代码。

在代码验证过程中,一次性密码技术配置文件也可能返回错误消息。 通过使用“验证技术配置文件”来设计与一次性密码的集成。 验证技术配置文件调用一次性密码技术配置文件来验证代码。 在用户旅程继续执行之前,验证技术配置文件将验证用户提供的数据。 使用验证技术配置文件时,错误消息将显示在自断言页面上。

协议

“Protocol”元素的“Name”属性必须设置为 Proprietary。 handler 属性必须包含 Azure AD B2C 使用的协议处理程序程序集的完全限定名称:

Web.TPEngine.Providers.OneTimePasswordProtocolProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null

以下示例显示了一次性密码技术配置文件:

<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" />
  ...

生成代码

此技术配置文件的第一种模式是生成代码。 下面是可以为此模式配置的选项。 在会话中跟踪生成的代码和尝试。

输入声明

InputClaims 元素包含发送到一次性密码协议提供程序所需的声明列表。 还可将声明名称映射到下面定义的名称。

ClaimReferenceId 必选 说明
标识符 一个标识符,用于标识需在稍后验证代码的用户。 此标识符通常用作代码传递的目标对象的标识符,例如电子邮件地址或电话号码。

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

输出声明

OutputClaims 元素包含由一次性密码协议提供程序生成的声明列表。 还可将声明名称映射到下面定义的名称。

ClaimReferenceId 必选 说明
otpGenerated 一段生成代码,由 Azure AD B2C 管理其会话。

OutputClaimsTransformations 元素可能包含用于修改输出声明或生成新输出声明的 OutputClaimsTransformation 元素集合。

Metadata

以下设置可用于配置代码生成模式:

属性 必须 说明
操作 要执行的操作。 可能的值:GenerateCode
CodeExpirationInSeconds 代码过期之前的时间(秒)。 最小值:60;大值:1200;默认值:600 每次提供代码(使用 ReuseSameCode 的相同代码或新代码)时,代码过期时间都会延长。 此时间还用于设置重试超时(达到最大尝试次数后,用户将被锁定,在此时间到期之前无法尝试获取新代码)
CodeLength 代码的长度。 默认值为 6
CharacterSet 代码的字符集,其格式设置为可在正则表达式中使用。 例如,a-z0-9A-Z。 默认值为 0-9。 字符集必须在指定的集中至少包含 10 个不同的字符。
NumRetryAttempts 代码被视为无效之前的验证尝试次数。 默认值为 5。 例如,如果将 NumRetryAttempts 设置为 2,则仅允许总共尝试 2 次(首次 + 重试 1 次)。 对于第 3 次尝试,无论代码是否正确,都将引发已达到最大尝试次数的错误。
NumCodeGenerationAttempts 每个标识符的最大代码生成尝试次数。 如果未指定,则默认值为 10
ReuseSameCode 当给定代码尚未过期且仍然有效时,是否应给出相同的代码而不是生成新代码。 默认值为 false

示例

下面的示例 TechnicalProfile 用于生成代码:

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

验证验证码

此技术配置文件的第二种模式是验证代码。 下面是可以为此模式配置的选项。

输入声明

InputClaims 元素包含发送到一次性密码协议提供程序所需的声明列表。 还可将声明名称映射到下面定义的名称。

ClaimReferenceId 必选 说明
标识符 一个标识符,用于标识之前生成代码的用户。 此标识符通常用作代码传递的目标对象的标识符,例如电子邮件地址或电话号码。
otpToVerify 用户提供的验证码。

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

输出声明

此协议提供程序的代码验证过程中未提供任何输出声明。

OutputClaimsTransformations 元素可能包含用于修改输出声明或生成新输出声明的 OutputClaimsTransformation 元素集合。

Metadata

以下设置可用于代码验证模式:

属性 必须 说明
操作 要执行的操作。 可能的值:VerifyCode

UI 元素

以下元数据可用于配置在代码验证失败时显示的错误消息。 元数据应该在自断言技术配置文件中进行配置。 可以将错误消息本地化

Attribute 必须 说明
UserMessageIfSessionDoesNotExist 代码验证会话过期后向用户显示的消息。 代码已过期,或从未为给定标识符生成代码。
UserMessageIfMaxRetryAttempted 用户尝试验证的次数超过允许的最大值时显示的消息。
UserMessageIfMaxNumberOfCodeGenerated 当代码生成超出了允许的最大尝试次数时显示给用户的消息。
UserMessageIfInvalidCode 用户提供的代码无效时显示的消息。
UserMessageIfVerificationFailedRetryAllowed 在用户提供的代码无效且系统允许用户提供正确代码的情况下向用户显示的消息。
UserMessageIfSessionConflict 无法验证代码时要向用户显示的消息。

示例

下面的示例 TechnicalProfile 用于验证代码:

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