MSAL.NET hataları ve özel durumları işleme

Bu makalede, farklı hata türlerine genel bir bakış ve yaygın oturum açma hatalarını işlemeye yönelik öneriler verilmektedir.

MSAL hata işleme temelleri

Microsoft Authentication Library (MSAL) özel durumları, son kullanıcılara gösterilmek için değil, uygulama geliştiricilerinin sorun giderme amacıyla kullanması için tasarlanmıştır. Özel durum iletileri yerelleştirilmemiş.

Özel durumları ve hataları işlerken, özel durumlar arasında ayrım yapmak için özel durum türünün kendisini ve hata kodunu kullanabilirsiniz. Hata kodlarının listesi için bkz. kimlik doğrulaması ve yetkilendirme hata kodları Microsoft Entra.

Oturum açma deneyimi sırasında onaylar, Koşullu Erişim (MFA, Cihaz Yönetimi, Konum tabanlı kısıtlamalar), belirteç verme ve kullanım ve kullanıcı özellikleriyle ilgili hatalarla karşılaşabilirsiniz.

Aşağıdaki bölümde, uygulamanız için hata işleme hakkında daha fazla ayrıntı sağlanır.

MSAL.NET'de hata işleme

Özel durum türleri

MsalClientException, kitaplığın kendisi örneğin hatalı bir yapılandırma gibi bir hata durumu algıladığında fırlatılır.

Kimlik Sağlayıcısı (Microsoft Entra ID) bir hata döndürdüğünde MsalServiceException oluşturulur. Sunucu hatasının çevirisi.

MsalUIRequiredException, MsalServiceException türüdür ve kullanıcı etkileşiminin gerekli olduğunu gösterir. Örneğin, çok faktörlü kimlik doğrulaması (MFA) gerektiğinde veya kullanıcı parolasını değiştirdiğinde ve bir belirteç sessizce alınamazsa.

Özel durumları işleme

.NET özel durumları işlerken, özel durumlar arasında ayrım yapmak için özel durum türünün kendisini ve üyeyi ErrorCode kullanabilirsiniz. ErrorCode değerler MsalError türünde sabitlerdir.

MsalClientException, MsalServiceException ve MsalUIRequiredException alanlarına da göz atabilirsiniz.

MsalServiceException oluşturulursa, kodun orada listelenip listelenmediğini görmek için Kimlik doğrulama ve yetkilendirme hata kodlarını deneyin.

MsalUIRequiredException oluşturulursa, kullanıcının sorunu çözmesi için etkileşimli bir akışın gerçekleşmesi gerektiğinin göstergesidir. Masaüstü ve mobil uygulama gibi genel istemci uygulamalarında bu, bir tarayıcı görüntüleyen çağrısıyla AcquireTokenInteractiveçözülür. Gizli istemci uygulamalarında, web uygulamaları kullanıcıyı yetkilendirme sayfasına yönlendirmelidir ve web API'leri kimlik doğrulama hatasını belirten bir HTTP durum kodu ve üst bilgi (401 Yetkisiz ve WWW-Authenticate üst bilgisi) döndürmelidir.

Yaygın .NET özel durumları

Oluşturulabilecek yaygın özel durumlar ve bazı olası risk azaltmaları şunlardır:

