Skip to content
jennyf19 edited this page Jun 23, 2022 · 99 revisions

Getting started with Microsoft Identity Web

Token cache serialization

Web apps

Web APIs

Daemon scenario

Advanced topics




Other resources

Clone this wiki locally

Microsoft Identity Web is a library which contains a set of reusable classes used in conjunction with ASP.NET Core for integrating with the Microsoft identity platform (formerly Azure AD v2.0 endpoint) and AAD B2C.

This library is for specific usage with:

Conceptual documentation

Conceptual documentation

Getting started with Microsoft Identity Web

See Why use Microsoft.Identity.Web? ?

Microsoft.Identity.Web NuGet package

Microsoft.Identity.Web is available as a NuGet package (Microsoft.Identity.Web) for .NET Core 3.1 and .NET 5.0 (preview). Web apps can also use the (Microsoft.Identity.Web.UI) NuGet package

ASP .NET Core web app and web API project templates

You can create new web apps and web APIs using the Microsoft identity platform (formerly Azure AD v2.0) or Azure AD B2C, and leveraging Microsoft.Identity.Web. For this:

  • Build and install the Nuget package containing these project templates.
  • use the following dotnet new commands.

Audience: users to sign-in:

  • AAD = Work or School accounts
  • MSA = Personal Microsoft accounts
  • B2C = Social accounts or local accounts (Azure AD B2C)
Application Audience Dotnet new command
Web API AAD - single tenant dotnet new webapi2 --auth SingleAuth
Web API B2C dotnet new webapi2 --auth IndividualB2C
Razor Web app AAD - single tenant dotnet new webapp2 --auth SingleOrg
Razor Web app AAD + MSA dotnet new webapp2 --auth MultiOrg
Razor Web app B2C dotnet new webapp2 --auth IndividualB2C
MVC Web app AAD - single tenant dotnet new mvc2 --auth SingleOrg
MVC Web app AAD + MSA dotnet new mvc2 --auth MultiOrg
MVC Web app B2C dotnet new mvc2 --auth IndividualB2C

For details see Web app templates and Web API templates.


