MSAL.NET 3 released

MSAL.NET 3.0.0 released

Overview

We are excited to announce the release of MSAL.NET 3.0-preview, which has a number of changes, which, we hope, you'll love. In this article, you'll learn about:

• Why MSAL.NET moved from MSAL 2.x to MSAL 3.x
  • Reacting to your feedback
  • Unified cache layout format change
• Changes in MSAL 3.x
  • Reference - list of all changes in MSAL.NET 3
  • Plans for deprecation in MSAL.NET 3.x, MSAL 4.x
  • Configuring an app got simpler
  • Acquiring a token also got simpler
  • Advanced: You can provide your own web view
  • Breaking changes in MSAL.NET 3.x
  • How to maintain SSO with apps written with ADAL v3, ADAL v4, MSAL.NET v2

Contrary to the previous versions for which the NuGet package had lost its -preview, the NuGet package for this version is 3.0.0-preview as we'd want to have your feedback about our changes, the new API, and the Plans for deprecation in MSAL.NET 3.x and MSAL.NET 4.x

Why MSAL.NET moved from MSAL 2.x to MSAL 3.x

This paragraph explains why MSAL.NET's major version number was bumped-up from 2 to 3. If you are new to MSAL.NET or are not interested in the reasons for changing the API, you might want to skip to changes in MSAL.NET 3.x.

Reacting to your feedback

In August, we released MSAL.NET 2.0, and since you've been using it, and providing feedback. Since August we've released fourteen incremental updates of MSAL.NET, improving both the API and the behavior of the library. You've been awesome helping us move MSAL.NET to a great authentication library. But you also told us that things could still be improved, and that you needed more flexibility. If you are interested in the analysis of your feedback with links to issues your raised, see the following GitHub issue [New API] Improved 3.x API leveraging builders #810). We wanted to bring you these improvements, but that we had reached a limit in term of API complexity. Here are the details of this journey to come to the realization that we had to change the paradigm of the API.

You told us you needed more configuration for applications

Providing your own HttpClient, supporting Http proxy and customization of user agent headers

Among the GitHub issues, stack overflow questions or direct contact you made with us, it became clear that we had been missing scenarios which were important for you, like letting you pass an HttpClient that MSAL.NET could use. We understand that there are cases where you want fine grained control on the Http proxy for instance, which we had not been able to provide you at all (on .NET core), or in a limited way (.NET framework). Also ASP.NET Core has some very efficient ways of pooling the HttpClient instance, and MSAL.NET clearly did not benefit from it (for details see Use HttpClientFactory to implement resilient HTTP requests)

Configuring your app to target national and sovereign clouds was not straightforward

As some of you start working on writing apps that can not only target users in the Azure public cloud, but also in national and sovereign clouds (for instance the US government cloud), you gave us the feedback that you'd need help making this transition easier. There are several ongoing initiatives for this, but MSAL.NET could already make it easier for you to configure the cloud instance you want to target, and the audience of your application. Along the same lines, we also came to the realization that we could help you with the configuration of the application from configuration files, and provide guidance on how to do that better.

Partial summary: Better configuration for apps

It was clear that you needed more configuration options for instantiating applications … therefore more parameters to the constructors, and help to support configuration files.

You told us you needed more flexibility in methods acquiring tokens

MSAL.NET enables you to get access tokens to call protected APIs in different ways, depending on your scenario, itself depending on the kind of app you build, and the platform. See Scenarios.

When we implemented the AcquireTokenByDeviceCodeFlow method in MSAL.NET 2.2.0-preview we provided a parameter so that the method is cancelable, and you quickly asked us to do the same for all the AcquireTokenXX methods, which makes sense. This requires adding another parameter to all methods, but we would not want it to be mandatory, and therefore this meant more overloads (see below).

Similarly, the only way to react to conditional access exceptions in MSAL 2.x was, as explained in Handling Claim challenge exceptions in MSAL.NET, to use the extraQueryParameter. Unfortunately, this parameter was available only in two overrides of the AcquireTokenAsync (interactive) flow, and it was not working correctly. We needed to fix it, and provide a proper claims parameter to AcquireTokenXXXAsync methods, including AcquireTokenSilentAsync.

