Share via

在 Azure Active Directory B2C 自定義原則中定義自我判斷技術配置檔

  • 文章

注意

在 Azure Active Directory B2C 中， 自定義原則 的設計主要是為了解決複雜的案例。 在大部分情況下，我們建議您使用內 建的使用者流程。 如果您尚未這麼做，請了解開始使用 Active Directory B2C 中的自定義原則入門套件。

Azure Active Directory B2C （Azure AD B2C） 中的所有互動，預期使用者提供輸入都是自我判斷技術配置檔。 例如，註冊頁面、登入頁面或密碼重設頁面。

通訊協定

Protocol 元素的 Name 屬性必須設定為 Proprietary。 處理程式屬性必須包含 Azure AD B2C 用於自我判斷的通訊協定處理程式元件的完整名稱：Web.TPEngine.Providers.SelfAssertedAttributeProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null

下列範例顯示電子郵件註冊的自我判斷技術配置檔：

<TechnicalProfile Id="LocalAccountSignUpWithLogonEmail">
  <DisplayName>Email signup</DisplayName>
  <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.SelfAssertedAttributeProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />

輸入宣告

在自我判斷技術配置檔中，您可以使用 InputClaims 和 InputClaimsTransformations 元素，預先填入出現在自我判斷頁面的宣告值（顯示宣告）。 例如，在編輯配置文件原則中，使用者旅程圖會先從 Azure AD B2C 目錄服務讀取使用者配置檔，然後自我判斷技術配置檔會使用儲存在使用者配置檔中的用戶數據來設定輸入宣告。 這些宣告會從使用者配置檔收集，然後呈現給可編輯現有數據的使用者。

<TechnicalProfile Id="SelfAsserted-ProfileUpdate">
...
  <InputClaims>
    <InputClaim ClaimTypeReferenceId="alternativeSecurityId" />
    <InputClaim ClaimTypeReferenceId="userPrincipalName" />
    <InputClaim ClaimTypeReferenceId="givenName" />
    <InputClaim ClaimTypeReferenceId="surname" />
  </InputClaims>

顯示宣告

DisplayClaims 元素包含要在螢幕上呈現的宣告清單，以便從使用者收集數據。 若要預先填入顯示宣告的值，請使用先前所述的輸入宣告。 元素也可能包含預設值。

DisplayClaims 中宣告的順序會指定 Azure AD B2C 在螢幕上呈現宣告的順序。 若要強制使用者提供特定宣告的值，請將 DisplayClaim 元素的 Required 屬性設定為 true。

DisplayClaims 集合中的 ClaimType 元素必須將 UserInputType 元素設定為 Azure AD B2C 支援的任何使用者輸入類型。 例如，TextBox 或 DropdownSingleSelect。

新增 DisplayControl 的參考

在顯示宣告集合中，您可以包含您所建立之 DisplayControl 的參考。 顯示控件是具有特殊功能並與 Azure AD B2C 後端服務互動的使用者介面元素。 它可讓使用者在後端叫用驗證技術配置檔的頁面上執行動作。 例如，驗證電子郵件地址、電話號碼或客戶忠誠度號碼。

下列範例 TechnicalProfile 說明搭配顯示控件使用顯示宣告。

  • 第一個顯示宣告會參考 emailVerificationControl 顯示控件，該控件會收集並驗證電子郵件位址。
  • 第二個顯示宣告會參考 captchaChallengeControl 顯示控件，該控件會產生並驗證 CAPTCHA 程式代碼。
  • 第六個顯示宣告會參考 phoneVerificationControl 顯示控件，該控件會收集和驗證電話號碼。
  • 其他顯示宣告是要從使用者收集的 ClaimTypes。
<TechnicalProfile Id="Id">
  <DisplayClaims>
    <DisplayClaim DisplayControlReferenceId="emailVerificationControl" />
    <DisplayClaim DisplayControlReferenceId="captchaChallengeControl" />
    <DisplayClaim ClaimTypeReferenceId="displayName" Required="true" />
    <DisplayClaim ClaimTypeReferenceId="givenName" Required="true" />
    <DisplayClaim ClaimTypeReferenceId="surName" Required="true" />
    <DisplayClaim DisplayControlReferenceId="phoneVerificationControl" />
    <DisplayClaim ClaimTypeReferenceId="newPassword" Required="true" />
    <DisplayClaim ClaimTypeReferenceId="reenterPassword" Required="true" />
  </DisplayClaims>
