iOS/macOS için MSAL.js’de 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 Kimlik Doğrulama Kitaplığı'ndaki (MSAL) özel durumlar, son kullanıcılara görüntülenmek için değil, uygulama geliştiricilerinin sorun gidermesine yöneliktir. Ö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 . Microsoft Entra kimlik doğrulaması ve yetkilendirme hata kodları.
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.
iOS/macOS için MSAL'de hata işleme
iOS ve macOS için MSAL hatalarının tam listesi MSALError sabit listesinde listelenir.
MSAL tarafından oluşturulan tüm hatalar etki alanıyla birlikte MSALErrorDomain döndürülür.
Sistem hataları için MSAL, sistem API'sinden özgün NSError değerini döndürür. Örneğin, belirteç alma işlemi ağ bağlantısı olmaması nedeniyle başarısız olursa, MSAL etki alanı ve NSURLErrorNotConnectedToInternet kodla NSURLErrorDomain ilgili bir hata döndürür.
İstemci tarafında en az aşağıdaki iki MSAL hatasını işlemenizi öneririz:
MSALErrorInteractionRequired: Kullanıcı etkileşimli bir istekte bulunmalıdır. Süresi dolan bir kimlik doğrulama oturumu veya ek kimlik doğrulaması gereksinimleri gereksinimi gibi bu hataya yol açabilecek birçok koşul vardır. Kurtarmak için MSAL etkileşimli belirteç alma API'sini çağırın.MSALErrorServerDeclinedScopes: Kapsamların bazıları veya tümü reddedildi. Yalnızca verilen kapsamlarla devam etmek mi yoksa oturum açma işlemini durdurmak mı istediğinize karar verin.
Not
Sabit MSALInternalError listesi yalnızca başvuru ve hata ayıklama için kullanılmalıdır. Bu hataları çalışma zamanında otomatik olarak işlemeye çalışmayın. Uygulamanız altında MSALInternalErrorbulunan hatalardan herhangi biri ile karşılaşırsa, ne olduğunu açıklayan genel bir kullanıcıya yönelik ileti göstermek isteyebilirsiniz.
Örneğin, MSALInternalErrorBrokerResponseNotReceived kullanıcının kimlik doğrulamasını tamamlamadığını ve uygulamaya el ile döndürüldüğünü gösterir. Bu durumda, uygulamanız kimlik doğrulamasının tamamlanmadığını açıklayan genel bir hata iletisi göstermeli ve yeniden kimlik doğrulaması yapmayı denemelerini önermelidir.
Aşağıdaki Objective-C örnek kodu, bazı yaygın hata koşullarını işlemeye yönelik en iyi yöntemleri gösterir.
MSALInteractiveTokenParameters *interactiveParameters = ...;
MSALSilentTokenParameters *silentParameters = ...;
MSALCompletionBlock completionBlock;
__block __weak MSALCompletionBlock weakCompletionBlock;
weakCompletionBlock = completionBlock = ^(MSALResult *result, NSError *error)
{
if (!error)
{
// Use result.accessToken
NSString *accessToken = result.accessToken;
return;
}
if ([error.domain isEqualToString:MSALErrorDomain])
{
switch (error.code)
{
case MSALErrorInteractionRequired:
{
// Interactive auth will be required
[application acquireTokenWithParameters:interactiveParameters
completionBlock:weakCompletionBlock];
break;
}
case MSALErrorServerDeclinedScopes:
{
// These are list of granted and declined scopes.
NSArray *grantedScopes = error.userInfo[MSALGrantedScopesKey];
NSArray *declinedScopes = error.userInfo[MSALDeclinedScopesKey];
// To continue acquiring token for granted scopes only, do the following
silentParameters.scopes = grantedScopes;
[application acquireTokenSilentWithParameters:silentParameters
completionBlock:weakCompletionBlock];
// Otherwise, instead, handle error fittingly to the application context
break;
}
case MSALErrorServerProtectionPoliciesRequired:
{
// Integrate the Intune SDK and call the
// remediateComplianceForIdentity:silent: API.
// Handle this error only if you integrated Intune SDK.
// See more info here: https://aka.ms/intuneMAMSDK
break;
}
case MSALErrorUserCanceled:
{
// The user cancelled the web auth session.
// You may want to ask the user to try again.
// Handling of this error is optional.
break;
}
case MSALErrorInternal:
{
// Log the error, then inspect the MSALInternalErrorCodeKey
// in the userInfo dictionary.
// Display generic error message to the end user
// More detailed information about the specific error
// under MSALInternalErrorCodeKey can be found in MSALInternalError enum.
NSLog(@"Failed with error %@", error);
break;
}
default:
NSLog(@"Failed with unknown MSAL error %@", error);
break;
}
return;
}
// Handle no internet connection.
if ([error.domain isEqualToString:NSURLErrorDomain] && error.code == NSURLErrorNotConnectedToInternet)
{
NSLog(@"No internet connection.");
return;
}
// Other errors may require trying again later,
// or reporting authentication problems to the user.
NSLog(@"Failed with error %@", error);
};
// Acquire token silently
[application acquireTokenSilentWithParameters:silentParameters
completionBlock:completionBlock];
// or acquire it interactively.
[application acquireTokenWithParameters:interactiveParameters
completionBlock:completionBlock];
let interactiveParameters: MSALInteractiveTokenParameters = ...
let silentParameters: MSALSilentTokenParameters = ...
var completionBlock: MSALCompletionBlock!
completionBlock = { (result: MSALResult?, error: Error?) in
if let result = result
{
// Use result.accessToken
let accessToken = result.accessToken
return
}
guard let error = error as NSError? else { return }
if error.domain == MSALErrorDomain, let errorCode = MSALError(rawValue: error.code)
{
switch errorCode
{
case .interactionRequired:
// Interactive auth will be required
application.acquireToken(with: interactiveParameters, completionBlock: completionBlock)
case .serverDeclinedScopes:
let grantedScopes = error.userInfo[MSALGrantedScopesKey]
let declinedScopes = error.userInfo[MSALDeclinedScopesKey]
if let scopes = grantedScopes as? [String] {
silentParameters.scopes = scopes
application.acquireTokenSilent(with: silentParameters, completionBlock: completionBlock)
}
case .serverProtectionPoliciesRequired:
// Integrate the Intune SDK and call the
// remediateComplianceForIdentity:silent: API.
// Handle this error only if you integrated Intune SDK.
// See more info here: https://aka.ms/intuneMAMSDK
break
case .userCanceled:
// The user cancelled the web auth session.
// You may want to ask the user to try again.
// Handling of this error is optional.
break
case .internal:
// Log the error, then inspect the MSALInternalErrorCodeKey
// in the userInfo dictionary.
// Display generic error message to the end user
// More detailed information about the specific error
// under MSALInternalErrorCodeKey can be found in MSALInternalError enum.
print("Failed with error \(error)");
default:
print("Failed with unknown MSAL error \(error)")
}
}
// Handle no internet connection.
if error.domain == NSURLErrorDomain && error.code == NSURLErrorNotConnectedToInternet
{
print("No internet connection.")
return
}
// Other errors may require trying again later,
// or reporting authentication problems to the user.
print("Failed with error \(error)");
}
// Acquire token silently
application.acquireToken(with: interactiveParameters, completionBlock: completionBlock)
// or acquire it interactively.
application.acquireTokenSilent(with: silentParameters, completionBlock: completionBlock)
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ı işlemeye yönelik desen, MSAL kullanarak etkileşimli bir belirteç almaktır. Bu, kullanıcıya sorar ve gerekli Koşullu Erişim ilkesini karşılama fırsatı verir.
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 ilkesinin yönetilen bir cihaza (Intune) sahip olması durumunda hata AADSTS53000: Cihazınızın bu kaynağa erişmek için yönetilmesi veya benzer bir şey olması gerekir. Bu durumda, kullanıcıdan uygun ilkeyi karşılaması istenmesi için alma belirteci çağrısında talepleri geçirebilirsiniz.
iOS ve macOS için MSAL, hem etkileşimli hem de sessiz belirteç alma senaryolarında belirli talepler istemenizi sağlar.
Özel talepler istemek için veya MSALInteractiveTokenParametersiçinde MSALSilentTokenParameters belirtinclaimsRequest.
Daha fazla bilgi için bkz . iOS ve macOS için MSAL kullanarak özel talepler isteme.
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 istekle aşırı yüklendiğinde, yanıt alanında yeniden Retry-After deneyebileceğiniz süreyle ilgili bir ipucuyla HTTP hatası 429 döndürür.
Sonraki adımlar
Sorunları tanılamanıza ve hatalarını ayıklamanıza yardımcı olması için iOS/macOS için MSAL'de Günlüğe Kaydetme'yi etkinleştirmeyi göz önünde bulundurun.