处理 MSAL.NET 中的错误和异常

本文概述不同类型的错误，并提供处理常见登录错误的相关建议。

MSAL 错误处理基础知识

Microsoft 身份验证库 (MSAL) 中的异常旨在帮助应用开发者进行故障排除，而不会向最终用户显示。 异常消息未经本地化。

处理异常和错误时，可以使用异常类型本身和错误代码来区分不同的异常。 有关错误代码的列表，请参阅 Microsoft Entra 身份验证和授权错误代码。

在登录体验期间，可能会遇到有关许可、条件访问（MFA、设备管理、基于位置的限制）、令牌颁发和兑换以及用户属性的错误。

以下部分提供了有关应用错误处理的更多详细信息。

MSAL.NET 中的错误处理

异常类型

当库本身检测到错误状态（例如配置错误）时，将引发 MsalClientException。

当标识提供者（Microsoft Entra ID）返回错误响应时，将引发 MsalServiceException。 这是对服务器错误信息的翻译。

MsalUIRequiredException 是 MsalServiceException 的类型，指示需要用户交互。 例如，当需要多重身份验证（MFA）或用户更改其密码且无法以无提示方式获取令牌时。

处理异常

处理.NET异常时，可以使用异常类型本身和ErrorCode成员来区分异常。 ErrorCode 值是 MsalError 类型的常量。

还可以查看 MsalClientException、 MsalServiceException 和 MsalUIRequiredException 的字段。

如果抛出了 MsalServiceException，请参阅 身份验证和授权错误代码，查看其中是否列出了该代码。

如果抛出 MsalUIRequiredException，则表明需要进行交互式流程，以便用户解决该问题。 在桌面和移动应用等公共客户端应用中，通过调用 AcquireTokenInteractive来解决此问题，它显示浏览器。 在机密客户端应用中，Web 应用应将用户重定向到授权页，Web API 应返回 HTTP 状态代码和标头，指示身份验证失败（401 未授权和 WWW-Authenticate 标头）。

常见.NET异常

下面是可能引发的常见异常和一些可能的缓解措施：

MsalUiRequiredException

调用AcquireTokenSilent()时，MSAL.NET 返回的常见状态代码之一是MsalError.InvalidGrantError。 此状态代码表示应用程序应再次调用身份验证库，但要在交互模式下调用（用于公共客户端应用程序的 AcquireTokenInteractive 或 AcquireTokenByDeviceCodeFlow 会在 Web 应用中执行质询）。 这是因为在颁发身份验证令牌之前需要其他用户交互。

大多数情况下 AcquireTokenSilent 失败时，这是因为令牌缓存没有与请求匹配的令牌。 访问令牌在 1 小时内过期，并 AcquireTokenSilent 尝试基于刷新令牌提取新令牌（在 OAuth2 术语中，这是“刷新令牌”流）。 此流也可能因各种原因而失败，例如，如果租户管理员配置更严格的登录策略。

交互旨在让用户执行操作。 其中一些条件便于用户解决（例如，单击一下即可接受使用条款），有些条件无法通过当前配置解决（例如，相关计算机需要连接到特定的公司网络）。 有些帮助用户设置多重身份验证，或在其设备上安装Microsoft Authenticator。

MsalUiRequiredException 分类枚举

MSAL 公开一个 Classification 字段，你可以阅读该字段以提供更好的用户体验。 例如，若要告知用户其密码已过期，或者他们需要提供许可才能使用某些资源。 支持的值是 UiRequiredExceptionClassification 枚举的一部分：

.NET代码示例

