Fouten en uitzonderingen verwerken in MSAL voor iOS/macOS

Dit artikel bevat een overzicht van de verschillende typen fouten en aanbevelingen voor het afhandelen van veelvoorkomende aanmeldingsfouten.

Basisprincipes van MSAL-foutafhandeling

Uitzonderingen in Microsoft Authentication Library (MSAL) zijn bedoeld voor app-ontwikkelaars om problemen op te lossen, niet voor weergave aan eindgebruikers. Uitzonderingsberichten worden niet gelokaliseerd.

Wanneer u uitzonderingen en fouten verwerkt, kunt u het uitzonderingstype zelf en de foutcode gebruiken om onderscheid te maken tussen uitzonderingen. Zie Microsoft Entra foutcodes voor verificatie en autorisatie voor een lijst met foutcodes.

Tijdens de aanmeldingservaring kunnen er fouten optreden over toestemmingen, voorwaardelijke toegang (MFA, Apparaatbeheer, beperkingen op basis van locatie), tokenuitgifte en inwisseling en gebruikerseigenschappen.

In de volgende sectie vindt u meer informatie over foutafhandeling voor uw app.

Foutafhandeling in MSAL voor iOS/macOS

De volledige lijst met MSAL voor iOS- en macOS-fouten wordt vermeld in MSALError enum.

Alle door MSAL gegenereerde fouten worden geretourneerd met het domein MSALErrorDomain.

Voor systeemfouten retourneert MSAL het origineel NSError van de systeem-API. Als het ophalen van tokens bijvoorbeeld mislukt vanwege een gebrek aan netwerkconnectiviteit, retourneert MSAL een fout met het domein en NSURLErrorDomain de NSURLErrorNotConnectedToInternet code.

U wordt aangeraden ten minste de volgende twee MSAL-fouten aan de clientzijde af te handelen:

• MSALErrorInteractionRequired: De gebruiker moet een interactieve aanvraag doen. Er zijn veel voorwaarden die kunnen leiden tot deze fout, zoals een verlopen verificatiesessie of de noodzaak van aanvullende verificatievereisten. Roep de INTERACTIEVE MSAL-tokenverwervings-API aan om te herstellen.

• MSALErrorServerDeclinedScopes: Sommige of alle scopes zijn afgewezen. Bepaal of u wilt doorgaan met alleen de verleende machtigingen, of het aanmeldingsproces wilt stoppen.

Dit betekent bijvoorbeeld MSALInternalErrorBrokerResponseNotReceived dat de gebruiker de verificatie niet heeft voltooid en handmatig naar de app is teruggestuurd. In dit geval moet uw app een algemeen foutbericht weergeven waarin wordt uitgelegd dat de verificatie niet is voltooid en wordt voorgesteld dat ze opnieuw proberen te verifiëren.

In de volgende Objective-C voorbeeldcode ziet u aanbevolen procedures voor het afhandelen van enkele veelvoorkomende foutvoorwaarden.

    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)

Problemen met voorwaardelijke toegang en claims

Wanneer tokens op de achtergrond worden opgehaald, kan uw toepassing fouten krijgen wanneer een claims-uitdaging voor voorwaardelijke toegang, zoals MFA-beleid, wordt vereist door een API waartoe u toegang probeert te krijgen.

Het patroon voor het afhandelen van deze fout is om interactief een token te verkrijgen met BEHULP van MSAL. Hiermee wordt de gebruiker gevraagd en krijgt deze de mogelijkheid om te voldoen aan het vereiste beleid voor voorwaardelijke toegang.

In bepaalde gevallen kunt u, wanneer u een API aanroept waarvoor voorwaardelijke toegang is vereist, een claims-uitdaging ontvangen in de foutmelding van de API. Als het beleid voor voorwaardelijke toegang bijvoorbeeld een beheerd apparaat (Intune) heeft, is de fout ongeveer AADSTS53000: uw apparaat moet worden beheerd om toegang te krijgen tot deze resource of iets dergelijks. In dit geval kunt u de claims doorgeven in de aanroep van het acquire-token, zodat de gebruiker wordt gevraagd om te voldoen aan het juiste beleid.

Met MSAL voor iOS en macOS kunt u specifieke claims aanvragen in zowel interactieve als stille tokenverwervingsscenario's.

Als u aangepaste claims wilt aanvragen, geeft u claimsRequest op in MSALSilentTokenParameters of MSALInteractiveTokenParameters.

Zie Aangepaste claims aanvragen met MSAL voor iOS en macOS voor meer informatie.

Opnieuw proberen na fouten en uitzonderingen

U wordt verwacht dat u uw eigen beleid voor opnieuw proberen implementeert bij het aanroepen van MSAL. MSAL maakt HTTP-aanroepen naar de Microsoft Entra-service en af en toe kunnen er fouten optreden. Het netwerk kan bijvoorbeeld uitvalt of de server overbelast is.

HTTP 429

Wanneer de Service Token Server (STS) overbelast is met te veel aanvragen, retourneert deze HTTP-fout 429 met een hint over hoe lang het duurt voordat u het opnieuw kunt proberen in het Retry-After antwoordveld.

Volgende stappen 

Overweeg logregistratie in MSAL voor iOS/macOS in te schakelen om u te helpen problemen te diagnosticeren en op te lossen.