MSAL.NET Version 3.0.0-preview

• For more info on the release, along with code samples, checkout https://aka.ms/msal-net-3x

Breaking changes in MSAL.NET 3:

• UIBehavior was renamed to Prompt (breaking change)
• TokenCacheNotificationArgs now surfaces an ITokenCache instead of a TokenCache. This will allow MSAL.NET to provide, in the future, various token cache implementations.
• TokenCacheExtensions was removed and its methods moved to ITokenCache (this is a binary breaking change, but not a source level breaking change)
• The Serialize and Deserialize methods on TokenCacheExtention (which were serializing/deserializing the cache to the MSAL v2 format) were moved to ITokenCache and renamed SerializeMsaV2 and `DeserializeV2

Changes related to improving app Creation and configuration MSAL issue

• New class ApplicationOptions helps you build an application, for instance, from a configuration file
• New interface IMsalHttpClientFactory to pass-in the HttpClient to use by MSAL.NET to communicate with the endpoints of Microsoft identity platform for developers.
• New classes PublicClientApplicationBuilder and ConfidentialClientApplicationBuilder propose a fluent API to instantiate respectively classes implementing IPublicClientApplication and IConfidentialClientApplication including from configuration files, setting the targetted cloud and audience, but also setting per application logging and telemetry, and setting the HttpClient.
• New delegates TelemetryCallback and TokenCacheCallback can be set at application construction
• New enumerations AadAuthorityAudience and AzureCloudInstance help you writing applications for sovereign and national clouds, and help you choose the audience for your application.

Changes related to improving token acquisition, addressing issues 810, 635, 426, 799 :

• ClientApplicationBase now implements IClientApplicationBase and has new members:
  • AppConfig of new type IAppConfig contains the configuration of the application
  • UserTokenCache of new type ITokenCache contains the user token cache (for both public and confidential client applications for all flows, but AcquireTokenForClient)
    • New fluent API AcquireTokenSilent
• PublicClientApplication and IPublicClientApplication have four new fluent APIs: AcquireTokenByIntegratedWindowsAuth, AcquireTokenByUsernamePassword, AcquireTokenInteractive, AcquireTokenWithDeviceCode.
• ConfidentialClientApplication has new members:
  • AppTokenCache used by AcquireTokenForClient
  • Five new fluent APIs: AcquireTokenByAuthorizationCode, AcquireTokenForClient, AcquireTokenOnBehalfOf, GetAuthorizationRequestUrl, IByRefreshToken.AcquireTokenByRefreshToken
• New extensibility mechanism to enable public client applications to provide, in a secure way, their own browsing experience to let the user interact with the Microsoft identity platform endpoint (advanced). For this, applications need to implement the ICustomWebUi interface and throw MsalCustomWebUiFailedException exceptions in case of failure. This can be useful in the case of platforms which don't have yet a Web browser. For instance, the Visual Studio Feedback tool is an Electron application which uses this mechanism. MSAL issue
• MsalServiceException now surfaces two new properties:
  • CorrelationId which can be useful when you interact with Microsoft support.
  • SubError which indicates more details about why the error happened, including hints on how to communicate with the end user. MSAL issue

Changes related to the token cache:

• New interface ITokenCache contains primitives to serialize and deserialize the token cache and set the delegates to react to cache changes
• New methods SerializeMsalV3 and DeserializeMsalV3 on ITokenCache serialize/deserialize the token cache to a new layout format compatible with other MSAL libraries on Windows/Linux/MacOS.

A few bug fixes:

• Update Xamarin dependencies
• Send client headers to the user realm endpoint