UserJourneys

發行項
08/09/2024

注意

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

使用者旅程圖會指定明確的路徑，原則可透過這類路徑來讓信賴憑證者應用程式取得使用者所需的宣告。使用者會透過這些路徑來擷取要呈現給信賴憑證者的宣告。換句話說，使用者旅程圖會定義終端使用者在 Azure AD B2C 身分識別體驗架構處理要求時所經歷的商業規則。

這些使用者旅程圖可視為範本，以滿足社群各信賴憑證者的核心需求。使用者旅程圖可協助定義原則的信賴憑證者部分。原則可以定義多個使用者旅程圖。每個使用者旅程圖都是一連串的協調流程步驟。

若要定義原則所支援的使用者旅程圖， UserJourneys 則會在原則檔案的最上層 TrustFrameworkPolicy 元素下新增元素。

<TrustFrameworkPolicy  ...>
  ...
  <UserJourneys>
    ...
  </UserJourneys>
</TrustFrameworkPolicy>

UserJourneys 元素包含下列元素：

元素	發生次數	描述
UserJourney	1：n	使用者旅程圖，定義完整使用者流程所需的所有建構。

UserJourney 元素包含下列屬性：

屬性	必要	描述
Id	Yes	使用者旅程圖的標識碼，可用來從原則中的其他元素參考它。信賴憑證者原則的DefaultUserJourney元素會指向此屬性。
DefaultCpimIssuerTechnicalProfileReferenceId	No	默認令牌簽發者技術配置文件參考標識碼。例如， JWT 令牌簽發者、 SAML 令牌簽發者或 OAuth2 自定義錯誤。如果您的使用者旅程圖或子旅程圖已有另一個 `SendClaims` 協調流程步驟，請將屬性設定 `DefaultCpimIssuerTechnicalProfileReferenceId` 為使用者旅程圖的令牌簽發者技術配置檔。

UserJourney 元素包含下列元素：

元素	發生次數	描述
AuthorizationTechnicalProfiles	0:1	授權技術配置檔清單。
OrchestrationSteps	1：n	必須遵循才能成功交易的協調流程順序。每個使用者旅程圖都包含循序執行的協調流程步驟清單。如果有任何步驟失敗，交易就會失敗。

AuthorizationTechnicalProfiles

假設使用者已完成 UserJourney 並取得存取權或標識碼令牌。若要管理其他資源，例如 UserInfo端點，必須識別使用者。若要開始此程式，用戶必須出示稍早發出的存取令牌，證明其原本是由有效的 Azure AD B2C 原則驗證。使用者的有效令牌必須一律存在此程式期間，以確保允許使用者提出此要求。授權技術配置檔會驗證傳入令牌，並從令牌擷取宣告。

AuthorizationTechnicalProfiles 元素包含下列元素：

元素	發生次數	描述
AuthorizationTechnicalProfile	0:1	用來授權用戶的技術配置文件參考。

AuthorizationTechnicalProfile 元素包含下列屬性：

屬性	必要	描述
ReferenceId	Yes	要執行之技術配置文件的標識碼。

下列範例顯示具有授權技術設定檔的使用者旅程圖元素：

<UserJourney Id="UserInfoJourney" DefaultCpimIssuerTechnicalProfileReferenceId="UserInfoIssuer">
  <Authorization>
    <AuthorizationTechnicalProfiles>
      <AuthorizationTechnicalProfile ReferenceId="UserInfoAuthorization" />
    </AuthorizationTechnicalProfiles>
  </Authorization>
  <OrchestrationSteps>
    <OrchestrationStep Order="1" Type="ClaimsExchange">
     ...

OrchestrationSteps

使用者旅程圖會以協調流程順序表示，必須遵循才能成功交易。如果有任何步驟失敗，交易就會失敗。這些協調流程步驟會參考原則檔案中允許的建置組塊和宣告提供者。負責顯示或轉譯用戶體驗的任何協調流程步驟，也會參考對應的內容定義標識符。

協調流程步驟可以根據協調流程步驟元素中定義的前置條件，有條件地執行。例如，只有當特定宣告存在，或宣告等於或不等於指定的值時，您才能檢查是否執行協調流程步驟。

若要指定已排序的協調流程步驟清單， 會將 OrchestrationSteps 元素新增為原則的一部分。此項目為必要項。

<UserJourney Id="SignUpOrSignIn">
  <OrchestrationSteps>
    <OrchestrationStep Order="1" Type="CombinedSignInAndSignUp" ContentDefinitionReferenceId="api.signuporsignin">
      ...

