Hantera fel och undantag i MSAL.NET

Den här artikeln ger en översikt över de olika typerna av fel och rekommendationer för hantering av vanliga inloggningsfel.

Grunderna för MSAL-felhantering

Undantag i Microsofts autentiseringsbibliotek (MSAL) är avsedda för apputvecklare att felsöka, inte för att visas för slutanvändare. Undantagsmeddelanden är inte lokaliserade.

När du bearbetar undantag och fel kan du använda själva undantagstypen och felkoden för att skilja mellan undantag. En lista över felkoder finns i felkoder för Microsoft Entra autentisering och auktorisering.

Under inloggningen kan det uppstå fel om medgivanden, villkorsstyrd åtkomst (MFA, Správa zariadení, platsbaserade begränsningar), tokenutfärdande och inlösen samt användaregenskaper.

Följande avsnitt innehåller mer information om felhantering för din app.

Felhantering i MSAL.NET

Undantagstyper

MsalClientException genereras när själva biblioteket identifierar ett feltillstånd, till exempel en felaktig konfiguration.

MsalServiceException genereras när identitetsprovidern (Microsoft Entra ID) returnerar ett fel. Det är en översättning av serverfelet.

MsalUIRequiredException är en typ av MsalServiceException och anger att användarinteraktion krävs. Till exempel när multifaktorautentisering (MFA) krävs eller när användaren ändrar sitt lösenord och en token inte kan hämtas tyst.

Behandling av undantag

När du bearbetar .NET undantag kan du använda själva undantagstypen och ErrorCode medlemmen för att skilja mellan undantag. ErrorCode värden är konstanter av typen MsalError.

Du kan också ta en titt på fälten MsalClientException, MsalServiceException och MsalUIRequiredException.

Om MsalServiceException genereras kan du prova felkoder för autentisering och auktorisering för att se om koden visas där.

Om MsalUIRequiredException genereras är det en indikation på att ett interaktivt flöde måste ske för att användaren ska kunna lösa problemet. I offentliga klientappar som skrivbords- och mobilappar löses detta genom att anropa AcquireTokenInteractive, som visar en webbläsare. I konfidentiella klientappar bör webbappar omdirigera användaren till auktoriseringssidan och webb-API:er ska returnera en HTTP-statuskod och ett huvud som tyder på autentiseringsfelet (401 Obehörig och ett WWW-Authenticate-huvud).

Vanliga .NET undantag

Här är de vanligaste undantagen som kan uppstå och några möjliga åtgärder:

MsalUiRequiredException

En av de vanliga statuskoder som returneras från MSAL.NET när du anropar AcquireTokenSilent() är MsalError.InvalidGrantError. Den här statuskoden innebär att programmet ska anropa autentiseringsbiblioteket igen, men i interaktivt läge (AcquireTokenInteractive eller AcquireTokenByDeviceCodeFlow för offentliga klientprogram har det en utmaning i webbappar). Detta beror på att ytterligare användarinteraktion krävs innan autentiseringstoken kan utfärdas.

Oftast, när AcquireTokenSilent misslyckas, beror det på att tokencachen inte innehåller token som matchar din förfrågan. Åtkomsttoken upphör att gälla om 1 timme och AcquireTokenSilent försöker hämta en ny baserat på en uppdateringstoken (i OAuth2-termer är detta flödet "Uppdatera token"). Det här flödet kan också misslyckas av olika orsaker, till exempel om en klientorganisationsadministratör konfigurerar strängare inloggningsprinciper.

Interaktionen syftar till att låta användaren utföra en åtgärd. Vissa av dessa villkor är enkla för användare att lösa (till exempel acceptera användningsvillkor med ett enda klick), och vissa kan inte lösas med den aktuella konfigurationen (till exempel måste datorn i fråga ansluta till ett specifikt företagsnätverk). Vissa hjälper användaren att konfigurera multifaktorautentisering eller installera Microsoft Authenticator på sin enhet.

MsalUiRequiredException klassificeringsuppräkning

MSAL exponerar ett Classification fält som du kan läsa för att ge en bättre användarupplevelse. Till exempel för att tala om för användaren att lösenordet har upphört att gälla eller att de måste ge sitt medgivande till att använda vissa resurser. De värden som stöds är en del av UiRequiredExceptionClassification uppräkningen:

.NET kodexempel

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

Villkorsstyrd åtkomst och claims-utmaningar

När du hämtar token utan användarinteraktion kan din applikation få fel om ett API som du försöker komma åt kräver en anspråksutmaning för villkorlig åtkomst, till exempel en MFA-policy.

Mönstret för att hantera det här felet är att interaktivt hämta en token med hjälp av MSAL. Detta uppmanar användaren och ger dem möjlighet att uppfylla den nödvändiga principen för villkorsstyrd åtkomst.

I vissa fall, när du anropar ett API som kräver villkorsstyrd åtkomst, kan du få en anspråksutmaning i felmeddelandet från API:et. Om principen för villkorsstyrd åtkomst till exempel ska ha en hanterad enhet (Intune) blir felet ungefär som AADSTS53000: Enheten måste hanteras för att få åtkomst till den här resursen eller något liknande. I det här fallet kan du skicka med anspråken i anropet för att hämta en token så att användaren uppmanas att uppfylla kraven i rätt policy.

När du anropar ett API som kräver villkorlig åtkomst från MSAL.NET måste ditt program hantera undantag för anspråksutmaningar. Detta visar sig som en MsalServiceException och egenskapen Claims kommer inte att vara tom.

Om du vill hantera anspråksutmaningen använder du WithClaims(String).

Försök igen efter fel och undantag

Du förväntas implementera dina egna principer för återförsök när du anropar MSAL. MSAL gör HTTP-anrop till Microsoft Entra-tjänsten och ibland kan fel uppstå. Nätverket kan till exempel gå ner eller så är servern överbelastad.

HTTP 429

När servicetokenservern (STS) är överbelastad med för många begäranden returneras HTTP-fel 429 med en ledtråd om hur lång tid tills du kan försöka igen i svarsfältet Retry-After .

HTTP-felkoder 500-600

MSAL.NET implementerar en enkel mekanism för återförsök en gång för fel med HTTP-felkoderna 500-600.

MsalServiceException visas System.Net.Http.Headers.HttpResponseHeaders som en egenskap namedHeaders. Du kan använda ytterligare information från felkoden för att förbättra tillförlitligheten för dina program. I det fall som beskrivs kan du använda RetryAfter egenskapen (av typen RetryConditionHeaderValue) och beräkna när du ska försöka igen.

Här är ett exempel för ett daemonprogram som använder flödet för klientautentiseringsuppgifter. Du kan anpassa detta till någon av metoderna för att hämta en token.

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ästa steg

Överväg att aktivera loggning i MSAL.NET som hjälper dig att diagnostisera och felsöka problem.