</TechnicalProfile>

如前所述，具有顯示控件參考的顯示宣告可能會執行自己的驗證，例如驗證電子郵件位址。 此外，自我判斷提示頁面支援使用驗證技術配置文件來驗證整個頁面，包括任何使用者輸入（宣告類型或顯示控件），然後再移至下一個協調流程步驟。

仔細結合顯示宣告和輸出宣告的使用方式

如果您在自我判斷技術配置檔中指定一或多個 DisplayClaim 元素，則必須針對 您想要在螢幕上顯示並從使用者收集的每個 宣告使用 DisplayClaim。 沒有輸出宣告是由包含至少一個顯示宣告的自我判斷技術配置文件顯示。

請考慮下列範例，其中 age 宣告在基底原則中定義為 輸出 宣告。 將任何顯示宣告新增至自我判斷技術配置檔之前， age 宣告會顯示在畫面上供使用者收集數據：

<TechnicalProfile Id="id">
  <OutputClaims>
    <OutputClaim ClaimTypeReferenceId="age" />
  </OutputClaims>
</TechnicalProfile>

如果繼承該基底的分葉原則後續指定 officeNumber 為 顯示 宣告：

<TechnicalProfile Id="id">
  <DisplayClaims>
    <DisplayClaim ClaimTypeReferenceId="officeNumber" />
  </DisplayClaims>
  <OutputClaims>
    <OutputClaim ClaimTypeReferenceId="officeNumber" />
  </OutputClaims>
</TechnicalProfile>

基 age 底原則中的宣告不再顯示在畫面上給使用者 -- 它實際上是「隱藏」的。若要顯示 age 宣告，並從使用者收集年齡值，您必須新增 ageDisplayClaim。

輸出宣告

OutputClaims 元素包含要傳回至下一個協調流程步驟的宣告清單。 只有在從未設定宣告時，DefaultValue 屬性才會生效。 如果在上一個協調流程步驟中設定，即使使用者將值保留空白，預設值也不會生效。 若要強制使用預設值，請將 AlwaysUseDefaultValue 屬性設定為 true。

基於安全性考慮，密碼宣告值（UserInputType 設定為 Password）僅適用於自我判斷技術配置檔的驗證技術配置檔。 在下一個協調流程步驟中，您無法使用密碼宣告。

注意

在舊版的 Identity Experience Framework （IEF）中，輸出宣告是用來從使用者收集數據。 若要從使用者收集數據，請改用 DisplayClaims 集合。

OutputClaimsTransformations 元素可能包含 OutputClaimsTransformation 元素的集合，這些元素可用來修改輸出宣告或產生新的宣告。

當您應該使用輸出宣告時

在自我判斷技術配置檔中，輸出宣告集合會將宣告傳回下一個協調流程步驟。

在下列情況下使用輸出宣告：

  • 宣告是由輸出宣告轉換所輸出。
  • 在輸出宣告 中設定預設值，而不需從使用者收集數據，或從驗證技術配置檔傳回數據。 自我判斷技術配置檔會將 LocalAccountSignUpWithLogonEmail executed-SelfAsserted-Input宣告設定為 true。
  • 驗證技術配置檔會傳回輸出宣告 - 您的技術配置檔可能會呼叫傳回某些宣告的驗證技術配置檔。 您可能會想要泡泡宣告，並將它們傳回使用者旅程圖中的下一個協調流程步驟。 例如，使用本機帳戶登入時，名為 SelfAsserted-LocalAccountSignin-Email 的自我判斷技術配置檔會呼叫名為 login-NonInteractive的驗證技術配置檔。 此技術配置檔會驗證使用者認證，並傳回使用者配置檔。 例如 'userPrincipalName'、'displayName'、'givenName' 和 'surName'。
  • 顯示控制項會傳回輸出宣告 - 您的技術設定檔可能有顯示控制件的參考。 顯示控制項會傳回一些宣告，例如已驗證的電子郵件位址。 您可能會想要泡泡宣告，並將它們傳回使用者旅程圖中的下一個協調流程步驟。

