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,
• Startup performance improvements,
• Better control of user experience when invalid grant: 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

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

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 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