Finally, some advanced end-user scenarios, like letting the user pre-consent ahead of time were really hard to achieve, as you'll see in the next paragraph.

A limit was reached in term of method overloads

Let's take one of the scenarios where the developer experience was not good: acquiring a token interactively in a desktop or mobile application (The same reasoning can be extended to other scenarios). In that case you had to call AcquireTokenAsync, but the issue is that this method had 14 overloads (for details of all the parameters see Acquiring tokens interactively).

But the worse is that to achieve one goal (for instance, letting the end user pre-consent to specific scopes ahead of time), you had to use one specific overload with 7 parameters, and, just to pass extraScopesToConsent, you had to fill-in all the other parameters, and as a result, you had to study the documentation in detail to understand what could be good values for these parameters. This pain is illustrated in this article How to get consent for several resources, where you see that you had to write code like this just to be able to pass-in scopesForVendorApi (and some of you had no idea what to use for uiBehavior, or authority)

var result = await app.AcquireTokenAsync(scopesForCustomerApi,
                                         accounts.FirstOrDefault(),
                                         uiBehavior,
                                         string.Empty,
                                         scopesForVendorApi,
                                         app.Authority,
                                         uiParent);

There are several examples of this pain (extra query parameters being another), and we knew that we had to add more parameters to the AcquireTokenXXXAsync methods (for instance, the claims to handle conditional access), and therefore it seemed that we had to add more overloads.

But then came a question: would you think that having 56 overloads for AcquireTokenAsync would have been reasonable?

Wouldn't you prefer to only set the parameters you need? For instance, use another syntax like the following:

var result = await app.AcquireTokenInteractive(scopesForCustomerApi)
                     .WithAccount(accounts.FirstOrDefault())
                     .WithExtraScopesToConsent(scopesForVendorApi)
                     .ExecuteAsync();

We think that a limit was reached in term of overloads, both on some AcquireTokenXXXAsync methods, and on the constructors for the applications. We propose another approach, based on fluent APIs.

You told us you needed more extensibility

Another request you made was to give you more flexibility. For instance, you wanted to allow public applications to acquire token via authorization code #863. In .NET Core we don't provide interactive authentication because no Web control is available there (yet). But there are cases, like what the Azure CLI team have done, where you want to let the user sign-in and consent into the machine browser on the desktop. This can be done, but at the same time you don't want to sacrifice to security. Therefore you asked us to provide an extensible way to let you do that. Another example of this is our own Visual Studio team who has Electron applications (VS Feedback and Azure Storage explorer) and wanted sign-in to be delegated in their UI, while still benefiting from the rest of MSAL.NET.

Naming could be improved

Finally we heard that we could improve the naming of things a bit. Here is an example UIBehavior was the mechanism, in MSAL 2.x by which you could customize the user experience and direct the Microsoft identity platform to present a particular prompt experience. We got the feedback that the name UIBehavior did not speak much, and everybody in the industry is naming it Prompt therefore we've decided to rename UIBehavior to Prompt in all MSAL libraries, starting with MSAL 3.x

Testability of your app could be improved

In the past to help you test your app (for instance in MSAL 2.5.0-preview), it was still not easy to test the cache, and the applications by a lack of interfaces (for instance ITokenCache), and the mutability of application configuration (for example it was possible to set the RedirectUri of an app after constructing it)

Unified cache layout format change

MSAL 2.0 already enabled common token cache scenarios between ADAL and MSAL on the platforms supported by ADAL, and also between MSAL libraries on different platforms. However as we were recently working on initiatives to enable SSO between tools written in different languages, we discovered that, on Windows/Linux/MacOS, MSAL.NET and MSAL.Python (for instance), although using the same cache schema, did not share the same layout for the blob that is serialized when you implement your own custom cache serialization. Therefore, we slightly changed the layout format of the token cache blob to harmonize the format between MSAL.NET, MSAL Python and MSAL.Java. This is a breaking change, but we also provided a migration path. See how to maintain SSO with apps written with ADAL v3, ADAL v4, MSAL.NET v2 if you are interested in one of these.