OrchestrationSteps 元素包含下列元素：

元素	發生次數	描述
OrchestrationStep	1：n	已排序的協調流程步驟。

OrchestrationStep 元素包含下列屬性：

屬性	必要	描述:
`Order`	Yes	協調流程步驟的順序。屬性的值`Order`從開始`1`。`N` 因此，如果您有10個步驟，而您刪除第二個步驟，則必須重新編號步驟3到10，以變成2到9。
`Type`	Yes	協調流程步驟的類型。可能的值： ClaimsProviderSelection - 指出協調流程步驟會向使用者呈現各種宣告提供者，以選取一個宣告提供者。 CombinedSignInAndSignUp - 指出協調流程步驟會顯示合併的社交提供者登入和本機帳戶註冊頁面。 ClaimsExchange - 指出協調流程步驟會與宣告提供者交換宣告。 GetClaims - 指定協調流程步驟應該透過其 `InputClaims` 設定處理從信賴憑證者傳送至 Azure AD B2C 的宣告數據。 InvokeSubJourney - 指出協調流程步驟會與子旅程交換宣告。 SendClaims - 指出協調流程步驟會使用宣告簽發者所簽發的令牌，將宣告傳送至信賴憑證者。
ContentDefinitionReferenceId	No	與此協調流程步驟相關聯的內容定義標識符。內容定義參考標識碼通常定義於自我判斷技術配置檔中。但是，在某些情況下，Azure AD B2C 需要顯示沒有技術配置文件的內容。有兩個範例 - 如果協調流程步驟的類型如下： `ClaimsProviderSelection` 或 `CombinedSignInAndSignUp`，Azure AD B2C 必須顯示識別提供者選取專案，而不需要技術配置檔。
CpimIssuerTechnicalProfileReferenceId	No	協調流程步驟的類型為 `SendClaims`。這個屬性會定義發出信賴憑證者令牌之宣告提供者的技術配置檔標識碼。如果不存在，則不會建立任何信賴憑證者令牌。

OrchestrationStep 元素可以包含下列元素：

元素	發生次數	描述
前置條件	0：n	必須滿足協調流程步驟才能執行的先決條件清單。
ClaimsProviderSelections	0：n	協調流程步驟的宣告提供者選取項目清單。
ClaimsExchanges	0：n	協調流程步驟的宣告交換清單。
JourneyList	0:1	協調流程步驟的子旅程候選項目清單。

前置條件

協調流程步驟可以根據協調流程步驟中定義的前置條件，有條件地執行。元素 Preconditions 包含要評估的前置條件清單。滿足前置條件評估時，相關聯的協調流程步驟會跳到下一個協調流程步驟。

Azure AD B2C 會依清單順序評估前置條件。以順序為基礎的前置條件可讓您設定套用前置條件的順序。滿足的第一個前置條件會覆寫所有後續前置條件。只有在不符合所有先決條件時，才會執行協調流程步驟。

Preconditions 元素包含下列元素：

元素	發生次數	描述
先決條件	1：n	要評估的前置條件。

先決條件

Precondition 元素包含下列屬性：

屬性	必要	描述:
`Type`	Yes	要針對這個前置條件執行的檢查或查詢類型。值可以是 ClaimsExist，指定如果指定的宣告存在於使用者目前的宣告集中，則應該執行動作，或 ClaimEquals，指定當指定的宣告存在且其值等於指定的值時，應該執行動作。
`ExecuteActionsIf`	Yes	決定如何滿足前置條件。可能的值： `true`、或 `false`。如果值設定為 `true`，當宣告符合前置條件時，就會將其視為滿足。如果值設定為 `false`，當宣告不符合前置條件時，就會將其視為滿足。

前置條件元素包含下列元素：

元素	發生次數	描述
值	1:2	宣告類型的識別碼。宣告已在原則檔或父原則檔案的宣告架構區段中定義。當前置條件是的型 `ClaimEquals`別時，第二 `Value` 個元素會包含要檢查的值。
動作	1:1	如果滿足前置條件評估，則應該執行的動作。可能值：`SkipThisOrchestrationStep`。相關聯的協調流程步驟會跳到下一個步驟。

每個前置條件都會評估單一宣告。有兩種類型的前置條件：

ClaimsExist - 指定如果指定的宣告存在於使用者目前的宣告包中，則應該執行動作。
ClaimEquals - 指定當指定的宣告存在時，應該執行動作，而且其值等於指定的值。檢查會執行區分大小寫的序數比較。檢查布林宣告類型時，請使用 True、或 False。