Date Release Blog post Main features
(Not Started) Microsoft Identity Web vFuture
(Next/In progress) See milestones
Releases All releases
June 22nd 1.25.1 IIdentityLogger support, bug fixes.
June 3rd 1.25.0 RequiredScopeOrAppPermissionAttribute support, bug fixes.
April 26th 1.24.1 Bug fixes.
April 23rd 1.24.0 Certless auth support.
March 23rd 1.23.1 Bug fixes.
Feb 14th 1.23.0 Hybrid spa support and update to MSAL.NET 4.41.
Jan 30th 1.22.2 Bug fixes.
Jan 7th 1.22.1 Update to MSAL.NET 4.40.
Jan 7th 1.22.0 Ability to set request headers in IDownstreamWebApi, proof of concept for MSI, cache improvements.
Dec 3rd 1.21.1 Dependent packages updates.
Nov 19th 1.21.0 Bug fixes and support long running process for OBO.
Nov 4th 1.20.0 Update to Microsoft.IdentityModel.Validators 6.14.1, provide MemoryCacheOptions for InMemoryCache on .NET Framework.
Nov 1st 1.19.0 Release with AadIssuerValidator package from Microsoft.IdentityModel and support for authentication handlers outside JwtBearer.
Oct 6th 1.19.0-preview Release with MSAL.NET 4.36.0-preview, which has cache improvements.
Oct 5th 1.18.0 Change RequiredScope to be based on policies and bug fixes.
Sept 20th 1.17.0 Publish Microsoft.Identity.Web.TokenCache and Microsoft.Identity.Web.Certificate for ASP.NET Framework and .NET Core apps. See package dependencies for more info.
Sept 6th 1.16.1 Bug fixes
Aug 18th 1.16.0 DisableL1Cache option, OIDC provider DisplayName, bug fixes
July 30th 1.15.2 Bug fixes
July 26th 1.15.1 encryption strategy for the Distributed token cache, delegating handler for token acquisition
July 15th 1.14.1 Bug fixes, stress improvement in daemon apps
June 23rd 1.14.0 Improve cache extensions for net framework, support long running process with OBO, include backup authentication system routing hint on calls to AAD.
June 15th 1.13.1 Fix regression from 1.12 with LegacyCacheCompatibilityEnabled.
June 11th 1.13.0
June 2nd 1.12.0
May 1.11.0 Support for multiple authentication schemes.
May 17th 1.10.0 Help rotating client certificates (especially when the certificate description points to KeyVault).
May 4th 2021 1.9.2 Support for PKCE + bug fixes.
April 14th 2021 1.9.1 Bug fixes and work-arounding a breaking change in a dependency.
April 12th 2021 1.9.0 blog post Perf improvements, support for NET Framework 4.6.2, support for Regional STS, Azure SDKs, client capabilities.
March 23th 2021 1.8.2 Update to MSAL 4.28.1.
March 16th 2021 1.8.1 Bug fix for refreshing the L2 cache when an cached item is found in the L1 cache.
March 10th 2021 1.8.0 Provides a more performant L1/L2 token cache, exposes options for L1 cache, improved L2 cache failure scenarios, supports assigned managed identity for certificate loading.
Feb 27th 2021 1.7.0 Release of msidentity-app-sync tool, disable ADAL cache lookup by default, X509KeyStorageFlags can be specified, remove obsolete attribute from ValidateUserScopesAndAppRoles.
Feb 12th 2021 1.6.0 blog post Simplification of the API, support for decrypt certificate rotation, support and project templates for Azure functions and gRPC services, performance improvement of GetTokenForApp, and update to MSAL.NET 4.26.0
Jan 21th 2021 1.5.1 Update to the latest version of MSAL .NET (4.25), Microsoft Graph (3.22) and Microsoft Graph Beta (0.36.0-preview)
Jan 20th 2021 1.5.0 See release notes for details. Support for Azure functions and gRPC. Update of the project templates (adding gRPC and use
Dec 15th 2020 1.4.1 See release notes for details. MSAL.NET logs are now surfaced. See Logging
Dec 9th 2020 1.4.0 See release notes for details. See Minimal support for ASP.NET
Nov 11th 2020 1.3.0 See release notes for details.
Oct 23rd 2020 1.2.0 1.2.0 article Scopes and app-permissions for Microsoft Graph, Comfort methods for IDownstreamAPI, Support for App Services Authentication, Support for Ajax calls in Web APIs, For web APIs protected by ACLS, for back channel proxys, and bug fixes
Oct 8th 2020 1.1.0 1.1.0 Improvement to the blazorwasm hosted template, bug fixes
September 30th 2020 1.0.0 1.0.0 (GA) Features and bug fixes.
September 11th 2020 0.4.0-preview See release notes for details.
August 27th 2020 0.3.1-preview See release notes for details.
August 25th, 2020 0.3.0-preview 0.3.0-preview See for specific details. See release notes for more info.
August 10th, 2020 0.2.3-preview 0.2.3-preview ReplyForbiddenWithWwwAuthenticateHeaderAsync has an additional optional HttpResponse parameters. Microsoft.Identity.Web works for .NET 5.0.0-* (including Preview 8). See release notes for details.
August 7th, 2020 0.2.2-preview 0.2.2-preview AadIssuerValidator exposed publicly (to be used in Azure Functions), MicrosoftIdentityConsentAndConditionalAccessHandler can now take an httpContextAccessor, and exposes BaseUri and User. Bug fixes. See release notes for details.
July 24th, 2020 0.2.1-preview 0.2.1-preview Blazor support and token acquisition stability improvements, Blazor templates support, allow specifying B2C user flow for token acquisition calls. See release notes for details.
July 13th, 2020 0.2.0-preview Blog post for 0.2.0-preview Simplification, support for .NET 5, validation of roles in Web APIs called from daemons. See release notes for details.
June 16th, 2020 0.1.5-preview 0.1.5-preview Support for client and token decryption certificates, use System.Text.Json instead of Newtonsoft.Json, add ForceHttpsRedirectUris option. See release notes for details.
June 1st, 2020 0.1.4-preview 0.1.4-preview Support token acquisition service as a singleton, fix redirect with an unauthorized account, use user_info for guest accounts. See release notes for details.
May 15th, 2020 0.1.3-preview 0.1.3-preview Sign-in without passing in scopes is supported, specify the redirectUri and postLogoutRedirectUri, bug fixes. See release notes for details.
May 7th, 2020 0.1.2-preview 0.1.2-preview Performance improvements (HttpClientFactory, issuer cache, better error message when the client secret is missing) and bug fixes. See release notes for details.
April 22th, 2020 0.1.1-preview 0.1.1-preview Surface ClaimsConstants class and bug fixes. See release notes for details.
April 13th, 2020 0.1.0-preview Documentation First preview NuGet package.

For previous, or intermediate releases, see releases. See also Semantic versioning - API change management to understand changes in Microsoft Identity Web public API, and Microsoft Identity Web Release Cadence to understand when Microsoft Identity Web is released.


Web App Samples

To see Microsoft Identity Web in action, or learn how to sign-in users with a web app and call a protected web API, use this incremental tutorial on ASP .NET Core web apps which signs-in users (including in your org, many orgs, orgs + personal accounts, sovereign clouds) and calls web APIs (including Microsoft Graph), while leveraging Microsoft Identity Web. See the incremental tutorial.

Web API Samples

To secure web APIs and call downstream web APIs, use this ASP .NET Core incremental tutorial.