Summarizing the feedback

To summarize what we learned, you needed:

• More flexibility in configuring your apps,
• More options to acquire tokens
• An API which enables your apps to be more testable
• Customization of the Web view should be possible (on .NET Core)

We had to change the API to enable this flexibility without making it overly complex. Therefore we've decided that MSAL.NET 3 would bring a lot of changes, but would also have to take a few breaking changes.

Changes in MSAL.NET 3.x

After providing the exhaustive reference list of changes in MSAL.NET, the following paragraph explains these in more detail.

Reference - list of changes in MSAL.NET 3

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

• 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 write applications for sovereign and national clouds, and help you choose the audience for your application.

Changes related to improving token acquisition:

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

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.

Plans for deprecation in MSAL.NET 3.x and MSAL.NET 4.x

As seen above, we are proposing a new MSAL.NET V3.0 API based on builders. For the moment (MSAL 3.0), proposes this new API side by side with the previous V2.0 APIs (still having AcquireTokenXXXAsync, and many overrides of these), in order to leave you time to migrate to the new API.

Here is the current proposal, on which we'd like to get your feedback:

• In 3 months, supposing that, like us, you love the new APIs, we'd want to deprecate the old V2.0 API. At that point, if you still use the old-style API, you'll see warnings encouraging you to move to the new API.
• Then in the next major version of MSAL.NET, the old V2.0 style APIs would disappear, leaving a very simple shape for the API. In the class diagram below, we've hidden the V2.0 style APIs, and that gives you an idea of what the public API could be in the next major release.

Configuring an app got simpler

With MSAL.NET 3.x, we made it much simpler to configure your application. You don't need to choose an override for a constructor. The recommended way is to use the static PublicClientApplicationBuilder and ConfidentiaClientApplicationBuilder classes and call the Create() or CreateFromOption() method. They both return a builder, to which you chain optional properties. When you have all your properties, you call Build() and that's it!

Simple scenarios are simple

If you want to create a desktop application, you can do it with the minimum information.

IPublicClientApplication app;
app = PublicClientApplicationBuilder.Create(clientId)
        .Build();

By default, this application will target Work and School Accounts and Microsoft personal accounts from the Microsoft Azure public cloud.

Now, let's assume that your application is a line of business application which is only for your organization, then you can write:

IPublicClientApplication app;
app = PublicClientApplicationBuilder.Create(clientId)
        .WithAuthority(AzureCloudInstance.AzurePublic, tenantId)
        .Build();

More complex scenarios remain simple

Where it becomes interesting is that programming for national clouds has now become simple: if you want your application to be a multi-tenant application in a national or sovereign cloud, you could write for instance, write:

IPublicClientApplication app;
app = PublicClientApplicationBuilder.Create(clientId)
        .WithAuthority(AzureCloudInstance.AzureUsGovernment, AadAuthorityAudience.AzureAdMultipleOrgs)
        .Build();

Finally, if you are an Azure AD B2C developer, you can specify your tenant like this. Note that you don't need to say that you want to bypass authority validation, which, we heard, was scary.

IPublicClientApplication app;
app = PublicClientApplicationBuilder.Create(clientId)
        .WithB2CAuthority($"https://fabrikamb2c.b2clogin.com/tfp/{tenant}/{PolicySignInSignUp}")
        .Build();

Of course there are several overloads of .WithAuthority with many different cases. For more information see Client applications in MSAL 3.x

You can now configure your application more easily through config files

Now, chances are that you probably have the application configuration in a file, rather than in the code. This is also possible as the application builder can create an application from Options. Here is how:

PublicClientApplicationOptions = GetOptions(); // your own method.
var app = PublicClientApplicationBuilder.CreateWithApplicationOptions(options)
.Build();

You'll find a more complete code sample in Client applications in MSAL 3.x

Acquiring a token also got simpler

Once you have your application, you want to acquire tokens. The same kind of pattern was used where you call:

app.AcquireTokenXXX(scopes, mandatory-parameters)
   .WithOptionalProperty(optional-property).
   .ExecuteAsync();

