Demystifying Microsoft Identity SDKs

Over time, the needs of identity platform and community have evolved and with that the needs for the SDKs developers need have also evolved. Here I will try to demystify and provide a 30,000 foot view of the various SDKs Microsoft has, and hopefully add some clarity.

The first thing you need to know is the concept of v1 endpoint vs. v2 endpoint. V1 is older of course, but v2 is OIDC compliant. And our newer SDKs (and recommended path) is to target the newer v2 endpoint. Why is that important?

Because the older library, ADAL (Microsoft.IdentityModel.Clients.ActiveDirectory) targets the v1 endpoint. In fact, ADAL is being deprecated. Your existing ADAL apps will not stop working, but starting June 30th, 2020, Microsoft is not adding any new features to ADAL. You should strongly consider updating to MSAL.

But then we have many other libraries, AppAuth, Azure.Identity, Microsoft.Identity.Web, where do they fit in?

Microsoft.Azure.Services.AppAuthentication enables S2S communication using OAuth 2.0 client credentials grant, and it depends on ADAL. Since it depends on ADAL, you should consider moving away from it.

Azure.Identity is great for using Managed Identity and is available not just for .NET but many platforms, in a very similar and well thought out programming paradigm. Managed Identity is a service principal whose credentials you don’t have to manage, and it does not have a backing app registration. You must always prefer to use a MI, vs. a SP whose credential you have to manage. There are still borderline scenarios where SP with a known credential is necessary but those are far and few in between. Azure.Identity, takes a dependency on MSAL. It is worth mentioning that both MI and SP target app permissions, and .default scope is a convenient shorthand for requesting all scopes your app is pre-consented to. So you would generally use MI/SP with a scope such as https://graph.microsoft.com/.default

MSAL.NET or Microsoft.Identity.Client is the .NET version of the Microsoft authentication library, and it targets the v2 endpoint. You should use this. In fact, there is a family of platform specific MSALs

Microsoft.Identity.Web is a higher level abstraction on top of MSAL, which makes using common identity scenarios in ASPNET a whole lot easier. Now this raises an interesting question. When should I use Microsoft.Identity.Web and when should I use MSAL.NET directly? I am going to steal this amazing flowchart, but also encourage you to read this article here.

One last thought,

1. You should always prefer to use a Microsoft SDK if available for a platform
2. If a SDK is not available, you should prefer to use a standard OIDC complaint SDK
3. And finally, as a last resort, you should target the OIDC spec.

Hope this helps.