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 supportability improvements.

MsalError brings a number of new error messages to help you troubleshooting your application configuration.

public static class MsalError 
{
 ...
 public const string ClientIdMustBeAGuid = "client_id_must_be_guid";
 public const string InvalidClient = "invalid_client";
 public const string InvalidInstance = "invalid_instance";
 public const string InvalidUserInstanceMetadata = "invalid-custom-instance-metadata";
 public const string NoClientId = "no_client_id";
 public const string TelemetryConfigOrTelemetryCallback = "telemetry_config_or_telemetry_callback";
 public const string ValidateAuthorityOrCustomMetadata = "validate_authority_or_custom_instance_metadata";
}

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