This means you no longer have plenty of overrides, you can choose the parameters you want to set. Finally ExecuteAsync() had an override taking a CancellationToken argument, making all the AcquireTokenXXX methods cancellable, as you requested!

app.AcquireTokenXXX(scopes, mandatory-parameters)
   .WithOptionalProperty(optional-property).
   .ExecuteAsync(cancellationToken);

For details, see Acquiring tokens and Scenrios and the links from these articles on the detailed token acquisition methods

Breaking changes in MSAL.NET 3.x

As mentionned in Why did MSAL move from 2.x to 3.x?, as we were cleaning-up the public API, and simplifying it, we introduced a small number of breaking changes which, we'd expect, should not affect you too much for most of the scenarios if you use the MSAL 2.x type API.

• We renamed a type (UIBehavior)
• Setting some properties of IClientApplicationBase and ClientApplicationBase after building the application did not make sense any longer, and was getting in the way for testability
• the application builder now creates the token cache for you, we recommand you to use this mechanism, not instantiate TokenCache yourself.

UIBehavior renamed to Prompt

The UIBehavior class was used until MSAL.NET 2.x to specify, in AcquireTokenAsync (interactive) which prompt the application developer wanted to expose to the user. The class was renamed to Prompt, as explained in Naming-could-be-improved

Logger and Telemetry are now set per application, and during its construction

Until MSAL.NET 3.0, you used to set the logger by setting properties on a static class named Logger. These properties were, therefore, the same for all the applications in your executable

If you have a method to log information

void MyLogginMethod(LogLevel level, string message, bool containsPii)
{
 Console.WriteLine($"MSAL {level} {containsPii} {message}");
 Console.ResetColor();
}

you used to write:

Logger.LogCallback = MyLogginMethod;
Logger.Level = LogLevel.Verbose;
Logger.PiiLoggingEnabled = true;

This is no longer possible. You'll need to use the new fluent API if you want to provide logging:

IPublicClientApplication app;
app = PublicClientApplicationBuilder.Create(config.ClientId)
        .WithLogging(MyLogginMethod, LogLevel.Verbose,
                     enablePiiLogging: true,
                     enableDefaultPlatformLogging: true)
        .Buid();

For more details see Logging in MSAL.NET

Some properties on Applications now need to be set by builders, and read through the configuration

Some properties in the V2.0 API style were settable after the application construction. The V3 builder style makes the application properties immutable. From MSAL.NET 3.x, if you need to use these properties, you now need to:

• Set them when you are building the application (that is with .WithParameter clauses on the application builder)
• Read them from the application's configuration

Here is the detail. They all are held by:

Property	Description	Which method of the application builder to user	How to read it?
Component	Identifier of the component (libraries/SDK) consuming MSAL.NET (telemetry)	.WithComponent(component)	app.AppConfig.Component
SliceParameters	Used for dogfood testing or debugging as a string of segments of the form key=value separated by an ampersand character	.WithExtraQueryParameters
ValidateAuthority	No longer needed	.WithAADAuthority does not require it, .WithB2CAuthority either, .WithAuthority still has a Boolean for specific cases
RedirectUri	URI at which the identity provider will contact back the application with the tokens	Set to defaults, or, for client applications, in the constructor with .WithRedirectUri	app.AppConfig.RedirectUri

How to maintain SSO with apps written with ADAL v3, ADAL v4, MSAL.NET v2

Breaking change in the MSAL.NET cache serialization format and API

MSAL 2.x was providing two serialization mechanisms:

• One to serialize/deserialize the cache to the unified cache format (V2). This was done through the Serialize and Deserialize extension methods on TokenCacheExtension.
• The other to serialize/deserialize the cache with both the MSAL V2 formats and the ADAL V3 format at once, therefore, in the case of Deserialize, merging the information from several serialization files if both were available (DeserializeUnifiedAndAdalCache and SerializeUnifiedAndAdalCache)

We've taken a breaking change in order to let you:

• benefit out of the box from a “True” Unified Cache serialized json format across libraries on Windows, Linux and MacOS
• upgrade your apps easily from ADAL v3 and ADAL v4 to MSAL v3 with-out loosing SSO (if you need it)
• upgrade easily your apps from MSAL v2 to MSAL v3 with-out loosing SSO (if you need it)