Exception	Hata kodu	Mitigation
MsalUiRequiredException	AADSTS65001: Kullanıcı veya yönetici '{appId}' kimliği '{appName}' olan uygulamayı kullanmayı onaylamadı. Bu kullanıcı ve kaynak için etkileşimli yetkilendirme isteği gönderin.	Önce kullanıcı onayı alın. .NET Core kullanmıyorsanız (Web kullanıcı arabirimi olmayan), AcquireTokenInteractive çağrısını yalnızca bir kez yapın. .NET Core kullanıyorsanız veya bir AcquireTokenInteractive yapmak istemiyorsanız, kullanıcı onay vermek için şu URL’yi ziyaret edebilir: https://login.microsoftonline.com/common/oauth2/v2.0/authorize?client_id={clientId}&response_type=code&scope=user.read. AcquireTokenInteractive çağırmak için: app.AcquireTokenInteractive(scopes).WithAccount(account).WithClaims(ex.Claims).ExecuteAsync();
MsalUiRequiredException	AADSTS50079: Kullanıcının çok faktörlü kimlik doğrulaması (MFA) kullanması gerekir.	Hafifletme yok. MFA kiracınız için yapılandırılmışsa ve Microsoft Entra ID bunu zorunlu kılmaya karar verirse, AcquireTokenInteractivegibi etkileşimli bir akışa geri dönün.
MsalServiceException	AADSTS90010: İzin türü, /common veya /consumers uç noktalarında desteklenmez. /organizations veya kiracıya özgü uç noktayı kullanın. /common kullandınız.	Microsoft Entra ID iletisinde açıklandığı gibi, yetkilinin bir kiracısı veya başka bir şekilde /organizations olması gerekir.
MsalServiceException	AADSTS70002: İstek gövdesi şu parametreyi içermelidir: client_secret or client_assertion.	Uygulamanız Microsoft Entra ID'de genel istemci uygulaması olarak kaydedilmediyse bu özel durum oluşabilir. Microsoft Entra yönetim merkezinde, uygulamanızın bildirim dosyasını düzenleyin ve allowPublicClient değerini true olarak ayarlayın.
MsalClientException	unknown_user Message: Oturum açmış kullanıcı belirlenemedi	Kitaplık, Windows’ta oturum açmış geçerli kullanıcıyı sorgulayamadı veya bu kullanıcı Active Directory’ye ya da Microsoft Entra’ya bağlı değil (yalnızca iş yerine katılmış kullanıcılar desteklenmez). Risk azaltma: Kullanıcı adını almak için kendi mantığınızı uygulayın (örneğin, john@contoso.com) ve kullanıcı adını alan AcquireTokenByIntegratedWindowsAuth formunu kullanın.
MsalClientException	Yönetilen kullanıcı için Tümleşik Windows kimlik doğrulaması desteklenmiyor.	Bu yöntem, Active Directory (AD) tarafından kullanıma sunulan bir protokole dayanır. Bir kullanıcı Microsoft Entra ID ad desteği olmadan oluşturulduysa ("yönetilen" kullanıcı), bu yöntem başarısız olur. AD'de oluşturulan ve Microsoft Entra ID ("federasyon" kullanıcıları) tarafından yedeklenen kullanıcılar bu etkileşimli olmayan kimlik doğrulama yönteminden yararlanabilir. Azaltma: Etkileşimli kimlik doğrulaması kullanın.

MsalUiRequiredException

AcquireTokenSilent() çağrılırken MSAL.NET tarafından döndürülen yaygın durum kodlarından biri MsalError.InvalidGrantError'dir. Bu durum kodu, uygulamanın kimlik doğrulama kitaplığını yeniden çağırması gerektiği anlamına gelir, ancak etkileşimli modda (genel istemci uygulamaları için AcquireTokenInteractive veya AcquireTokenByDeviceCodeFlow, Web uygulamalarında bir zorluk vardır). Bunun nedeni, kimlik doğrulama belirtecinin verilebilmesi için ek kullanıcı etkileşimi gerekmesidir.

Çoğu zaman başarısız olduğunda AcquireTokenSilent , bunun nedeni belirteç önbelleğinin isteğinizle eşleşen belirteçlere sahip olmamasıdır. Erişim belirteçlerinin süresi 1 saat içinde dolacak ve AcquireTokenSilent yenileme belirtecini temel alan yeni bir belirteç getirmeye çalışır (OAuth2 terimlerinde, bu "Yenileme Belirteci" akışıdır). Bu akış, kiracı yöneticisinin daha sıkı oturum açma ilkeleri yapılandırması gibi çeşitli nedenlerle de başarısız olabilir.