下列範例示範如何使用使用顯示宣告和輸出宣告的自我判斷技術配置檔。

<TechnicalProfile Id="LocalAccountSignUpWithLogonEmail">
  <DisplayName>Email signup</DisplayName>
  <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.SelfAssertedAttributeProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
  <Metadata>
    <Item Key="IpAddressClaimReferenceId">IpAddress</Item>
    <Item Key="ContentDefinitionReferenceId">api.localaccountsignup</Item>
    <Item Key="language.button_continue">Create</Item>
  </Metadata>
  <InputClaims>
    <InputClaim ClaimTypeReferenceId="email" />
  </InputClaims>
  <DisplayClaims>
    <DisplayClaim DisplayControlReferenceId="emailVerificationControl" />
    <DisplayClaim DisplayControlReferenceId="SecondaryEmailVerificationControl" />
    <DisplayClaim ClaimTypeReferenceId="displayName" Required="true" />
    <DisplayClaim ClaimTypeReferenceId="givenName" Required="true" />
    <DisplayClaim ClaimTypeReferenceId="surName" Required="true" />
    <DisplayClaim ClaimTypeReferenceId="newPassword" Required="true" />
    <DisplayClaim ClaimTypeReferenceId="reenterPassword" Required="true" />
  </DisplayClaims>
  <OutputClaims>
    <OutputClaim ClaimTypeReferenceId="email" Required="true" />
    <OutputClaim ClaimTypeReferenceId="objectId" />
    <OutputClaim ClaimTypeReferenceId="executed-SelfAsserted-Input" DefaultValue="true" />
    <OutputClaim ClaimTypeReferenceId="authenticationSource" />
    <OutputClaim ClaimTypeReferenceId="newUser" />
  </OutputClaims>
  <ValidationTechnicalProfiles>
    <ValidationTechnicalProfile ReferenceId="AAD-UserWriteUsingLogonEmail" />
  </ValidationTechnicalProfiles>
  <UseTechnicalProfileForSessionManagement ReferenceId="SM-AAD" />
</TechnicalProfile>

注意

當您在自我判斷技術配置檔中收集密碼宣告值時，該值只能在相同的技術配置檔或相同自我判斷技術配置檔所參考的驗證技術配置檔內使用。 當執行該自我判斷技術配置檔完成，並移至另一個技術配置檔時，密碼的值就會遺失。 因此，密碼宣告只能儲存在收集密碼的協調流程步驟中。

輸出宣告註冊或登入頁面

在合併註冊和登入頁面中，使用指定 unifiedssp 或 unifiedssd 頁面類型的內容定義 DataUri 元素時，請注意下列事項：

  • 只會轉譯使用者名稱和密碼宣告。
  • 前兩個輸出宣告必須是使用者名稱和密碼（依此順序）。
  • 不會轉譯任何其他宣告;針對這些宣告，您必須設定 defaultValue 或叫用宣告窗體驗證技術配置檔。

保存宣告

不使用 PersistedClaims 元素。 自我判斷技術配置檔不會將數據保存到 Azure AD B2C。 相反地，會對負責保存數據的驗證技術配置檔進行呼叫。 例如，註冊原則會使用 LocalAccountSignUpWithLogonEmail 自我判斷技術配置檔來收集新的使用者配置檔。 LocalAccountSignUpWithLogonEmail技術配置檔會呼叫驗證技術配置檔，以在 Azure AD B2C 中建立帳戶。

驗證技術配置檔

驗證技術配置檔用於驗證參考技術配置檔的某些或所有輸出宣告。 驗證技術配置檔的輸入宣告必須出現在自我判斷技術配置文件的輸出宣告中。 驗證技術配置檔會驗證使用者輸入，而且可以將錯誤傳回給使用者。

驗證技術配置檔可以是原則中的任何技術配置檔，例如 Microsoft Entra ID 或 REST API 技術配置檔。 在上述範例中 LocalAccountSignUpWithLogonEmail ，技術配置檔會驗證 signinName 不存在於目錄中。 如果沒有，驗證技術配置檔會建立本機帳戶，並傳回 objectId、authenticationSource、newUser。 SelfAsserted-LocalAccountSignin-Email技術配置檔會login-NonInteractive呼叫驗證技術配置檔來驗證用戶認證。

