We’re excited to announce that Microsoft.Identity.Web is now generally available. Microsoft.Identity.Web brings a renewed, simplified, end-to-end experience for developers to build secured-by-default web apps or web APIs, possibly calling Microsoft Graph or other web APIs.
Building ASP.NET Core web apps or web APIs using the Microsoft identity platform used to require a lot of effort and domain and technical knowledge. Although the Microsoft identity platform provides the basic building blocks to build ASP.NET Core web apps or web APIs with Identity.Model (middleware) and MSAL.NET (to acquire tokens), the task of doing so is challenging. In the past, customers often tried to glue together ASP.NET Core, middleware, and MSAL.NET and often got it wrong, resulting in a poor customer experience, lack of app/API reliability, and security vulnerabilities.
Today, when you use the ASP.NET Core 3.1 templates or the “File > New project” experience in Visual Studio, you create web apps or web APIs that target the Azure AD v1.0 endpoint. These apps are not secured by default: there is no support for issuer validation in multi-tenant apps, no validation of scope/roles in web APIs, and you have to write your own logic to use client certificates or decrypt certificates. Also, the developer experience is different between Azure AD and Azure AD B2C, and using external identities was incompatible with other identity providers.
Microsoft.Identity.Web provides an API with a pay as you go learning curve, making simple things simple and more complex scenarios possible, while enabling you to create web apps that sign-in users and create protected web APIs. Developers can incrementally add calls to Microsoft Graph or other web APIs. Microsoft.Identity.Web also provides project templates for web APIs and web apps, including MVC, Razor, and Blazor.
The NuGet packages
Microsoft.Identity.Web is released on NuGet.org as a set of NuGet packages:
- Identity.Web which is the main API.
- Identity.Web.UI brings the button to sign in and sign out users and handle some B2C experiences. It includes the challenge mechanism that enables the library to automatically handle incremental consent and conditional access. The UI is customizable.
- Identity.Web.MicrosoftGraph exposes the Microsoft Graph SDK for .NET, GraphServiceClient, so that it’s used in your controllers.
- Identity.Web.MicrosoftGraphBeta exposes the Microsoft Graph SDK beta for .NET (corresponding to the Microsoft Graph Beta endpoint).
Quickstarts, tutorials, and samples
Several quickstarts, tutorials, and samples now use Microsoft.Identity.Web:
- Quickstarts for ASP.NET Core web apps and web APIs. A bit more work is required to add the web API quickstart to the portal.
- Web apps, web APIs, daemon app calling a web API incremental tutorials, and a Blazor Server tutorial
The scenario articles on docs.microsoft.com were also updated, and more is coming as we migrate the wiki to docs.microsoft.com.
ASP.NET in 5.0
If you’ve installed the ASP.NET Core 5 SDK preview and create a Web App or Web API project, then by default you’ll be using Microsoft.Identity.Web and the new project templates. .NET 5.0 will GA in November.
ASP.NET Core 3.1 templates
If you still use .NET Core 3.1, you can get the same project templates from NuGet. See https://aka.ms/ms-id-web/webapp-project-templates and https://aka.ms/ms-id-web/webapi-project-templates for details. The picture below shows the .NET CLI commands to use depending on your scenario:
The public API
If you’re not creating your project with the project templates, for instance if you want to add authentication with Microsoft to an existing ASP.NET Core web app or API, you can do so in 3 steps:
- Update a configuration file to match the app registration according to your scenario.
2. Update the cs file to configure services appropriate for your scenario.
3. Update your controllers or Razor pages to validate scopes (in web APIs), or use Microsoft Graph or the downstream API helper to call a downstream API. The example below shows the code used to call Microsoft Graph.
– Please reach out to the Microsoft.Identity.Web repository, with any feedback or questions.