Etkileşim, kullanıcının bir eylem gerçekleştirmesini hedefler. Bu koşulların bazıları kullanıcıların kolayca çözümleyebilmesini sağlar (örneğin, tek tıklamayla Kullanım Koşulları'nı kabul edin) ve bazıları geçerli yapılandırmayla çözümlenemez (örneğin, söz konusu makinenin belirli bir şirket ağına bağlanması gerekir). Bazıları kullanıcının çok faktörlü kimlik doğrulamasını ayarlamasına veya Microsoft Authenticator cihazına yüklemesine yardımcı olur.

MsalUiRequiredException sınıflandırma listelemesi

MSAL, daha iyi bir kullanıcı deneyimi sağlamak için okuyabileceğiniz bir Classification alanı kullanıma sunar. Örneğin, kullanıcıya parolasının süresinin dolduğunu veya bazı kaynakları kullanmak için onay vermesi gerektiğini söylemek için. Desteklenen değerler, UiRequiredExceptionClassification enum'un bir parçasıdır:

Classification	Meaning	Önerilen işleme
BasicAction	Koşul, etkileşimli kimlik doğrulama akışı sırasında kullanıcı etkileşimi tarafından çözülebilir.	AcquireTokenInteractively() öğesini çağır.
Ek Eylem	Koşul, etkileşimli kimlik doğrulama akışının dışında sistemle ek düzeltme etkileşimiyle çözülebilir.	Düzeltici eylemi açıklayan bir ileti göstermek için AcquireTokenInteractively() öğesini çağırın. Çağıran uygulama, kullanıcının düzeltici işlemi tamamlama olasılığı düşükse additional_action gerektiren akışları gizlemeyi seçebilir.
MessageOnly	Koşul şu anda çözümlenemiyor. Etkileşimli kimlik doğrulama akışının başlatılması koşulu açıklayan bir ileti gösterir.	Koşulu açıklayan bir ileti göstermek için AcquireTokenInteractively() öğesini çağırın. AcquireTokenInteractively() kullanıcı iletiyi okuyup pencereyi kapattıktan sonra UserCanceled hatası döndürür. Çağıran uygulama, kullanıcının mesajdan fayda görmesinin olası olmadığı durumlarda, message_only ile sonuçlanan akışları gizlemeyi seçebilir.
Onay gerekli	Kullanıcı onayı eksik veya iptal edilmiş.	Kullanıcının onay vermesi için AcquireTokenInteractively() öğesini çağır.
Kullanıcı parolasının süresi doldu	Kullanıcının parolasının süresi doldu.	Kullanıcının parolasını sıfırlayabilmesi için AcquireTokenInteractively() öğesini çağır.
PromptNeverFailed	Etkileşimli Kimlik Doğrulaması prompt=never parametresiyle çağrıldı ve MSAL tarayıcı tanımlama bilgilerine güvenmeye ve tarayıcıyı görüntülememeye zorlandı. Bu başarısız oldu.	Prompt.None olmadan AcquireTokenInteractively() çağrısı yapın
AcquireTokenSilentFailed	MSAL SDK'sı önbellekten belirteç getirmek için yeterli bilgiye sahip değildir. Bunun nedeni önbellekte belirteç olmaması veya bir hesabın bulunmamış olması olabilir. Hata iletisinde daha fazla ayrıntı var.	AcquireTokenInteractively() öğesini çağır.
Hiçbiri	Başka ayrıntı sağlanmadı. Koşul, etkileşimli kimlik doğrulama akışı sırasında kullanıcı etkileşimi tarafından çözülebilir.	AcquireTokenInteractively() öğesini çağır.

.NET kod örneği

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

Koşullu Erişim ve talep sınamaları

Belirteçleri sessizce alırken, erişmeye çalıştığınız bir API için MFA ilkesi gibi bir Koşullu Erişim talep sınaması gerektiğinde uygulamanız hata alabilir.

Bu hatayı ele almak için kullanılan yöntem, MSAL kullanarak etkileşimli olarak bir belirteç edinmektir. Bu, kullanıcıdan gerekli Koşullu Erişim ilkesini karşılamasını ister ve bunu yapmasına olanak tanır.

Koşullu Erişim gerektiren bir API'yi çağırırken bazı durumlarda, API'den hatada bir talep sınaması alabilirsiniz. Örneğin, Koşullu Erişim ilkesi yönetilen bir cihaz (Intune) gerektiriyorsa hata AADSTS53000: Bu kaynağa erişmek için cihazınızın yönetiliyor olması gerekir veya benzeri bir şey olacaktır. Bu durumda, kullanıcının uygun ilkenin gereksinimlerini karşılaması istensin diye, claim bilgilerini belirteç alma çağrısında iletebilirsiniz.

MSAL.NET Koşullu Erişim gerektiren bir API'yi çağırırken uygulamanızın talep sınaması özel durumlarını işlemesi gerekir. Bu, MsalServiceException olarak görünür; burada Claims özelliği boş değildir.

Talep sınamasını işlemek için kullanın WithClaims(String).

Hatalar ve özel durumlardan sonra yeniden deneme

MSAL'yi çağırırken kendi yeniden deneme ilkelerinizi uygulamanız beklenir. MSAL, Microsoft Entra hizmetine HTTP çağrıları yapar ve bazen hatalar oluşabilir. Örneğin ağ kapanabilir veya sunucu aşırı yüklenmiş olabilir.

HTTP 429

Hizmet Belirteci Sunucusu (STS), çok fazla istek nedeniyle aşırı yüklendiğinde, Retry-After yanıt alanında ne kadar süre sonra yeniden deneyebileceğinize ilişkin bir ipucuyla birlikte HTTP 429 hatasını döndürür.

HTTP hata kodları 500-600

MSAL.NET, 500-600 HTTP hata kodlarıyla ilgili hatalar için basit bir yeniden deneme mekanizması uygular.

MsalServiceException özelliği System.Net.Http.Headers.HttpResponseHeadersolarak ortaya çıkarnamedHeaders. Uygulamalarınızın güvenilirliğini artırmak için hata kodundaki ek bilgileri kullanabilirsiniz. Açıklanan durumda, RetryConditionHeaderValue türündeki RetryAfter özelliğini kullanabilir ve yeniden ne zaman deneneceğini hesaplayabilirsiniz.

aşağıda, istemci kimlik bilgileri akışını kullanan bir daemon uygulaması örneği verilmiştir. Bunu belirteç alma yöntemlerinden herhangi birine uyarlayabilirsiniz.

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

Sonraki Adımlar

Sorunları tanılamanıza ve hatalarını ayıklamanıza yardımcı olması için MSAL.NET oturum açmayı etkinleştirmeyi göz önünde bulundurun.