Zpracování chyb a výjimek v MSAL.NET

Tento článek obsahuje přehled různých typů chyb a doporučení pro zpracování běžných chyb přihlašování.

Základy zpracování chyb MSAL

Výjimky v Identity a ověřování Microsoftu (MSAL) jsou určené pro vývojáře aplikací k řešení potíží, nikoli k zobrazení koncovým uživatelům. Zprávy o výjimce nejsou lokalizované.

Při zpracování výjimek a chyb můžete k rozlišení mezi výjimkami použít samotný typ výjimky a kód chyby. Seznam kódů chyb najdete v tématu Kódy chyb ověřování a autorizace v Microsoft Entra.

Během přihlašování můžete narazit na chyby týkající se souhlasů, podmíněného přístupu (MFA, Správa zařízení, omezení založených na poloze), vystavování a uplatnění tokenů a vlastností uživatele.

Následující část obsahuje další podrobnosti o zpracování chyb pro vaši aplikaci.

Zpracování chyb v MSAL.NET

Typy výjimek

MsalClientException je vyvolána, když samotná knihovna zjistí chybový stav, například chybná konfigurace.

MsalServiceException je vyvolána, když zprostředkovatel identity (Microsoft Entra ID) vrátí chybu. Jedná se o překlad chyby serveru.

MsalUIRequiredException je typ MsalServiceException a označuje, že je vyžadována interakce uživatele. Pokud je například vyžadováno vícefaktorové ověřování (MFA) nebo když uživatel změní heslo a token se nedá získat bezobslužně.

Zpracování výjimek

Při zpracování .NET výjimek můžete k rozlišení mezi výjimkami použít samotný typ výjimky a ErrorCode člen. ErrorCode hodnoty jsou konstanty typu MsalError.

Můžete se také podívat na pole MsalClientException, MsalServiceException a MsalUIRequiredException.

Pokud je vyvolána výjimka MsalServiceException , zkuste kódy chyb ověřování a autorizace , abyste zjistili, jestli je tam uvedený kód.

Pokud je vyvolána výjimka MsalUIRequiredException, znamená to, že aby uživatel mohl problém vyřešit, je nutné provést interaktivní tok. Ve veřejných klientských aplikacích, jako je desktopová a mobilní aplikace, se to vyřeší voláním AcquireTokenInteractive, který zobrazí prohlížeč. U důvěrných klientských aplikací by webové aplikace měly uživatele přesměrovat na autorizační stránku a webová rozhraní API by měla vrátit stavový kód HTTP a hlavičku označující selhání ověřování (401 Unauthorized a hlavičku WWW-Authenticate).

Běžné výjimky .NET

Zde jsou běžné výjimky, které mohou nastat, a některá možná opatření k jejich zmírnění:

