Behandeln von Fehlern und Ausnahmen in MSAL.NET

In diesem Artikel finden Sie eine Übersicht über die verschiedenen Arten von Fehlern und Empfehlungen für die Behandlung häufiger Anmeldefehler.

Grundlagen zur MSAL-Fehlerbehandlung

Ausnahmen in Microsoft Authentication Library (MSAL) (MSAL) sind für App-Entwickler vorgesehen, um Probleme zu beheben, nicht für die Anzeige für Endbenutzer. Ausnahmemeldungen werden nicht lokalisiert.

Bei der Verarbeitung von Ausnahmen und Fehlern können Sie den Ausnahmetyp selbst und den Fehlercode verwenden, um zwischen Ausnahmen zu unterscheiden. Eine Liste der Fehlercodes finden Sie unter Microsoft Entra Authentifizierungs- und Autorisierungsfehlercodes.

Während der Anmeldeumgebung treten möglicherweise Fehler bezüglich Zustimmungen, bedingter Zugriff (MFA, Geräteverwaltung, Standortbasierte Einschränkungen), Tokenausstellung und Einlösung sowie Benutzereigenschaften auf.

Der folgende Abschnitt enthält weitere Details zur Fehlerbehandlung für Ihre App.

Fehlerbehandlung in MSAL.NET

Ausnahmetypen

MsalClientException wird ausgelöst, wenn die Bibliothek selbst einen Fehlerzustand erkennt, z. B. eine fehlerhafte Konfiguration.

MsalServiceException wird ausgelöst, wenn der Identitätsanbieter (Microsoft Entra ID) einen Fehler zurückgibt. Dies ist eine Übersetzung des Serverfehlers.

MsalUIRequiredException ist der Typ von MsalServiceException und gibt an, dass eine Benutzerinteraktion erforderlich ist. Wenn z. B. die mehrstufige Authentifizierung (Multifactor Authentication, MFA) erforderlich ist oder der Benutzer sein Kennwort ändert und ein Token nicht automatisch abgerufen werden kann.

Verarbeiten von Ausnahmen

Bei der Verarbeitung .NET Ausnahmen können Sie den Ausnahmetyp selbst und das ErrorCode Element verwenden, um zwischen Ausnahmen zu unterscheiden. ErrorCode Werte sind Konstanten vom Typ MsalError.

Sie können auch die Felder "MsalClientException", "MsalServiceException" und "MsalUIRequiredException" betrachten.

Wenn MsalServiceException ausgelöst wird, prüfen Sie unter Authentifizierungs- und Autorisierungsfehlercodes, ob der Code dort aufgeführt ist.

Wenn MsalUIRequiredException ausgelöst wird, ist es ein Hinweis darauf, dass ein interaktiver Fluss ausgeführt werden muss, damit der Benutzer das Problem beheben kann. In öffentlichen Client-Apps wie Desktop- und mobiler App wird dies durch Aufrufen AcquireTokenInteractiveaufgelöst, wodurch ein Browser angezeigt wird. In vertraulichen Client-Apps sollten Web-Apps den Benutzer auf die Autorisierungsseite umleiten, und Web-APIs sollten einen HTTP-Statuscode und header für den Authentifizierungsfehler zurückgeben (401 Nicht autorisiert und ein WWW-Authenticate Header).

Allgemeine .NET Ausnahmen

Hier sind die häufigen Ausnahmen, die möglicherweise ausgelöst werden können, sowie einige mögliche Abhilfemaßnahmen:

MsalUiRequiredException

Einer der allgemeinen Statuscodes, die beim Aufrufen AcquireTokenSilent() von MSAL.NET zurückgegeben werden, ist MsalError.InvalidGrantError. Dieser Statuscode bedeutet, dass die Anwendung die Authentifizierungsbibliothek erneut aufrufen soll, aber im interaktiven Modus (AcquireTokenInteractive oder AcquireTokenByDeviceCodeFlow für öffentliche Clientanwendungen, haben eine Herausforderung in Web-Apps). Dies liegt daran, dass zusätzliche Benutzerinteraktionen erforderlich sind, bevor ein Authentifizierungstoken ausgegeben werden kann.

Meistens liegt ein Fehlschlag von AcquireTokenSilent daran, dass der Token-Cache keine Token enthält, die Ihrer Anforderung entsprechen. Zugriffstoken laufen in einer Stunde ab und AcquireTokenSilent versucht, ein neues token basierend auf einem Aktualisierungstoken abzurufen (in OAuth2-Ausdrücken ist dies der Fluss "Aktualisierungstoken"). Dieser Ablauf kann aus verschiedenen Gründen auch fehlschlagen, z. B. wenn ein Mandantenadministrator strengere Anmelderichtlinien konfiguriert.