In MSAL.NET 3.x:, the ITokenCache interface is the following:

public interface ITokenCache
{
 void DeserializeMsalV2(byte[] msalV2State, bool merge);   // MSAL V2.0 format (was Deserialize() in MSAL 2.x)
 void DeserializeUnifiedAndAdalCache(CacheData cacheData); // Deprecated: ADAL V3.0 and MSAL V3.0 format
 void DeserializeMsalV3(byte[] bytes, bool merge);         // New: MSAL V3.0 unified cache format
 void DeserializeAdalV3(byte[] bytes, bool merge);         // New ADAL V3.0 format only with merge

 byte[] SerializeMsalV2();                                 // MSAL V2.0 format (was Serialize() in MSAL 2.x)
 CacheData SerializeUnifiedAndAdalCache();                 // Deprecated: ADAL V3.0 and MSAL V3.0 format
 byte[] SerializeMsalV3();                                 // New: MSAL V3.0 unified cache format
 byte[] SerializeAdalV3();                                 // New: for ADAL v3.0 cache format

 void SetAfterAccess(TokenCacheCallback afterAccess);
 void SetBeforeAccess(TokenCacheCallback beforeAccess);
 void SetBeforeWrite(TokenCacheCallback beforeWrite);
}

• CacheData and its methods are obsoleted with an aka.ms link to the explanations (this document)
• Instead of TokenCacheExtensions.SerializeUnifiedAndAdalCache we recommending using, SerializeAdalV3 and SerializeMsalV3 with an aka.ms link.
• Instead of TokenCacheExtensions.DeserializeUnifiedAndAdalCache we recommending using, DeserializeAdalV3 and DeserializeMsalV3 with override=false, and an aka.ms link.
• Instead of TokenCacheExtensions.Serialize we recommending using SerializeMsalV3 with an aka.ms link.
• Instead of TokenCacheExtensions.Deserialize recommending using and DeserializeMsalV3 with an aka.ms link.

Support plans for serialization formats

In future versions of MSAL (and ADAL), we'd want to start obsoleting some of the cache serialization format. Here is, for the moment, our proposed support matrix:

Library/version	Adal 3.x Format	MSAL 2.x Format	Msal 3.x format
ADAL.NET 3.0	Supported	-	-
ADAL.NET 4.0	Supported	Supported	-
ADAL.NET 5.0	Supported	Deprecate (Error)	Supported
ADAL.NET 6.0	Supported**	Removed	Supported
MSAL.NET 2.0*	Supported	Supported	-
MSAL.NET 3.0	Supported	Deprecate (Error)	Supported
MSAL.NET 4.0	*	Removed	Supported
MSAL.NET 3.0 + 12m*	Deprecate (Error) *		Supported
MSAL.NET 3.0 + 24m*	Removed *		Supported

Supported: means available and Supported

*: We plan on removing v3 support after sometime to make sure our codebase stays as simple as possible (however it may challenge the migration path if we remove it), timelines should be the driving factor or we can decide to leave as is. As we ship MSAL 3.0 we should mark MSAL v2 and as not supported (same with MSAL v1). we would monitor adoption to understand when the right moment is, to remove support for the v3 cache. Again your feedback would be valuable.

** : Leaving for now but we could consider removing that to ensure even if you are sticking to ADAL, your'd be using the new format.

Example of code showing how to migrate from MSAL.NET v2 to MSAL.NET v3

There are two scenarios depending on the type of app: one time migration and side by side migration:

