在 Azure Active Directory B2C 自定义策略中定义 OAuth2 自定义错误技术配置文件

本文介绍如何使用 Azure Active Directory B2C (Azure AD B2C) 处理 OAuth2 自定义错误。 如果策略中的逻辑内容出现问题,请使用此技术配置文件。 该技术配置文件会将错误返回到 OAuth2 或 OpenId Connect 信赖方应用程序。 查看 OAuth2 自定义错误技术配置文件实时演示

若要处理自定义 OAuth2 错误消息,请执行以下操作:

  1. 定义 OAuth2 错误技术配置文件。
  2. 设置错误代码,以及错误消息声明。
  3. 从用户旅程调用 OAuth2 错误技术配置文件。

OAuth2 错误

该错误会返回,包含以下数据:

  • 错误 - access_denied
  • error_description - 使用约定 AAD_Custom_<errorCode>: <errorMessage> 的错误消息。
  • 相关 ID - Azure AD B2C 相关 ID。
  • 时间戳 - 该错误的时间戳。

下面的示例演示了返回到 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> -->

定义声明转换以生成错误代码和错误消息的自定义值

通过以下步骤生成错误代码和错误消息的自定义值:

  1. 找到 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> -->
    
  2. 在你定义的、Oauth2 技术之前的任何技术配置文件的 OutputClaimsTransformations 元素中添加两个声明转换:

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

输入声明

InputClaims 元素包含返回 OAuth2 错误所需声明的列表。

ClaimReferenceId 必选 Description
errorCode 错误代码。
errorMessage 错误消息。

加密密钥

CryptographicKeys 元素包含以下密钥:

Attribute 必须 说明
issuer_secret X509 证书(RSA 密钥集)。 使用在自定义策略入门中配置的 B2C_1A_TokenSigningKeyContainer 密钥。

调用技术配置文件

你可以从用户旅程子旅程(类型transfer)中调用 OAuth2 错误技术配置文件。 将业务流程步骤类型设置为 SendClaims,并对 OAuth2 错误技术配置文件进行引用。

如果用户旅程或子旅程已经有另一个 SendClaims 业务流程步骤,请将 DefaultCpimIssuerTechnicalProfileReferenceId 属性设置为令牌颁发者技术配置文件。

如下示例中:

  • 用户旅程 SignUpOrSignIn-CustomDefaultCpimIssuerTechnicalProfileReferenceId 设置为令牌颁发者技术配置文件 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