MSAL.NET 2.6.0 released
Since MSAL.NET 2.2.0 released, there were a number of releases improving MSAL.NET based on your feedback but the changes were mainly communicated with the release notes. With MSAL.NET 2.6.0, we are getting one step further to our goal of removing the -preview tag on MSAL.NET. We thought it was useful to update you on the progress made.
MSAL.NET supports multiple platforms. When you want to write applications working on several platforms, you will probably create a library targeting the MSAL.NET .NET Standard 1.3 platform. The problem is that, in the case of multi-target projects, the assembly actually used by .NET is different:
- at coding or build time (IDE, msbuild)
- and at runtime (CLR).
The picture below shows the case of a .NET Core application and an Android application which reference a shared code library targeting the .NET standard platform.
If you are interested in learning more about what is .NET standard, how .NET resolves platforms, what it means to build against .NET standard and what happens at runtime, read Understanding multi targetting and NetStandard.
Until MSAL.NET 2.6.0, there were differences between the public API surface exposed in different platforms (that is fine), but also with the public API of the .NET standard platform. When you were developing shared code libraries, you were hit by two kind of issues:
- The concrete platforms could have more APIs than .NET standard, which was making your life difficult: You basically had to create multi-platform projects yourself, and use conditional compilation.
- Also because the edit/build time and runtime assembly resolution is different, and the public API was different, you could get, at runtime, and on some platforms only, a
MethodNotImplementedException, whereas your code was building fine. Debugging these exceptions was also difficult as the exceptions were not actionable
With MSAL.NET 2.6.0, the public API of the .NET Standard platform was re-thought so that you can more easily build cross-platform libraries:
- The public API was introduced each time it made sense for you to use it in the .NET standard assembly.
- In the case of methods that do not make sense in some platforms, either they do nothing, or they throw a meaningful and actionable
PlatformNotSupportedException, which has an aka.ms link to MSAL.NET conceptual documentation.
The following table summarizes the cases when you can have a PlatformNotSupportedException if you have use a particular API in a .NET standard 1.3 application, depending on the actual platform for the app.
| If you attempt to use at runtime | in an app of the following plaforms | you'll get a PlatformNotSupportedException with the following message |
|---|---|---|
| any confidential client API (ConfidentialClientApplication, ClientCredential, ClientAssertionCertificate | Xamarin.iOS, Xamarin.Android, UWP | Confidential Client flows are not available on mobile platforms. See https://aka.ms/msal-net-confidential-availability for details |
| IWA* | non-Windows platforms (iOS, Android) | Integrated Windows Authentication is not supported on this platform. For details about this authentication flow, please see https://aka.ms/msal-net-iwa" |
| The overload of IWA* without username | .NET Core | This overload of AcquireTokenByIntegratedWindowsAuthAsync is not suppored on .net core because MSAL cannot determine the username (UPN) of the currently logged in user. Please use the overload where you pass in a username (UPN). For more details see https://aka.ms/msal-net-iwa |
| The constructor of PublicClientApplication taking a TokenCache parameter | Xamarin.iOS, Xamarin.Android, UWP | You should not use this constructor that takes in a TokenCache object on mobile platforms. This constructor is meant to allow applications to define their own storage strategy on .net desktop and .net core. On mobile platforms, a secure and performant storage mechanism is implemeted by MSAL. For more details about custom token cache serialization, visit https://aka.ms/msal-net-serialization |
| The methods enabling customization of token cache serialization | Xamarin.iOS, Xamarin.Android, UWP | You should not use these TokenCache methods object on mobile platforms. They meant to allow applications to define their own storage strategy on .net desktop and .net core. On mobile platforms, a secure and performant storage mechanism is implemeted by MSAL. For more details about custom token cache serialization, visit https://aka.ms/msal-net-serialization |
| Any constructor of UIParent | .NET Core | Interactive Authentication flows are not supported on .net core. Consider using Device Code Flow https://aka.ms/msal-device-code-flow or Integrated Windows Auth https://aka.ms/msal-net-iwa |
In some cases, the .NET standard 1.3 assembly can also be used at runtime. This is for instance the case if the application you are building is for a platform that MSAL.NET does not support explicitly. In that case things will mostly work fine except for this API:
| If you attempt to use at runtime | in an app of non-explicitly supported platform (therefore defaulting to .NET Standard 1.3 runtime) | you'll get a PlatformNotSupportedException with the following message |
|---|---|---|
| Constructor of UIParent | .NET Core | Interactive Authentication flows are not supported on .net core. Consider using Device Code Flow https://aka.ms/msal-device-code-flow or Integrated Windows Auth https://aka.ms/msal-net-iwa" |
(*) IWA = AcquireTokenByIntegratedWindowsAuthAsync (abbreviated so that the table keeps being readable)
The MSAL.NET nuget package also now contains, in addition to platform assemblies (let's say implementation assemblies, the ones used at runtime) a set of corresponding reference assemblies, which are used at edit and build time. Think of reference assemblies as kind of interface assemblies: they have the .NET metadata, but not the IL body.