Control de errores y excepciones en MSAL para iOS/macOS

En este artículo se proporciona información general sobre los distintos tipos de errores y recomendaciones para controlar los errores de inicio de sesión comunes.

Aspectos básicos del control de errores de MSAL

Las excepciones de Biblioteca de autenticación de Microsoft (MSAL) están diseñadas para que los desarrolladores de aplicaciones solucionen problemas, no para mostrarlos a los usuarios finales. Los mensajes de excepción no se localizan.

Al procesar excepciones y errores, puede usar el propio tipo de excepción y el código de error para distinguir entre excepciones. Para obtener una lista de códigos de error, consulte Microsoft Entra códigos de error de autenticación y autorización.

Durante la experiencia de inicio de sesión, puede encontrar errores sobre los consentimientos, el acceso condicional (MFA, Administración de dispositivos, restricciones basadas en ubicación), la emisión y el canje de tokens y las propiedades del usuario.

En la sección siguiente se proporcionan más detalles sobre el control de errores de la aplicación.

Control de errores en MSAL para iOS/macOS

La lista completa de errores de MSAL para iOS y macOS se encuentra en la enumeración MSALError.

Todos los errores generados por MSAL se devuelven con el dominio MSALErrorDomain.

Respecto a los errores de sistema, MSAL devuelve el NSError original de la API del sistema. Por ejemplo, si se produce un error al adquirir tokens debido a la falta de conectividad de red, MSAL devuelve un error con el dominio NSURLErrorDomain y el código NSURLErrorNotConnectedToInternet.

Se recomienda controlar al menos los dos errores de MSAL siguientes en el lado cliente:

• MSALErrorInteractionRequired: el usuario debe realizar una solicitud interactiva. Hay muchas condiciones que pueden provocar este error, como una sesión de autenticación expirada o la necesidad de requisitos de autenticación adicionales. Llame a la API de adquisición de tokens interactivos de MSAL para recuperarse.

• MSALErrorServerDeclinedScopes: Se rechazaron algunos o todos los ámbitos. Decida si desea continuar con solo los ámbitos concedidos o detener el proceso de inicio de sesión.

Por ejemplo, MSALInternalErrorBrokerResponseNotReceived significa que el usuario no completó la autenticación y volvió manualmente a la aplicación. En este caso, la aplicación debe mostrar un mensaje de error genérico que explica que la autenticación no se completó y sugiere que intentan autenticarse de nuevo.

En el siguiente código de ejemplo Objective-C se muestran los procedimientos recomendados para controlar algunas condiciones de error comunes.

    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)

Desafíos del acceso condicional y las reclamaciones

Al obtener los tokens de forma automática, la aplicación puede recibir errores si una API a la que intenta acceder requiere un desafío de notificaciones de acceso condicional como, por ejemplo, una directiva de autenticación multifactor.

El patrón para controlar este error es adquirir de forma interactiva un token mediante MSAL. De esta forma, se avisa al usuario y le da la oportunidad de cumplir con la directiva de acceso condicional requerida.

En algunos casos, al llamar a una API que requiere acceso condicional, puede recibir un desafío de notificaciones en el error de la API. Por ejemplo, si la directiva de acceso condicional es tener un dispositivo administrado (Intune), el error será similar a AADSTS53000: el dispositivo debe administrarse para acceder a este recurso o algo similar. En este caso, puede pasar las notificaciones de la llamada de adquisición del token de manera que se le pida al usuario que cumpla con la directiva adecuada.

MSAL para iOS y macOS permite solicitar notificaciones específicas en escenarios de adquisición de tokens interactivos y silenciosos.

Para solicitar claims personalizadas, especifique claimsRequest en MSALSilentTokenParameters o MSALInteractiveTokenParameters.

Consulte Solicitud de notificaciones personalizadas con MSAL para iOS y macOS para obtener más información.

Reintentar después de errores y excepciones

Se espera que implemente sus propias directivas de reintentos al llamar a MSAL. MSAL realiza llamadas HTTP al servicio Microsoft Entra y, en ocasiones, se pueden producir errores. Por ejemplo, la red puede bajar o el servidor está sobrecargado.

HTTP 429

Cuando el servidor de token de servicio (STS) está sobrecargado con demasiadas solicitudes, devuelve el error HTTP 429 con una sugerencia sobre cuánto tiempo hasta que pueda intentarlo de nuevo en el Retry-After campo de respuesta.

Pasos siguientes

Considere la posibilidad de habilitar el registro en MSAL para iOS/macOS para ayudarle a diagnosticar y depurar problemas.