• One time migration. This is the recommended approach for MSAL public client applications which don’t share the cache with other apps or generations of apps, and for confidential client applications that don’t use a distributed cache shared between several web instances: it’s simple (try read V3, if it fails read V2, in any case write V3). This approach is possible as of today with MSAL 3.0.0-preview

  /// <summary>
  /// Enables persistence of the token cache to some storage
  /// </summary>
  /// <param name="unifiedCacheStorageKey">Key (for instance file name in the cache of a
  //  file storage) where the cache is serialized with the Unified cache format
  /// </param>
  public static void EnableFilePersistence(ITokenCache userTokenCache,
                                                 string unifiedCacheStorageKey)
  {
   UnifiedCacheStorageKey = unifiedCacheFileName;
   userTokenCache.SetBeforeAccess(BeforeAccessNotification);
   userTokenCache.SetAfterAccess(AfterAccessNotification);
  }
  
  /// <summary>
  /// File path where the token cache is serialiazed with the unified cache format
  /// </summary>
  public static string UnifiedCacheStorageKey { get; private set; }
  
  public static void BeforeAccessNotification(TokenCacheNotificationArgs args)
  {
   byte[] serializedData = ReadFromStorageIfExists(UnifiedCacheStorageKey);
   try
   {
    args.TokenCache.DeserializeMsalV3(serializedData, override:true);
   }
   catch (MsalUnexpectedCacheFormatException)
   {
    args.TokenCache.DeserializeMsalV2(serializedData, override:true);
   }
  }
  
  public static void AfterAccessNotification(TokenCacheNotificationArgs args)
  {
   // if the access operation resulted in a cache update
   if (args.HasStateChanged)
   {
    byte[] serializedCache = args.TokenCache.SerializeMsalV3();
    WriteToStorageIfNotNull(UnifiedCacheStorageKey, serializedCache);
   }
  }

• For MSAL public client apps that share the cache with other apps or web apps/apis that share the cache between several instances, you'll need to implement a dual MSAL V2 / MSAL V3 for a while until all apps or web instances have migrated. Then remove the support for the MSAL V2 cache format. For this we'll provide (in a later version of MSAL 3.x) an API enabling you to deserialize with merge. This is not implemented yet in MSAL 3.0.0-preview (hence the preview), but our plans are to enable it soon. For the moment if you try to use the Deserialize APIs with merge=true, MSAL will throw a NotImplementedException with a meaningful message

  /// <summary>
  /// Enables persistence of the token cache to some storage
  /// </summary>
  /// <param name="msalV2CacheStorageKey">Key (for instance file name in the cache of a
  //  file storage) where the cache is serialized with the Unified cache format of
  /// MSAL 2.x
  /// <param name="msalV3CacheStorageKey">Key (for instance file name in the cache of a
  //  file storage) where the cache is serialized with the Unified cache format of
  /// MSAL 3.x
  /// </param>
  public static void EnableFilePersistence(ITokenCache userTokenCache,
                                           string msalV2CacheStorageKey,
                                           string msalV3CacheStorageKey)
  {
   MsalV2CacheStorageKey = msalV2CacheStorageKey;
   MsalV3CacheStorageKey = msalV3CacheStorageKey;
   userTokenCache.SetBeforeAccess(BeforeAccessNotification);
   userTokenCache.SetAfterAccess(AfterAccessNotification);
  }
  
  /// <summary>
  /// File path where the token cache is serialiazed with the unified cache format
  /// </summary>
  public static string UnifiedCacheStorageKey { get; private set; }
  
  public static void BeforeAccessNotification(TokenCacheNotificationArgs args)
  {
   args.TokenCache.DeserializeMsalV2(null);
  
   byte[] serializedData = ReadFromStorageIfExists(MsalV2CacheStorageKey);
   args.TokenCache.DeserializeMsalV2(serializedData, merge:true);
   serializedData = ReadFromStorageIfExists(MsalV3CacheStorageKey);
   args.TokenCache.DeserializeMsalV3(serializedData, merge:true);
  }
  
  public static void AfterAccessNotification(TokenCacheNotificationArgs args)
  {
   // if the access operation resulted in a cache update
   if (args.HasStateChanged)
   {
    byte[] serializedCache = args.TokenCache.SerializeMsalV3();
    WriteToStorageIfNotNull(MsalV3CacheStorageKey, serializedCache);
    serializedCache = args.TokenCache.SerializeMsalV2();
    WriteToStorageIfNotNull(MsalV2CacheStorageKey, serializedCache);
   }
  }

Example code demonstrating how it will be possible (in MSAL 3.1+) to share SSO across all versions

