Lidar com erros e exceções no MSAL para iOS/macOS

Este artigo apresenta uma visão geral dos diferentes tipos de erros e recomendações para lidar com erros comuns de iniciação de sessão.

Noções básicas de gestão de erros MSAL

As exceções na Biblioteca de Autenticação da Microsoft (MSAL) destinam-se aos programadores de aplicações para resolver problemas, não para serem exibidas aos utilizadores finais. As mensagens de exceção não são localizadas.

Ao processar exceções e erros, pode usar o próprio tipo de exceção e o código de erro para distinguir entre exceções. Para uma lista de códigos de erro, consulte códigos de erro de autenticação e autorização Microsoft Entra.

Durante a experiência de login, pode encontrar erros sobre consentimentos, Acesso Condicional (MFA, Gestão de Dispositivos, restrições baseadas na localização), emissão e resgate de tokens, e propriedades dos utilizadores.

A secção seguinte fornece mais detalhes sobre o tratamento de erros na sua aplicação.

Tratamento de erros no MSAL para iOS/macOS

A lista completa de erros MSAL para iOS e macOS está listada em MSALError enum.

Todos os erros produzidos pelo MSAL são devolvidos com o domínio MSALErrorDomain.

Para erros do sistema, o MSAL retorna o original NSError da API do sistema. Por exemplo, se a aquisição de tokens falhar devido à falta de conectividade à rede, o MSAL devolve um erro com o domínio NSURLErrorDomain e o código NSURLErrorNotConnectedToInternet.

Recomendamos que trate, pelo menos, os dois erros MSAL seguintes do lado do cliente:

• MSALErrorInteractionRequired: O utilizador deve fazer um pedido interativo. Existem muitas condições que podem levar a este erro, como uma sessão de autenticação expirada ou a necessidade de requisitos adicionais de autenticação. Chame a API de aquisição interativa de tokens do MSAL para recuperar.

• MSALErrorServerDeclinedScopes: Alguns ou todos os âmbitos foram rejeitados. Decida se continua apenas com os parâmetros concedidos ou se interrompe o processo de registo.

Por exemplo, MSALInternalErrorBrokerResponseNotReceived significa que o utilizador não completou a autenticação e voltou manualmente à aplicação. Neste caso, a sua aplicação deve mostrar uma mensagem de erro genérica a explicar que a autenticação não foi concluída e sugerir que tentem autenticar-se novamente.

O seguinte Objective-C código de exemplo demonstra as melhores práticas para lidar com algumas condições comuns de erro.

    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)

Acesso Condicional e desafios de sinistros

Ao obter tokens silenciosamente, a sua aplicação pode receber erros quando um pedido de reivindicações de Acesso Condicional, como uma política de MFA, for exigido pela API à qual está a tentar aceder.

O padrão para lidar com este erro é adquirir interativamente um token usando MSAL. Isto incita o utilizador e dá-lhe a oportunidade de cumprir a política de Acesso Condicional exigida.

Em determinados casos, ao chamar uma API que requer Acesso Condicional, pode receber um pedido de declarações na mensagem de erro da API. Por exemplo, se a política de Acesso Condicional for ter um dispositivo gerido (Intune), o erro será algo como AADSTS53000: O seu dispositivo é obrigado a ser gerido para aceder a este recurso ou algo semelhante. Neste caso, pode passar as declarações na chamada de aquisição de token para que o utilizador seja solicitado a satisfazer a política adequada.

O MSAL para iOS e macOS permite-lhe solicitar reivindicações específicas tanto em cenários interativos como silenciosos de aquisição de tokens.

Para solicitar reivindicações personalizadas, especifique claimsRequest em MSALSilentTokenParameters ou MSALInteractiveTokenParameters.

Consulte Solicitar pedidos personalizados usando MSAL para iOS e macOS para mais informações.

Tentar novamente após erros e exceções

Espera-se que implemente as suas próprias políticas de repetição ao chamar a MSAL. A MSAL faz chamadas HTTP ao serviço Microsoft Entra e, ocasionalmente, podem ocorrer falhas. Por exemplo, a rede pode cair ou o servidor ficar sobrecarregado.

HTTP 429

Quando o Service Token Server (STS) está sobrecarregado com demasiados pedidos, devolve o erro HTTP 429 com uma dica sobre quanto tempo até poderes tentar novamente no Retry-After campo de resposta.

Passos seguintes

Considere ativar o registo no MSAL para iOS/macOS para ajudar a diagnosticar e depurar problemas.