您也可以使用商業規則呼叫 REST API 技術配置檔、覆寫輸入宣告，或藉由進一步整合公司企業營運應用程式來擴充用戶數據。 如需詳細資訊，請參閱 驗證技術配置檔

注意

只有在使用者輸入時，才會觸發驗證技術配置檔。 您無法建立空的自我判斷技術配置檔來呼叫驗證技術配置檔，只是為了利用 ValidationTechnicalProfile 元素的 ContinueOnError 屬性。 您只能從要求使用者輸入的自我判斷技術配置檔，或從使用者旅程圖中的協調流程步驟呼叫驗證技術配置檔。

中繼資料

屬性 必要 描述
setting.operatingMode 1 No 對於登入頁面，此屬性會控制使用者名稱欄位的行為，例如輸入驗證和錯誤訊息。 預期值： Username 或 Email。 查看 此元數據的實時示範 。
AllowGenerationOfClaimsWithNullValues No 允許產生具有 Null 值的宣告。 例如，在使用者未選取複選框的情況下。
ContentDefinitionReferenceId Yes 與此技術配置文件相關聯的內容定義標識碼。
EnforceEmailVerification No 若要註冊或設定檔編輯，請強制執行電子郵件驗證。 可能的值： true （預設值），或 false。
setting.retryLimit No 控制使用者可以嘗試提供針對驗證技術配置檔檢查的數據次數。 例如，用戶嘗試使用已經存在的帳戶進行註冊，並持續嘗試直到達到限制為止。 查看 此元數據的實時示範 。
SignUpTarget 1 No 註冊目標交換標識碼。 當使用者按下註冊按鈕時，Azure AD B2C 會執行指定的交換標識碼。
setting.showCancelButton No 顯示取消按鈕。 可能的值： true （預設值），或 false。 查看 此元數據的實時示範 。
setting.showContinueButton No 顯示 [繼續] 按鈕。 可能的值： true （預設值），或 false。 查看 此元數據的實時示範 。
setting.showSignupLink 2 No 顯示註冊按鈕。 可能的值： true （預設值），或 false。 查看 此元數據的實時示範 。
setting.forgotPasswordLinkLocation 2 No 顯示忘記的密碼連結。 可能的值： AfterLabel （預設值）會在標籤後面或密碼輸入欄位後面顯示連結，如果沒有標籤，在密碼輸入字段後面顯示連結， AfterInputAfterButtons 在按鈕之後顯示表單底部的連結，或 None 移除忘記的密碼連結。 查看 此元數據的實時示範 。
setting.enableRememberMe 2 No 顯示 [ 讓我保持登入] 複選框。 可能的值： true 、 或 false （預設值）。 此元數據的實時示範 。
setting.inputVerificationDelayTimeInMilliseconds 3 No 藉由等候使用者停止輸入，然後驗證值，以改善用戶體驗。 預設值 2000 毫秒。 查看 此元數據的實時示範 。
IncludeClaimResolvingInClaimsHandling No 針對輸入和輸出宣告，指定宣告解析是否包含在技術配置檔中。 可能的值： true、 或 false （預設值）。 如果您要在技術設定檔中使用宣告解析程式，請將此設定為 true。
setting.forgotPasswordLinkOverride 4 No 密碼重設宣告要執行的交換。 如需詳細資訊，請參閱 自助式密碼重設。
setting.enableCaptchaChallenge No 指定是否應該顯示 CAPTCHA 挑戰程式代碼。 可能的值： true 、 或 false （預設值）。 若要讓此設定能夠運作，必須在自我判斷技術配置文件的顯示宣告中參考 CAPTCHA 顯示控制件。 CAPTCHA 功能處於 公開預覽狀態。

注意：

  1. 適用於、 或unifiedssd的內容定義 DataUri 類型unifiedssp。
  2. 適用於、 或unifiedssd的內容定義 DataUri 類型unifiedssp。 版面配置 1.1.0 版和更新版本 。
  3. 適用於 1.2.0 版和更新版本的 版面配置。
  4. 適用於的內容定義 DataUri 類型 unifiedssp。 版面配置 2.1.2 版和更新版本 。

密碼編譯金鑰

不使用 CryptographicKeys 元素。