MsalUiRequiredException classification

Note: Feature available from: 4.1

Understanding MsalUiRequiredException

When performing an AcquireTokenSilent call, MSAL may respond by throwing an MsalUiRequiredException, which indicates that interactive auth is needed.

Most of the time when AcquireTokenSilent fails, it is because the token cache does not have tokens matching your request. Access tokens expire in 1h, and AcquireTokenSilent will try to fetch a new one based on a refresh token (in OAuth2 terms, this is the "Refresh Token' flow). This flow can also fail for various reasons, for example if a tenant admin configures more stringent login policies.

MsalUiRequiredException Classification

MSAL exposes a Classification field, which you can read to provide a better user experience, for example to tell the user that his password expired or that he will need to provide consent to use some resources. The supported values are:

Classification	Meaning	Recommended handling
basic_action	Condition can be resolved by user interaction during the interactive authentication flow.	Call AcquireTokenInteractively().
additional_action	Condition can be resolved by additional remedial interaction with the system, outside of the interactive authentication flow.	Call AcquireTokenInteractively() to show a message that explains the remedial action. Calling application may choose to hide flows that require additional_action if the user is unlikely to complete the remedial action.
message_only	Condition cannot be resolved at this time. Launching interactive authentication flow will show a message explaining the condition.	Call AcquireTokenInteractively() to show a message that explains the condition. AcquireTokenInteractively() will return UserCanceled error after the user reads the message and closes the window. Calling application may choose to hide flows that result in message_only if the user is unlikely to benefit from the message.
consent_required	User consent is missing, or has been revoked.	Call AcquireTokenInteractively() for user to give consent.
user_password_expired	User's password has expired.	Call AcquireTokenInteractively() so that user can reset their password.
[empty string]	Condition may be resolved by user interaction during the interactive authentication flow.	Call AcquireTokenInteractively().

Code Example

// Example app that tries to download some documents
foreach (var documentUrl in documentUrls) 
{
    try 
    {
        var account = await pca.GetAccountsAsync().FirstOrDefault();
        var authenticationResult = await pca.AcquireTokenSilent(new[] { "scopes" }, account).ExecuteAsync();
        
        await downloadDocumentAsync(documentUrl, authenticationResult.AccessToken);
    }
    catch (MsalUiRequiredException ex) 
    {
        switch (ex.Classification) 
        {
            case MsalUiRequiredException.BasicAction:
                // Show the button that invokes AcquireTokenInteractively() 
                showFixItButton();
                break;
            case MsalUiRequiredException.AdditionalAction:
                // Show a message that explains to the user that fixing the problem is more involved.
                showAdditionalActionMessage();
                // Show the button that invokes AcquireTokenInteractively() 
                showFixItButton();
                break;
            case MsalUiRequiredException.MessageOnly:
                // Do nothing here. Skip documents that cannot be downloaded at this time.
                break;
            default:
                // Invoke default error handling routine that assumes no tokens can be issued, and no documents can be shown. 
                // Hide all thumbnails and show a button to fix the issue.
                hideAllDocuments();
                showSignInMessage();
                showFixItButton();
                break;
        }
    }
}