Die Interaktion zielt darauf ab, dass der Benutzer eine Aktion ausführen kann. Einige dieser Bedingungen sind für Benutzer leicht zu beheben (z. B. akzeptieren Sie die Nutzungsbedingungen mit einem einzigen Klick), und einige können nicht mit der aktuellen Konfiguration aufgelöst werden (z. B. muss der betreffende Computer eine Verbindung mit einem bestimmten Unternehmensnetzwerk herstellen). Einige helfen dem Benutzer beim Einrichten der mehrstufigen Authentifizierung oder beim Installieren von Microsoft Authenticator auf dem Gerät.

MsalUiRequiredException Klassifizierungsaufzählung

MSAL macht ein Classification Feld verfügbar, das Sie lesen können, um eine bessere Benutzererfahrung bereitzustellen. Um dem Benutzer beispielsweise mitzuteilen, dass sein Kennwort abgelaufen ist oder dass er die Zustimmung zur Verwendung einiger Ressourcen erteilen muss. Die unterstützten Werte gehören zur UiRequiredExceptionClassification-Enumeration:

.NET Codebeispiel

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;
 }
}

Herausforderungen für bedingten Zugriff und Ansprüche

Beim stillen Abrufen von Token kann bei Ihrer Anwendung ein Fehler auftreten, wenn eine API, auf die Sie zugreifen möchten, eine Anspruchsanforderung für den bedingten Zugriff erfordert, z. B. eine MFA-Richtlinie.

Das Muster für die Behandlung dieses Fehlers besteht darin, ein Token mithilfe von MSAL interaktiv abzurufen. Dadurch wird der Benutzer aufgefordert und erhält die Möglichkeit, die erforderliche Richtlinie für bedingten Zugriff zu erfüllen.

In bestimmten Fällen können Sie beim Aufrufen einer API, die Bedingten Zugriff erfordert, in der Fehlermeldung der API eine Claims-Abfrage erhalten. Wenn beispielsweise die Richtlinie für den bedingten Zugriff über ein verwaltetes Gerät (Intune) verfügt, ist der Fehler etwa AADSTS53000: Ihr Gerät muss verwaltet werden, um auf diese Ressource oder etwas ähnliches zuzugreifen. In diesem Fall können Sie die Claims beim Aufruf zum Abrufen eines Tokens übergeben, damit der Benutzer aufgefordert wird, die Anforderungen der entsprechenden Richtlinie zu erfüllen.

Beim Aufrufen einer API, die bedingten Zugriff von MSAL.NET erfordert, muss Ihre Anwendung Ausnahmen von Anspruchsabfragen behandeln. Dies wird als MsalServiceException angezeigt, bei der die Claims-Eigenschaft nicht leer ist.

Um die Anspruchsanfechtung zu bearbeiten, verwenden Sie WithClaims(String).

Wiederholen nach Fehlern und Ausnahmen

Beim Aufrufen von MSAL müssen Sie Ihre eigenen Wiederholungsrichtlinien implementieren. MSAL führt HTTP-Aufrufe an den Microsoft Entra Dienst aus, und gelegentlich können Fehler auftreten. Beispielsweise kann das Netzwerk nach unten gehen oder der Server überlastet ist.

HTTP 429

Wenn der Diensttokenserver (Service Token Server, STS) mit zu vielen Anfragen überlastet ist, gibt er den HTTP-Fehler 429 mit einem Hinweis darauf zurück, wann Sie es im Antwortfeld Retry-After erneut versuchen können.

HTTP-Fehlercodes 500-600

MSAL.NET implementiert einen einfachen Wiederholungsmechanismus für Fehler mit HTTP-Fehlercodes 500-600.

MsalServiceException wird als Eigenschaft System.Net.Http.Headers.HttpResponseHeadersangezeigtnamedHeaders. Sie können zusätzliche Informationen aus dem Fehlercode verwenden, um die Zuverlässigkeit Ihrer Anwendungen zu verbessern. In dem beschriebenen Fall können Sie die RetryAfter Eigenschaft (vom Typ RetryConditionHeaderValue) verwenden und berechnen, wann sie erneut versuchen.

Hier ist ein Beispiel für eine Daemon-Anwendung mit dem Client-Credentials-Flow. Sie können dies auf jede der Methoden zum Abrufen eines Tokens anpassen.

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);

Nächste Schritte

Erwägen Sie, die Protokollierung in MSAL.NET zu aktivieren, um Probleme zu diagnostizieren und zu debuggen.