在 Azure Active Directory B2C 自定义策略中定义 OAuth2 自定义错误技术配置文件
本文介绍如何使用 Azure Active Directory B2C (Azure AD B2C) 处理 OAuth2 自定义错误。 如果策略中的逻辑内容出现问题,请使用此技术配置文件。 该技术配置文件会将错误返回到 OAuth2 或 OpenId Connect 信赖方应用程序。 查看 OAuth2 自定义错误技术配置文件实时演示。
若要处理自定义 OAuth2 错误消息,请执行以下操作:
- 定义 OAuth2 错误技术配置文件。
- 设置错误代码,以及错误消息声明。
- 从用户旅程调用 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> -->
定义声明转换以生成错误代码和错误消息的自定义值
通过以下步骤生成错误代码和错误消息的自定义值:
找到
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 | 是 | 错误代码。 |
errorMessage | 是 | 错误消息。 |
加密密钥
CryptographicKeys 元素包含以下密钥:
Attribute | 必须 | 说明 |
---|---|---|
issuer_secret | 是 | X509 证书(RSA 密钥集)。 使用在自定义策略入门中配置的 B2C_1A_TokenSigningKeyContainer 密钥。 |
调用技术配置文件
你可以从用户旅程或子旅程(类型transfer
)中调用 OAuth2 错误技术配置文件。 将业务流程步骤类型设置为 SendClaims
,并对 OAuth2 错误技术配置文件进行引用。
如果用户旅程或子旅程已经有另一个 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