如果宣告為 Null 或未初始化，則會忽略前置條件，無論是 ExecuteActionsIf true、或 false。最佳做法是檢查宣告是否存在，並等於值。

例如，如果使用者已 MfaPreference 將設定為 Phone，則挑戰 MFA 的使用者。若要執行此條件式邏輯，請檢查宣告是否存在 MfaPreference ，並檢查宣告值是否等於 Phone。下列 XML 示範如何使用前置條件來實作此邏輯。

<Preconditions>
  <!-- Skip this orchestration step if MfaPreference doesn't exist. -->
  <Precondition Type="ClaimsExist" ExecuteActionsIf="false">
    <Value>MfaPreference</Value>
    <Action>SkipThisOrchestrationStep</Action>
  </Precondition>
  <!-- Skip this orchestration step if MfaPreference doesn't equal to Phone. -->
  <Precondition Type="ClaimEquals" ExecuteActionsIf="false">
    <Value>MfaPreference</Value>
    <Value>Phone</Value>
    <Action>SkipThisOrchestrationStep</Action>
  </Precondition>
</Preconditions>

前置條件範例

下列前置條件會檢查使用者的 objectId 是否存在。在使用者旅程圖中，用戶已選取使用本機帳戶登入。如果 objectId 存在，請略過此協調流程步驟。

<OrchestrationStep Order="2" Type="ClaimsExchange">
  <Preconditions>
    <Precondition Type="ClaimsExist" ExecuteActionsIf="true">
      <Value>objectId</Value>
      <Action>SkipThisOrchestrationStep</Action>
    </Precondition>
  </Preconditions>
  <ClaimsExchanges>
    <ClaimsExchange Id="FacebookExchange" TechnicalProfileReferenceId="Facebook-OAUTH" />
    <ClaimsExchange Id="SignUpWithLogonEmailExchange" TechnicalProfileReferenceId="LocalAccountSignUpWithLogonEmail" />
  </ClaimsExchanges>
</OrchestrationStep>

下列先決條件會檢查使用者是否使用社交帳戶登入。嘗試在目錄中尋找用戶帳戶。如果使用者使用本機帳戶登入或註冊，請略過此協調流程步驟。

<OrchestrationStep Order="3" Type="ClaimsExchange">
  <Preconditions>
    <Precondition Type="ClaimEquals" ExecuteActionsIf="true">
      <Value>authenticationSource</Value>
      <Value>localAccountAuthentication</Value>
      <Action>SkipThisOrchestrationStep</Action>
    </Precondition>
  </Preconditions>
  <ClaimsExchanges>
    <ClaimsExchange Id="AADUserReadUsingAlternativeSecurityId" TechnicalProfileReferenceId="AAD-UserReadUsingAlternativeSecurityId-NoError" />
  </ClaimsExchanges>
</OrchestrationStep>

前置條件可以檢查多個前置條件。下列範例會檢查 'objectId' 或 'email' 是否存在。如果第一個條件為 true，則旅程會跳到下一個協調流程步驟。

<OrchestrationStep Order="4" Type="ClaimsExchange">
  <Preconditions>
    <Precondition Type="ClaimsExist" ExecuteActionsIf="true">
      <Value>objectId</Value>
      <Action>SkipThisOrchestrationStep</Action>
    </Precondition>
    <Precondition Type="ClaimsExist" ExecuteActionsIf="true">
      <Value>email</Value>
      <Action>SkipThisOrchestrationStep</Action>
    </Precondition>
  </Preconditions>
  <ClaimsExchanges>
    <ClaimsExchange Id="SelfAsserted-SocialEmail" TechnicalProfileReferenceId="SelfAsserted-SocialEmail" />
  </ClaimsExchanges>
</OrchestrationStep>

宣告提供者選取

宣告提供者選取可讓使用者從選項清單中選取動作。識別提供者選取包含兩個協調流程步驟：

按鈕 - 其開頭為類型ClaimsProviderSelection，或CombinedSignInAndSignUp包含使用者可以選擇的選項清單。元素內 ClaimsProviderSelections 選項的順序會控制向用戶顯示的按鈕順序。
動作 - 後面接著的類型 ClaimsExchange。 ClaimsExchange 包含動作清單。動作是技術配置文件的參考，例如 OAuth2、 OpenID Connect、宣告轉換或自我判斷。當使用者按兩下其中一個按鈕時，就會執行對應的動作。

ClaimsProviderSelections 元素包含下列元素：

元素	發生次數	描述
ClaimsProviderSelection	1：n	提供可選取的宣告提供者清單。

ClaimsProviderSelections 元素包含下列屬性：

