在 Azure Active Directory B2C 自定義原則中定義 OAuth2 自定義錯誤技術配置檔

發行項
06/13/2024

本文說明如何使用 Azure Active Directory B2C （Azure AD B2C）處理 OAuth2 自定義錯誤。如果您的原則內發生錯誤邏輯，請使用此技術配置檔。技術配置檔會將錯誤傳回您的 OAuth2 或 OpenId Connect 信賴憑證者應用程式。查看 OAuth2 自定義錯誤技術配置檔的即時示範。

若要處理自定義 OAuth2 錯誤訊息：

定義 OAuth2 錯誤技術配置檔。
設定錯誤碼和錯誤訊息宣告。
從使用者旅程圖中，呼叫 OAuth2 錯誤技術配置檔。

OAuth2 錯誤

錯誤會以下欄資料傳回：

錯誤 - access_denied
error_description - 使用慣例AAD_Custom_<errorCode>: <errorMessage>的錯誤訊息。
相互關聯標識碼 - Azure AD B2C 相互關聯標識碼。
Timestamp - 錯誤的時間戳。

下列範例示範傳回應用程式的 https://jwt.ms 自定義錯誤訊息：

https://jwt.ms/#error=access_denied&error_description=AAD_Custom_1234%3a+My+custom+error+message%0d%0aCorrelation+ID%3a+233bf9bd-747a-4800-9062-6236f3f69a47%0d%0aTimestamp%3a+2021-03-25+14%3a01%3a23Z%0d%0a

通訊協定

Protocol 元素的 Name 屬性必須設定為 OAuth2。將 OutputTokenFormat 元素設定為 OAuth2Error。

下列範例顯示的技術設定檔 ReturnOAuth2Error：

<!--
 <ClaimsProviders> -->
  <ClaimsProvider>
    <DisplayName>Token Issuer</DisplayName>
    <TechnicalProfiles>
      <TechnicalProfile Id="ReturnOAuth2Error">
        <DisplayName>Return OAuth2 error</DisplayName>
        <Protocol Name="OAuth2" />
        <OutputTokenFormat>OAuth2Error</OutputTokenFormat>
        <CryptographicKeys>
          <Key Id="issuer_secret" StorageReferenceId="B2C_1A_TokenSigningKeyContainer" />
        </CryptographicKeys>
        <InputClaims>
          <InputClaim ClaimTypeReferenceId="errorCode" />
          <InputClaim ClaimTypeReferenceId="errorMessage" />
        </InputClaims>
      </TechnicalProfile>
    </TechnicalProfiles>
  </ClaimsProvider>
<!--
</ClaimsProviders> -->

定義宣告轉換以產生錯誤碼和錯誤訊息的自定義值

使用下列步驟來產生錯誤碼和錯誤訊息的自訂值：

ClaimsTransformations找出元素，然後在其中新增下列程序代碼

<!--
 <ClaimsTransformations> -->
<ClaimsTransformation Id="GenerateErrorCode" TransformationMethod="CreateStringClaim">
        <InputParameters>
          <InputParameter Id="value" DataType="string" Value="Error_001" />
        </InputParameters>
        <OutputClaims>
          <OutputClaim ClaimTypeReferenceId="errorCode" TransformationClaimType="createdClaim" />
        </OutputClaims>
      </ClaimsTransformation>
      <ClaimsTransformation Id="GenerateErrorMessage" TransformationMethod="CreateStringClaim">
        <InputParameters>
          <InputParameter Id="value" DataType="string" Value="Insert error description." />
        </InputParameters>
        <OutputClaims>
          <OutputClaim ClaimTypeReferenceId="errorMessage" TransformationClaimType="createdClaim" />
        </OutputClaims>
      </ClaimsTransformation>
<!--
</ClaimsTransformations> -->

在您定義的 OAuth2 技術之前，在任一技術配置檔的元素中 OutputClaimsTransformations 新增兩個宣告轉換：

    <OutputClaimsTransformations>
      <OutputClaimsTransformation ReferenceId="generateErrorCode" />
      <OutputClaimsTransformation ReferenceId="generateErrorMessage" />
    </OutputClaimsTransformations>

輸入宣告

InputClaims 元素包含傳回 OAuth2 錯誤所需的宣告清單。

ClaimReferenceId	必要	Description
errorCode	Yes	錯誤碼。
errorMessage	Yes	錯誤訊息。

密碼編譯金鑰

CryptographicKeys 元素包含下列密鑰：

屬性	必要	描述
issuer_secret	Yes	X509 憑證（RSA 金鑰集）。 `B2C_1A_TokenSigningKeyContainer`使用您在開始使用自訂原則中設定的金鑰。

叫用技術配置檔

您可以從使用者旅程圖或子旅程圖呼叫 OAuth2 錯誤技術配置檔（類型transfer）。使用 OAuth2 錯誤技術設定檔的參考，將協調流程步驟類型設定為 SendClaims 。

如果您的使用者旅程圖或子旅程圖已有另一個 SendClaims 協調流程步驟，請將 DefaultCpimIssuerTechnicalProfileReferenceId 屬性設定為令牌簽發者技術配置檔。

在以下範例中：

使用者旅程圖 SignUpOrSignIn-Custom 會設定 DefaultCpimIssuerTechnicalProfileReferenceId 為權杖簽發者技術設定檔 JwtIssuer。
第八個協調流程步驟會檢查是否存在 errorCode 。如果是，請呼叫 ReturnOAuth2Error 技術配置檔以傳回錯誤。
如果 errorCode 不存在，第九個協調流程步驟會發出令牌。

<UserJourney Id="SignUpOrSignIn-Custom" DefaultCpimIssuerTechnicalProfileReferenceId="JwtIssuer">
  <OrchestrationSteps>
    ...
    <OrchestrationStep Order="8" Type="SendClaims" CpimIssuerTechnicalProfileReferenceId="ReturnOAuth2Error">
      <Preconditions>
        <Precondition Type="ClaimsExist" ExecuteActionsIf="false">
          <Value>errorCode</Value>
          <Action>SkipThisOrchestrationStep</Action>
        </Precondition>
      </Preconditions>
    </OrchestrationStep>

    <OrchestrationStep Order="9" Type="SendClaims" CpimIssuerTechnicalProfileReferenceId="JwtIssuer" />

  </OrchestrationSteps>
  <ClientDefinition ReferenceId="DefaultWeb" />
</UserJourney>

您可以選擇性地使用前置條件來操作 OAuth2 錯誤技術配置檔。例如，如果沒有電子郵件宣告，您可以設定為呼叫 OAuth2 錯誤技術設定檔：

<OrchestrationStep Order="3" Type="SendClaims" CpimIssuerTechnicalProfileReferenceId="ReturnOAuth2Error">
      <Preconditions>
        <Precondition Type="ClaimsExist" ExecuteActionsIf="false">
          <Value>email</Value>
          <Action>SkipThisOrchestrationStep</Action>
        </Precondition>
      </Preconditions>
    </OrchestrationStep>

下一步

瞭解 UserJourneys

共用方式為