Exception	Kód chyby	Mitigation
MsalUiRequiredException	AADSTS65001: Uživatel nebo správce neschválili souhlas s použitím aplikace s ID {appId} s názvem {appName}. Odešlete interaktivní žádost o autorizaci pro tohoto uživatele a prostředek.	Nejdřív získejte souhlas uživatele. Pokud nepoužíváte .NET Core (které nemá žádné webové uživatelské rozhraní), zavolejte (jenom jednou). AcquireTokenInteractive Pokud používáte .NET jádro nebo nechcete provádět nějaké akceAcquireTokenInteractive, uživatel může přejít na adresu URL a udělit souhlas: https://login.microsoftonline.com/common/oauth2/v2.0/authorize?client_id={clientId}&response_type=code&scope=user.read. zavolat AcquireTokenInteractive: app.AcquireTokenInteractive(scopes).WithAccount(account).WithClaims(ex.Claims).ExecuteAsync();
MsalUiRequiredException	AADSTS50079: Uživatel musí používat vícefaktorové ověřování (MFA).	Neexistuje žádné zmírnění rizik. Pokud je pro vašeho tenanta nakonfigurované vícefaktorové ověřování a Microsoft Entra ID rozhodne o jeho vynucení, přejděte na interaktivní tok, například AcquireTokenInteractive.
MsalServiceException	AADSTS90010: Typ grantu není podporován pro koncové body /common nebo /consumers. Použijte koncový bod /organizations nebo koncový bod specifický pro daného tenanta. Použili jste /common.	Jak je vysvětleno ve zprávě z Microsoft Entra ID, autorita musí mít tenanta nebo jinak /organizace.
MsalServiceException	AADSTS70002: Text požadavku musí obsahovat následující parametr: client_secret or client_assertion.	Tuto výjimku můžete vyvolat, pokud vaše aplikace nebyla v Microsoft Entra ID zaregistrovaná jako veřejná klientská aplikace. V Centrum pro správu Microsoft Entra upravte manifest aplikace a nastavte allowPublicClient na true.
MsalClientException	unknown_user Message: Nepodařilo se identifikovat přihlášeného uživatele.	Knihovna nemohla zjistit aktuálně přihlášeného uživatele systému Windows nebo tento uživatel není připojený k služba Active Directory ani k Microsoft Entra (uživatelé připojení k pracovišti nejsou podporováni). Zmírnění: Implementujte vlastní logiku pro načtení uživatelského jména (například john@contoso.com) a použijte AcquireTokenByIntegratedWindowsAuth formulář, který přebírá uživatelské jméno.
MsalClientException	Integrované ověřování systému Windows není pro spravovaného uživatele podporováno.	Tato metoda spoléhá na protokol vystavený službou služba Active Directory (AD). Pokud byl uživatel vytvořen v Microsoft Entra ID bez zálohování AD (spravovaného uživatele), tato metoda selže. Uživatelé vytvořená v AD a podporovaní Microsoft Entra ID (federovaní uživatelé) můžou těžit z této neinteraktivní metody ověřování. Omezení rizik: Používejte interaktivní ověřování.

MsalUiRequiredException

Jeden z běžných stavových kódů vrácených z MSAL.NET při volání AcquireTokenSilent() je MsalError.InvalidGrantError. Tento stavový kód znamená, že aplikace by měla znovu volat knihovnu ověřování, ale v interaktivním režimu (AcquireTokenInteractive nebo AcquireTokenByDeviceCodeFlow pro veřejné klientské aplikace mají výzvu ve webových aplikacích). Důvodem je to, že před vydáním ověřovacího tokenu je vyžadována další interakce uživatele.

Většina případů, kdy AcquireTokenSilent dojde k selhání, je to proto, že mezipaměť tokenů nemá tokeny odpovídající vašemu požadavku. Platnost přístupových tokenů vyprší za 1 hodinu a AcquireTokenSilent pokusí se načíst nový token na základě obnovovacího tokenu (v OAuth2 se jedná o tok obnovovacího tokenu). Tento tok může také selhat z různých důvodů, například pokud správce tenanta konfiguruje přísnější zásady přihlašování.

Cílem interakce je, aby uživatel udělal nějakou akci. Některé z těchto podmínek se dají snadno vyřešit (například přijmout podmínky použití jediným kliknutím) a některé se nedají vyřešit s aktuální konfigurací (například počítač se musí připojit ke konkrétní podnikové síti). Některé pomáhají uživateli nastavit vícefaktorové ověřování nebo nainstalovat Microsoft Authenticator na zařízení.

MsalUiRequiredException klasifikace – výčet

Knihovna MSAL zpřístupňuje pole Classification, jehož hodnotu můžete číst, abyste zajistili lepší uživatelské prostředí. Pokud například chcete uživateli sdělit, že platnost hesla vypršela nebo že musí poskytnout souhlas s používáním některých prostředků. Podporované hodnoty jsou součástí výčtu UiRequiredExceptionClassification :

