msal net 4.2

MSAL.NET 4.2 will release this week

We are excited to announce the release of MSAL.NET 4.2 which brings a number of new features:

• Broker support for Xamarin iOS and Xamarin Android,
• Better control of user experience on invalid grant MsalUiRequiredException: A new property named Classification on MsalUiRequiredException to help you providing an optimal user experience when you receive an invalid grant error.
• Better usability of the API on Xamarin
• Startup performance improvements,

Broker support on Xamarin.iOS and Xamarin.Android

What are brokers?

Brokers are applications, provided by Microsoft on Android and iOS (Microsoft Authenticator on iOS and Android, InTune Company Portal on Android). They enable:

• Single-Sign-On,
• Device identification, which is required by some conditional access policies (See Device management
• Application identification verification also required in some enterprise scenarios (See for instance Intune mobile application management, or MAM)

How to enable them?

If you build an application that needs to work in tenants where conditional access is enabled, or if you want your users can benefit from a better experience, you should enable brokers. This is simple. you'll need to call WithBroker() at the construction of the application. Then when the user signs-in interactively, they will be directed by Azure AD to install a broker from the store depending on the conditional access policies. When this is done, the next interactive authentication will use the broker.

For details, see TODO https://aka.ms/msal-net-brokers for more information on platform specific settings required to enable the broker.

IPublicClientApplication application = PublicClientApplicationBuilder.Create(clientId)
  .WithDefaultRedirectUri()
  .WithBroker()
  .Build();

New Classification property on MsalUiRequiredException enables you to provide a better user experience in your apps

One of common status codes returned from MSAL.NET when calling AcquireTokenSilent() is MsalError.InvalidGrantError. This status code means that the application should call the authentication library again, but in interactive mode (AcquireTokenInteractive or AcquireTokenByDeviceCodeFlow for public client applications, and do a challenge in Web apps). This is because additional user interaction is required before authentication token can be issued.

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, the user's password has expired, the user needs to accept term of usage, etc ... the interaction aims at having the user do an action. Some of those conditions are easy for users to resolve (e.g. accept Terms of Use with a single click), and some cannot be resolved with the current configuration (e.g. the machine in question needs to connect to a specific corporate network). Some help the user setting-up Multi-factor authentication, or install Microsoft Authenticator on their device.

To help you guide the end user and provide a very good UX, you needed more data to make a decision on how to handle the exception. MsalUiRequiredException now exposes a new public property named Classification of type UiRequiredExceptionClassification. It helps you decide what to do in case of Invalid grant errors, informing the user, or batching conditional access or consent for instance.

The UiRequiredExceptionClassification is the following:

public enum UiRequiredExceptionClassification
{
 None = 0,
 MessageOnly = 1,
 BasicAction = 2,
 AdditionalAction = 3,
 ConsentRequired = 4,
 UserPasswordExpired = 5,
 PromptNeverFailed = 6,
 AcquireTokenSilentFailed = 7,
}

For details on how to handle if, see https://aka.ms/msal-net-UiRequiredException

Improved API on Xamarin

IPublicClientApplication application = PublicClientApplicationBuilder.Create(clientId)
  .ParentActivityOrWindowFunc(() => parent)
  .Build();

Self troubleshooting improvements.

MSAL.NET 4.2 brings a number of new MsalError constants with actionalbe error messages to help you troubleshooting your app registration and configuration. For instance, you'll now receive:

Error	Description
ClientIdMustBeAGuid	if you specify a ClientId at app creation, which is not a System.Guid. We hesitated to force MSAL.NET public API to use Guid in the past, but this was not helping the code readability. We prefered to guard you with a meaningfull error message
NoClientId	You usedCreateFromOptions()` to build your application but did not provide a clientID. Be sure to use the application ID from the application registration portal.
InvalidClient	when you have forgotten to specifiy that your application is a public client during app registration whereas you are using Integrated Windows Authentication, Device Code Flow or Username/Password. The error message also provides a self-troubleshooting aka.ms link: https://aka.ms/msal-net-invalid-client
InvalidInstance	AAD service error indicating that the configured authority does not exist
TelemetryConfigOrTelemetryCallback	You have configured both a telememtry callback and a telemetry config. Be sure to configure only one telemetry mechanism

Improved application startup cost, disconnected scenarios and advanced scenarios

In MSAL.NET 4.1, we started work to improve the application startup cost, and support disconnected scenarios (where you want to have access to the accounts without the device being connected to Internet). See GetAccounts and AcquireTokenSilent are now less network chatty for details. With MSAL.NET 4.2, we are completing this initiative but letting you speciy yourself the Instance discovery metadata, and disable the automatic instance discovery.

Most of you will never need to use this advanced feature, which should be left to some advanced scenarios where:

• performance of a command line tool frequently called by other processes is crucial (Think of Git Credential Manager for instance called frequently from Git command line tools or Visual Studio or Visual Studio Code)
• you are aware of security implications.

For details, read Msal Custom Authority Aliases