For the moment, the versions of the API exposing a merge parameter are not implemented in MSAL 3.0.0-preview. But we thought we'd share our plans to help you updating the SSO state in all the possible ways leveraging this parameter in the future (soon after 3.0.0-preview)

// Assigning a token cache to the public client (it's similar for Confidential client, though there a cache for the Application is also avaialble):
IPublicClientApplication app = PublicClientApplicationBuilder.Create(ClientId)
 .WithAuthority(Authority)
 .Build();

// Setting up the cache allowing loading and persisting the data
TokenCache usertokenCache = app.UserTokenCache
usertokenCache.SetBeforeAccess(BeforeAccessNotification);
usertokenCache.SetAfterAccess(AfterAccessNotification);

// Event handlers
private void BeforeAccessNotification(TokenCacheNotificationArgs args)
{
 // Load cache state from file
 byte[] adalV3State = FileStorage.ReadFromFileIfExists(AdalV3FileName);
 byte[] msalv2State = FileStorage.ReadFromFileIfExists(MsalV2FileNAme);
 byte[] msalv3State = FileStorage.ReadFromFileIfExists(MsalV3FileName);

 // To be deprecated
 args.TokenCache.DeserializeUnifiedAndAdalCache(cacheData);

 // Each deserialize call will merge from what has already been loaded
 bool merge = true;

 // Add the following cache deserializers
 // Writes to cache used in ClientApplication
 args.TokenCache.DeserializeAdalV3(adalV3State, merge);
 args.TokenCache.DeserializeMsalV2(msalv2State, merge);
 args.TokenCache.DeserializeMsalV3(msalv3State, merge);
}

private void AfterAccessNotification(TokenCacheNotificationArgs args)
{
    if (!args.HasStateChanged)
    {
        return;
    }

    // Deprecate
    CacheData cacheData = args.TokenCache.SerializeUnifiedAndAdalCache();
    var prevAdalV3State = cacheData.AdalV3State;
    var prevMsalV2State = cacheData.UnifiedState;

    // Add the following cache serializers
    // Reads from the cache in the ClientApplication
    byte[] adalV3State = args.TokenCache.SerializeAdalV3();
    byte[] msalv2State = args.TokenCache.SerializeMsalV2();
    byte[] msalv3State = args.TokenCache.SerializeMsalV3();

    // Persist cache state to file (depending on the migration scenario)
    FileStorage.WriteToFileIfNotNull(AdalV3FileName, adalV3State);
    FileStorage.WriteToFileIfNotNull(MsalV2FileNAme, msalv2State);
    FileStorage.WriteToFileIfNotNull(MsalV3FileName, msalv3State);
}

You can provide your own web view

Implement ICustomWebUI

As explained in You told us you needed extensibility, we have provided some extensibility so that you can provide your own UI in public client applications, to let the user go through the /Authorize endpoint of the identity provider and let them sign-in and consent, and then let MSAL.NET redeem the authentication code and get a token.

If you need to provide your own Web UI:

1. Implement the ICustomWebUi interface (See here. You'll basically need to implement one method AcquireAuthorizationCodeAsync accepting the authorization code URL (computed by MSAL.NET), letting the user go through the interaction with the identity provider, and then returning back the URL by which the identity provider would have called your implemetnation back (including the authorization code). In case of issues, your implementation should throw a MsalExtensionException exception in order to nicely cooperate with MSAL.
2. In your AcquireTokenInteractiveCall, you can use the .WithCustomUI() modifier passing the instance of your custom web UI

Security is respected

Note that, in public client applications, MSAL.NET leverages the PKCE standard (RFC 7636 - Proof Key for Code Exchange by OAuth Public Clients) to ensure that security is respected: Only MSAL.NET can redeem the code.

MSAL.NET UI tests also use this mechanism

We have rewritten our UI tests to leverage this extensibility mechanism. In case you are interested you can have a look at the SeleniumWebUI class in the MSAL.NET source code

Future plans

Note that we also have plans to provide ourselves in the future:

• AcquireTokenInteractive for .NET Core 3+ on Windows
• leveraging the desktop default browser on MacOS and Linux