Classification	Meaning	Doporučené zpracování
BasicAction	Podmínku je možné vyřešit interakcí uživatele během interaktivního ověřovacího toku.	Zavolejte AcquireTokenInteractively().
AdditionalAction	Podmínku lze vyřešit další nápravnou interakcí se systémem mimo interaktivní tok ověřování.	Zavoláním metody AcquireTokenInteractively() zobrazíte zprávu s vysvětlením nápravné akce. Volající aplikace se může rozhodnout skrýt toky, které vyžadují additional_action, pokud je nepravděpodobné, že uživatel dokončí nápravnou akci.
Pouze zpráva	Podmínku nelze v tuto chvíli vyřešit. Spuštění interaktivního toku ověřování zobrazí zprávu s vysvětlením podmínky.	Zavoláním metody AcquireTokenInteractively() zobrazíte zprávu s vysvětlením podmínky. AcquireTokenInteractively() vrátí chybu UserCanceled po přečtení zprávy a zavře okno. Volající aplikace se může rozhodnout skrýt toky, jejichž výsledkem je message_only, pokud je nepravděpodobné, že zpráva uživateli přinese užitek.
Vyžaduje se souhlas	Chybí souhlas uživatele nebo byl odvolán.	Zavolejte AcquireTokenInteractively(), aby uživatel udělil souhlas.
Platnost uživatelského hesla vypršela	Platnost hesla uživatele vypršela.	Zavolejte AcquireTokenInteractively(), aby uživatel mohl resetovat heslo.
PromptNeverFailed	Interaktivní ověřování bylo vyvoláno s parametrem prompt=never, což přinutilo MSAL spoléhat se na soubory cookie prohlížeče a nezobrazovat prohlížeč. Došlo k chybě.	Volání AcquireTokenInteractively() bez prompt.none
AcquireTokenSilentFailed	Sada MSAL SDK nemá dostatek informací k načtení tokenu z mezipaměti. Důvodem může být to, že v mezipaměti nejsou žádné tokeny nebo nebyl nalezen účet. Chybová zpráva obsahuje další podrobnosti.	Zavolejte AcquireTokenInteractively().
None	Nejsou k dispozici žádné další podrobnosti. Podmínku může vyřešit interakce uživatele během interaktivního ověřovacího toku.	Zavolejte AcquireTokenInteractively().

příklad kódu .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;
 }
}

Podmíněný přístup a problémy s claimy

Při tichém získávání tokenů může ve vaší aplikaci docházet k chybám, pokud rozhraní API, ke kterému se pokoušíte získat přístup, vyžaduje výzvu deklarací podmíněného přístupu, například kvůli zásadám MFA.

Vzor pro zpracování této chyby spočívá v interaktivním získání tokenu pomocí knihovny MSAL. Tím uživatele vyzvete a získáte mu možnost splnit požadované zásady podmíněného přístupu.

V některých případech můžete při volání rozhraní API, které vyžaduje podmíněný přístup, obdržet v chybové odpovědi z rozhraní API výzvu deklarací. Pokud například zásada podmíněného přístupu vyžaduje spravované zařízení (Intune), chybová zpráva bude vypadat přibližně takto: AADSTS53000: Aby bylo možné získat přístup k tomuto prostředku, musí být vaše zařízení spravované nebo podobně. V takovém případě můžete ve volání pro získání tokenu předat claims, aby byl uživatel vyzván ke splnění příslušných zásad.

Při volání rozhraní API, které vyžaduje podmíněný přístup, pomocí MSAL.NET musí vaše aplikace zpracovávat výjimky typu claim challenge. Projeví se jako výjimka MsalServiceException, přičemž vlastnost Claims nebude prázdná.

Ke zpracování výzvy deklarace identity použijte WithClaims(String).

Opakování po chybách a výjimkách

Očekává se, že při volání knihovny MSAL implementujete vlastní zásady opakování pokusů. MsAL provádí volání HTTP do služby Microsoft Entra a občas může dojít k selháním. Například síť může jít dolů nebo je server přetížen.

HTTP 429

Pokud je server tokenů služby (STS) přetížen příliš mnoha požadavky, vrátí chybu HTTP 429 s nápovědou o tom, jak dlouho, než to můžete zkusit znovu v Retry-After poli odpovědi.

Kódy chyb HTTP 500-600

MSAL.NET implementuje jednoduchý mechanismus opakování jednou pro chyby s kódy chyb HTTP 500-600.

MsalServiceException zpřístupňuje System.Net.Http.Headers.HttpResponseHeaders jako vlastnost namedHeaders. Ke zlepšení spolehlivosti aplikací můžete použít další informace z kódu chyby. V případě popsaném můžete použít RetryAfter vlastnost (typu RetryConditionHeaderValue) a vypočítat, kdy to zkusíte znovu.

Tady je příklad aplikace démona, která používá tok přihlašovacích údajů klienta. Můžete ho přizpůsobit libovolné z metod pro získání tokenu.

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

Další kroky

Zvažte povolení protokolování v MSAL.NET, abyste mohli diagnostikovat a ladit problémy.