屬性	必要	描述
DisplayOption	No	控制單一宣告提供者選取專案可用案例的行為。可能的值： `DoNotShowSingleProvider` （預設值），使用者會立即重新導向至同盟識別提供者。或者 `ShowSingleProvider` ，Azure AD B2C 會顯示具有單一識別提供者選取專案的登入頁面。若要使用這個屬性，內容定義版本必須是 `urn:com:microsoft:aad:b2c:elements:contract:providerselection:1.0.0` 和更新版本。

ClaimsProviderSelection 元素包含下列屬性：

屬性	必要	描述
TargetClaimsExchangeId	No	宣告交換的標識碼，這會在宣告提供者選取的下一個協調流程步驟中執行。必須指定這個屬性或 ValidationClaimsExchangeId 屬性，但不能同時指定這兩個屬性。
ValidationClaimsExchangeId	No	宣告交換的標識碼，會在目前的協調流程步驟中執行，以驗證宣告提供者選取專案。必須指定此屬性或 TargetClaimsExchangeId 屬性，但不能同時指定這兩個屬性。

宣告提供者選取範例

在下列協調流程步驟中，用戶可以選擇使用 Facebook、LinkedIn、X、Google 或本機帳戶登入。如果用戶選取其中一個社交識別提供者，則第二個協調流程步驟會使用屬性中指定的 TargetClaimsExchangeId 選取宣告交換來執行。第二個協調流程步驟會將使用者重新導向至社交識別提供者，以完成登入程式。如果用戶選擇使用本機帳戶登入，Azure AD B2C 會保持相同的協調流程步驟（相同的註冊頁面或登入頁面），並略過第二個協調流程步驟。

<OrchestrationStep Order="1" Type="CombinedSignInAndSignUp" ContentDefinitionReferenceId="api.signuporsignin">
  <ClaimsProviderSelections>
    <ClaimsProviderSelection TargetClaimsExchangeId="FacebookExchange" />
    <ClaimsProviderSelection TargetClaimsExchangeId="LinkedInExchange" />
    <ClaimsProviderSelection TargetClaimsExchangeId="TwitterExchange" />
    <ClaimsProviderSelection TargetClaimsExchangeId="GoogleExchange" />
    <ClaimsProviderSelection ValidationClaimsExchangeId="LocalAccountSigninEmailExchange" />
  </ClaimsProviderSelections>
  <ClaimsExchanges>
  <ClaimsExchange Id="LocalAccountSigninEmailExchange"
        TechnicalProfileReferenceId="SelfAsserted-LocalAccountSignin-Email" />
  </ClaimsExchanges>
</OrchestrationStep>


<OrchestrationStep Order="2" Type="ClaimsExchange">
  <Preconditions>
    <Precondition Type="ClaimsExist" ExecuteActionsIf="true">
      <Value>objectId</Value>
      <Action>SkipThisOrchestrationStep</Action>
    </Precondition>
  </Preconditions>
  <ClaimsExchanges>
    <ClaimsExchange Id="FacebookExchange" TechnicalProfileReferenceId="Facebook-OAUTH" />
    <ClaimsExchange Id="SignUpWithLogonEmailExchange" TechnicalProfileReferenceId="LocalAccountSignUpWithLogonEmail" />
    <ClaimsExchange Id="GoogleExchange" TechnicalProfileReferenceId="Google-OAUTH" />
    <ClaimsExchange Id="LinkedInExchange" TechnicalProfileReferenceId="LinkedIn-OAUTH" />
    <ClaimsExchange Id="TwitterExchange" TechnicalProfileReferenceId="Twitter-OAUTH1" />
  </ClaimsExchanges>
</OrchestrationStep>

ClaimsExchanges

ClaimsExchanges 元素包含下列元素：

元素	發生次數	描述
ClaimsExchange	1：n	視所使用的技術配置檔而定，根據選取的 ClaimsProviderSelection 重新導向用戶端，或對交換宣告進行伺服器呼叫。

ClaimsExchange 元素包含下列屬性：

屬性	必要	描述
Id	Yes	宣告交換步驟的標識碼。標識碼是用來參考原則中宣告提供者選取步驟中的宣告交換。
TechnicalProfileReferenceId	Yes	要執行之技術配置文件的標識碼。

JourneyList

JourneyList 元素包含下列元素：

元素	發生次數	描述
候選項目	1:1	要呼叫之子旅程圖的參考。

候選項目

候選專案包含下列屬性：

屬性	必要	描述
SubJourneyReferenceId	Yes	要執行之子旅程圖的標識碼。

共用方式為