在 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 必要 描述
識別碼 (identifier) Yes 識別哪個使用者稍後需要驗證程式碼的識別碼。 其通常用作程式碼傳遞目的地的識別碼，例如電子郵件地址或電話號碼。

InputClaimsTransformations 元素可能含有 InputClaimsTransformation 的集合，用於修改輸入宣告或產生新的輸入宣告，然後再傳送給一次性密碼通訊協定提供者。

輸出宣告

OutputClaims 元素包含一次性密碼通訊協定提供者所產生的宣告清單。 您也可以將宣告名稱對應至以下定義的名稱。

ClaimReferenceId 必要 描述
otpGenerated Yes 產生的程式碼，其工作階段由 Azure AD B2C 管理。

OutputClaimsTransformations 元素可能含有 OutputClaimsTransformation 的集合，用於修改輸出宣告或產生新的輸出宣告。

中繼資料

下列設定可以用來設定程式碼產生模式：

屬性 必要 描述
作業 Yes 要執行的作業。 可能值：GenerateCode。
CodeExpirationInSeconds No 程式碼到期前的時間 (以秒為單位)。 最小值：60；最大值：1200；預設值：600。 每次提供程式碼 (使用 ReuseSameCode 的相同程式碼或新的程式碼)，就會延長程式碼到期時間。 這段時間也是用來設定重試逾時 (一旦達到嘗試次數上限，系統就會鎖定使用者，不得嘗試取得新的程式碼，直到這段時間到期為止)
CodeLength No 程式碼的長度。 預設值是 6。
CharacterSet No 程式碼的字元集，其會格式化以用於規則運算式中。 例如，a-z0-9A-Z。 預設值為 0-9。 字元集必須在指定的集合中包含至少 10 個不同的字元。
NumRetryAttempts No 在程式碼被視為無效之前的驗證嘗試次數。 預設值是 5。 例如，如果您將 NumRetryAttempts 設定為 2，則只會允許您總共 2 次的嘗試 (第一次嘗試 + 1 次重試)。 在第 3 次嘗試時，不論程式碼是否正確，都會擲回已達嘗試次數上限。
NumCodeGenerationAttempts No 每個識別碼嘗試產生程式碼的次數上限。 如果未指定，則預設值為 10 。
ReuseSameCode No 是否應該提供相同的程式碼，而不是在指定的程式碼尚未過期且仍然有效時，產生新的程式碼。 預設值是 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 必要 描述
識別碼 (identifier) Yes 識別哪個使用者先前已產生程式碼的識別碼。 其通常用作程式碼傳遞目的地的識別碼，例如電子郵件地址或電話號碼。
otpToVerify Yes 使用者所提供的驗證碼。

InputClaimsTransformations 元素可能含有 InputClaimsTransformation 的集合，用於修改輸入宣告或產生新的輸入宣告，然後再傳送給一次性密碼通訊協定提供者。

輸出宣告

在此通訊協定提供者的程式碼驗證期間未提供任何輸出宣告。

OutputClaimsTransformations 元素可能含有 OutputClaimsTransformation 的集合，用於修改輸出宣告或產生新的輸出宣告。

中繼資料

下列設定可以用於程式碼驗證模式：

屬性 必要 描述
作業 Yes 要執行的作業。 可能值：VerifyCode。

UI 元素

下列中繼資料可以用來設定程式碼驗證失敗時所顯示的錯誤訊息。 應該在自行判斷技術設定檔中設定中繼資料。 錯誤訊息可以當地語系化。

屬性 必要 描述
UserMessageIfSessionDoesNotExist No 要在程式碼驗證工作階段過期時顯示給使用者的訊息。 這是程式碼過期，或是從未針對指定的識別碼產生程式碼。
UserMessageIfMaxRetryAttempted No 要在超過了允許的驗證嘗試次數上限時顯示給使用者的訊息。
UserMessageIfMaxNumberOfCodeGenerated No 要在程式碼產生超過了允許的嘗試次數上限時顯示給使用者的訊息。
UserMessageIfInvalidCode No 要在提供了不正確的程式碼時顯示給使用者的訊息。
UserMessageIfVerificationFailedRetryAllowed No 要在提供了不正確的程式碼，並允許使用者提供正確的程式碼時顯示給使用者的訊息。
UserMessageIfSessionConflict No 要在無法驗證程式碼時顯示給使用者的訊息。

範例

下列範例 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>

後續步驟

請參閱下列文章，以取得使用一次性密碼技術設定檔，搭配自訂電子郵件驗證的範例：

  • Azure Active Directory B2C (Mailjet、SendGrid) 中的自訂電子郵件驗證