AuthenticationResult res;
try
{
 res = await application.AcquireTokenSilent(scopes, account)
        .ExecuteAsync();
}
catch (MsalUiRequiredException ex) when (ex.ErrorCode == MsalError.InvalidGrantError)
{
 switch (ex.Classification)
 {
  case UiRequiredExceptionClassification.None:
   break;
  case UiRequiredExceptionClassification.MessageOnly:
  // You might want to call AcquireTokenInteractive(). Azure AD will show a message
  // that explains the condition. AcquireTokenInteractively() will return UserCanceled error
  // after the user reads the message and closes the window. The calling application may choose
  // to hide features or data that result in message_only if the user is unlikely to benefit 
  // from the message
  try
  {
      res = await application.AcquireTokenInteractive(scopes).ExecuteAsync();
  }
  catch (MsalClientException ex2) when (ex2.ErrorCode == MsalError.AuthenticationCanceledError)
  {
   // Do nothing. The user has seen the message
  }
  break;

  case UiRequiredExceptionClassification.BasicAction:
  // Call AcquireTokenInteractive() so that the user can, for instance accept terms
  // and conditions

  case UiRequiredExceptionClassification.AdditionalAction:
  // You might want to call AcquireTokenInteractive() to show a message that explains the remedial action. 
  // The calling application may choose to hide flows that require additional_action if the user 
  // is unlikely to complete the remedial action (even if this means a degraded experience)

  case UiRequiredExceptionClassification.ConsentRequired:
  // Call AcquireTokenInteractive() for user to give consent.
  
  case UiRequiredExceptionClassification.UserPasswordExpired:
  // Call AcquireTokenInteractive() so that user can reset their password
  
  case UiRequiredExceptionClassification.PromptNeverFailed:
  // You used WithPrompt(Prompt.Never) and this failed
  
  case UiRequiredExceptionClassification.AcquireTokenSilentFailed:
  default:
  // May be resolved by user interaction during the interactive authentication flow.
  res = await application.AcquireTokenInteractive(scopes)
                         .ExecuteAsync(); break;
 }
}

条件访问和声明质询

以静默方式获取令牌时，如果你尝试访问的 API 需要条件访问声明质询（例如 MFA 策略），则应用程序可能会收到错误。

处理此错误的模式是使用 MSAL 以交互方式获取令牌。 这会提示用户，并使他们能够满足所需的条件访问策略。

在某些情况下调用需要条件访问的 API 时，API 返回的错误中可能会包含声明质询。 例如，如果条件访问策略要求使用托管设备 (Intune)，则错误将类似于 AADSTS53000:需要管理你的设备才能访问此资源。 在这种情况下，可以在获取令牌调用中传递声明，以提示用户满足相应的策略要求。

当从 MSAL.NET 调用需要条件访问的 API 时，你的应用需要处理声明质询异常。 这表现为 MsalServiceException，其中 Claims 属性不为空。

若要处理声明质询，请使用 WithClaims(String)。

出现错误和异常后重试

调用 MSAL 时，应实现自己的重试策略。 MSAL 会对 Microsoft Entra 服务进行 HTTP 调用，有时会失败。 例如网络崩溃或服务器重载。

HTTP 429

如果服务令牌服务器 (STS) 因请求过多而重载，则将返回 HTTP 错误 429，并在 Retry-After 响应字段中提示还要多久才能重试。

HTTP 错误代码 500-600

MSAL.NET 为 HTTP 错误代码 500-600 的错误实现简单的重试一次机制。

MsalServiceException 以属性System.Net.Http.Headers.HttpResponseHeaders的形式浮出水面namedHeaders。 可以使用错误代码中的其他信息来提高应用程序的可靠性。 在上述情况下，可以使用 RetryAfter 属性（类型为 RetryConditionHeaderValue），并计算何时重试。

下面是使用客户端凭据流的守护程序应用程序的示例。 你可以将其调整为适用于获取令牌的任一方法。

bool retry = false;
do
{
    TimeSpan? delay;
    try
    {
         result = await publicClientApplication.AcquireTokenForClient(scopes, account).ExecuteAsync();
    }
    catch (MsalServiceException serviceException)
    {
         if (serviceException.ErrorCode == "temporarily_unavailable")
         {
             RetryConditionHeaderValue retryAfter = serviceException.Headers.RetryAfter;
             if (retryAfter.Delta.HasValue)
             {
                 delay = retryAfter.Delta;
             }
             else if (retryAfter.Date.HasValue)
             {
                 delay = (retryAfter.Date.Value – DateTimeOffset.Now).TotalMilliseconds;
             }
         }
    }
    // . . .
    if (delay.HasValue)
    {
        Thread.Sleep((int)delay.Value.TotalMilliseconds); // sleep or other
        retry = true;
    }
} while (retry);

后续步骤

请考虑启用 MSAL.NET 中的日志记录，以帮助你诊断和调试问题。