Gérer les erreurs et les exceptions dans MSAL pour iOS/macOS

Cet article fournit une vue d’ensemble des différents types d’erreurs et de recommandations pour la gestion des erreurs de connexion courantes.

Concepts de base de la gestion des erreurs MSAL

Les exceptions dans Microsoft Authentication Library (MSAL) sont destinées aux développeurs d’applications pour résoudre les problèmes, et non pour l’affichage aux utilisateurs finaux. Les messages d’exception ne sont pas localisés.

Lors du traitement des exceptions et des erreurs, vous pouvez utiliser le type d’exception lui-même et le code d’erreur pour distinguer les exceptions. Pour obtenir la liste des codes d’erreur, consultez Microsoft Entra codes d’erreur d’authentification et d’autorisation.

Pendant l’expérience de connexion, vous pouvez rencontrer des erreurs concernant les consentements, l’accès conditionnel (MFA, Gestion des appareils, restrictions basées sur l’emplacement), l’émission et l’échange de jetons et les propriétés utilisateur.

La section suivante fournit plus d’informations sur la gestion des erreurs pour votre application.

Gestion des erreurs dans MSAL pour iOS/macOS

La liste complète des erreurs MSAL pour iOS et macOS est répertoriée dans l’énumération MSALError.

Toutes les erreurs générées par MSAL sont renvoyées avec le domaine MSALErrorDomain.

Pour les erreurs système, MSAL retourne le NSError d’origine renvoyé par l’API système. Par exemple, si l’acquisition de jetons échoue en raison d’un manque de connectivité réseau, MSAL renvoie une erreur avec le domaine NSURLErrorDomain et le code NSURLErrorNotConnectedToInternet.

Nous vous recommandons de gérer au moins les deux erreurs MSAL suivantes côté client :

• MSALErrorInteractionRequired: l’utilisateur doit effectuer une demande interactive. De nombreuses conditions peuvent entraîner cette erreur, comme une session d’authentification expirée ou la nécessité d’exigences d’authentification supplémentaires. Appelez l’API d’acquisition de jetons interactive MSAL pour récupérer.

• MSALErrorServerDeclinedScopes : toutes les étendues ou certaines d’entre elles ont été refusées. Déterminez s’il faut continuer uniquement avec les étendues accordées ou arrêter le processus de connexion.

Par exemple, MSALInternalErrorBrokerResponseNotReceived cela signifie que l’utilisateur n’a pas terminé l’authentification et retourné manuellement à l’application. Dans ce cas, votre application doit afficher un message d’erreur générique expliquant que l’authentification n’a pas été terminée et suggère qu’elle tente de s’authentifier à nouveau.

L’exemple de code Objective-C suivant illustre les meilleures pratiques pour gérer certaines conditions d’erreur courantes.

    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)

Défis liés à l’accès conditionnel et aux revendications

Lorsque vous obtenez des jetons en mode silencieux, votre application peut recevoir des erreurs lorsqu’une demande de revendications d’accès conditionnel , telle que la stratégie MFA, est requise par une API que vous essayez d’accéder.

Le modèle de gestion de cette erreur consiste à acquérir de manière interactive un jeton à l’aide de MSAL. Cela invite l’utilisateur et lui donne la possibilité de se conformer à la stratégie d’accès conditionnel requise.

Dans certains cas, lors de l’appel d’une API nécessitant l’accès conditionnel, vous pouvez recevoir une demande de revendications dans le message d’erreur renvoyé par l’API. Par exemple, si la stratégie d’accès conditionnel doit avoir un appareil managé (Intune) l’erreur sera quelque chose comme AADSTS53000 : votre appareil doit être géré pour accéder à cette ressource ou quelque chose de similaire. Dans ce cas, vous pouvez transmettre la revendication dans l’appel d’acquisition du jeton, afin que l’utilisateur soit invité à satisfaire à la stratégie appropriée.

MSAL pour iOS et macOS vous permet de demander des revendications spécifiques dans des scénarios d’acquisition de jetons interactifs et silencieux.

Pour demander des revendications personnalisées, spécifiez claimsRequest dans MSALSilentTokenParameters ou MSALInteractiveTokenParameters.

Pour plus d’informations, consultez Demander des revendications personnalisées à l’aide de MSAL pour iOS et macOS .

Nouvelle tentative après des erreurs et des exceptions

Vous êtes censé implémenter vos propres stratégies de nouvelle tentative lors de l’appel de MSAL. MSAL effectue des appels HTTP au service Microsoft Entra, et parfois des échecs peuvent se produire. Par exemple, le réseau peut descendre ou le serveur est surchargé.

HTTP 429

Lorsque le serveur de jetons de service (STS) est surchargé avec trop de requêtes, il retourne l’erreur HTTP 429 avec un indicateur sur la durée jusqu’à ce que vous puissiez réessayer dans le Retry-After champ de réponse.

Étapes suivantes

Pensez à activer la journalisation dans MSAL pour iOS/macOS afin de vous aider à diagnostiquer et à déboguer les problèmes.