MSAL.NET 3 released

MSAL.NET 3.0.0 released

This page is not complete yet. This is Work in Progress

Overview

We are excited to announce the release of MSAL.NET 3.0, which has a number of changes, which, we hope, you'll love. This section provides an overview of this article.

• Why did MSAL move from MSAL 2.x to MSAL 3.x?
  • need for more parameters to construct applications or acquire tokens
  • we heard your feedback. Logger per application.
  • need for extensibility.
  • slight change in the unified cache format to harmonize MSAL's across langages on Windows, Linux and Mac.
• changes in MSAL 3.x
• Introduction of fluent APIs to build the applications and acquire tokens
• detailed list of changes
  • UIBehavior was renamed to Prompt (breaking change)
  • 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
  • ConfidentialClientApplication has new members:
    • AppTokenCache used by AcquireTokenForClient
    • five new fluent APIs: AcquireTokenByAuthorizationCode, AcquireTokenForClient, AcquireTokenOnBehalfOf, GetAuthorizationRequestUrl, IByRefreshToken.AcquireTokenByRefreshToken
  • PublicClientApplication and IPublicClientApplication have four new fluent APIs: AcquireTokenByIntegratedWindowsAuth, AcquireTokenByUsernamePassword, AcquireTokenInteractive, AcquireTokenWithDeviceCode,
  • New interface ITokenCache contains primitives to serialize and deserialize the token cache and set the delegates to react to cache changes
  • 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.
  • TokenCacheExtensions was removed (this is a binary breaking change, but not a source level breaking change)
  • New delegates TelemetryCallback and TokenCacheCallback can be set at application construction
  • TokenCacheNotificationArgs now surfaces an ITokenCache instead of a TokenCache. This will allow us to provide various token cache implementations in the future
  • New enumerations AadAuthorityAudience and AzureCloudInstance help you writing applications for sovereign and national clouds, and help you choose the audience for your application.
  • New class ApplicationOptions to build an application, for instance from a configuration file
  • New classes PublicClientApplicationBuilder and ConfidentialClientApplicationBuilder propose a fluent API to instanciate respectively PublicClientApplication and ConfidentialClientApplication including from configuration files, but also setting per application logging and telemetry, and setting the HttpClient.
  • New interface IMsalHttpClientFactory to pass-in the HttpClient to use by MSAL.NET to communicate with Azure AD.
  • 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 Azure AD authorize endpoint (advanced). 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.

Why did MSAL move from 2.x to 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 the new paragraph which explains the changes.

What could be improved in the MSAL.NET 2.x API

TODO: discussion about the many overloads, the needs for more, the difficulty to, for instance handle claims challenge (through extraQueryParameter, present in one overload, and last parameter, whereas you have no idea what to set for the previous ones. TODO: discussion about the naming TODO: discussion about how to configure the app, the confustion authority/endpoint, the need for a doc to target sovereign clouds or change the audience

Need for extensibility

Unified cache layout format change

The schema of the Unified cache has not changed between MSAL 2.x and MSAL 3.x. This is work which was done between MSAL 1.x and MSAL 2.0 to enable sharing token caches between ADAL and MSAL on the platforms supported by ADAL, and also between MSAL libraries on the platforms. However, we slightly changed the layout format of the token cache on disk to harmonize the file format of MSAL.NET, and MSAL Python and MSAL.Java

Application configuration got simpler

With MSAL.NET 3.x, we made it much simpler to configure your application. You don't need to choose an override. There is one constructor for PublicClientApplication, and one for ConfidentialClientApplication. They both return a builder, to which you chain properties. When you have all your properties, you call Build() and that's it.

Simple scenarios are simple. Complex scenarios remain 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)
        .WithAadAuthority(AzureCloudInstance.AzurePublic, tenantId)
        .Build();

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)
        .WithAadAuthority(AzureCloudInstance.AzureUsGovernment, AadAuthorityAudience.AzureAdMultipleOrgs)
        .Build();

Finally, if you are an Azure AD B2C developer, you can specify your tenant like this:

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

Of course there are several overloads of .WithAadAuthority 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();

Calling an AcquireToken method got simpler as well

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

app.AcquireTokenXXX()
   .WithProperty(property).
   .ExecuteAsync();

This means you no longer have plenty of overrides, you can choose the parameters you want to set. Finally all the ExecuteAsync methods can have a CancellationToken argument, making them cancellation.

TODO: elaborate

Changes in MSAL.NET 3.x

As seen above, we are proposing the new V3.0 API based on builders side by side with the previous V2.0 APIs (having AcquireTokenXXXAsync, and many overrides of these)

In order to leave you time to migrate to the new API, here is the plan that we propose:

• For the moment both APIs are exposed, and we'd like to get your feedback on them.
• 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 them 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.

Breaking changes in MSAL.NET 3.x

However, as we were cleaning-up the public API, and simplifying it:

• Some properties of IClientApplicationBase and ClientApplicationBase did not make sense any longer
• We renamed a type (UIBehavior)

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.

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 .With 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, allowing for disambiguation between MSAL usage by the app vs MSAL usage by component libraries (mostly for telemetry purpose)	.WithComponent(component)	app.AppConfig.Component
SliceParameters	Used to be a set of custom query parameters that may be sent to the STS 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 has a Boolean for specific cases
RedirectUri	The redirect URI (also known as Reply URI or Reply URL), is the URI at which Azure AD will contact back the application with the tokens	Set to defaults, or, for client applications, in the constructor.	.WithRedirectUri

MSAL.NET 3.x no longer uses SecureString

The recommendation of the .NET team is to avoid using secure strings. They are not that secure (not implemented at the OS level) and are difficult to use in managed code. If you are interested in details, look at this article: DE0001: SecureString shouldn't be used

Therefore we are changing the signature of AcquireTokenByUsernamePasswordAsync so that the password is now a plain string.

AcquireTokenByUsernamePasswordAsync(IEnumerable<string> scopes,
                                    string username,
                                    string password)

UIBehavior renamed to Prompt

The UIBehavior was used until MSAL.NET 3.x to specify, in AcquireTokenAsync (interactive) which prompt the application developer wanted to expose to the user. The class was renamed to Prompt.

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

Until MSAL.NET 3.0, you used to set the logger

New unified token cache format

```CSharp
  public interface ITokenCache {
      void Deserialize(byte[] unifiedState);                      // MSAL V2.0 format
      void DeserializeUnifiedAndAdalCache(CacheData cacheData);   // ADAL V3.0 and MSAL V3.0 format
      void DeserializeV3(byte[] bytes);                           // MSAL V3.0 unified cache format
      byte[] Serialize();                                         // MSAL V2.0 format
      CacheData SerializeUnifiedAndAdalCache();                   // ADAL V3.0 and MSAL V3.0 format
      byte[] SerializeV3();                                       // MSAL V3.0 unified cache format
      void SetAfterAccess(TokenCacheCallback afterAccess);
      void SetBeforeAccess(TokenCacheCallback beforeAccess);
      void SetBeforeWrite(TokenCacheCallback beforeWrite);
  }
```