Home - mattchenderson/microsoft-identity-web GitHub Wiki
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:
- Web applications, which sign in users and, optionally, call web APIs
- Protected web APIs, which optionally call protected downstream web APIs
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 newcommands.
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.
Roadmap
| Date | Release | Blog post | Main features |
|---|---|---|---|
| (Not Started) | Microsoft Identity Web vFuture | ||
| (Next/In progress) | See milestones | ||
| Releases | All releases | ||
| 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 ccs 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 b2clogin.com). | |
| 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 https://aka.ms/ms-id-web/0.3.0-preview 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.
Samples
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 app which signs in users
- Web app which signs in users and calls Graph
- Web app which signs in users and calls multiple web APIs
- See the incremental tutorial for even more samples, including B2C.
Web API Samples
To secure web APIs and call downstream web APIs, use this ASP .NET Core incremental tutorial.