Overview of Microsoft Identity Web

Microsoft.Identity.Web is a set of libraries that simplifies adding authentication and authorization to applications that integrate with the Microsoft identity platform, including Microsoft Entra ID. It supports:

  • .NET Aspire distributed applications
  • ASP.NET Core web applications and web APIs
  • OWIN applications on .NET Framework
  • .NET daemon applications and background services

Whether you build web apps that sign in users, web APIs that validate tokens, or background services that call protected APIs, Microsoft.Identity.Web handles the authentication complexity for you.

Why use Microsoft Identity Web?

Microsoft.Identity.Web reduces boilerplate code and provides built-in best practices for common identity scenarios. Key capabilities include:

  • Simplified authentication - Minimal configuration for signing in users and validating tokens
  • Downstream API calls - Call Microsoft Graph, Azure SDKs, or your own protected APIs with automatic token management
    • Token acquisition - Acquire tokens on behalf of users or your application
    • Token cache management - Distributed cache support with Redis, SQL Server, Cosmos DB, and PostgreSQL
  • Multiple credential types - Support for certificates, managed identities, and certificateless authentication
  • Automatic authorization headers - Authentication is handled transparently when calling APIs

See NuGet packages for an overview of all available packages and when to use them.

Call APIs with automatic authentication

You can call protected APIs without manually managing tokens. Microsoft.Identity.Web supports the following integration patterns:

  • Microsoft Graph - Use GraphServiceClient with automatic token acquisition
  • Azure SDKs - Use TokenCredential implementations that integrate with Microsoft.Identity.Web
  • Your own APIs - Use IDownstreamApi or IAuthorizationHeaderProvider for seamless API calls
  • Agent identities - Call APIs on behalf of managed identities or service principals with automatic credential handling

Authentication headers are added to your requests automatically, and tokens are acquired and cached transparently. For details, see Calling downstream APIs, Daemon applications, and the Agent identities guide.

Configuration approaches

You can configure Microsoft.Identity.Web through settings files or programmatically. Both approaches support all authentication scenarios.

Configure authentication in appsettings.json:

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "your-tenant-id",
    "ClientId": "your-client-id"
  }
}

Important

For daemon apps and console applications, ensure your appsettings.json file is copied to the output directory. In Visual Studio, set the Copy to Output Directory property to Copy if newer or Copy always, or add the following to your .csproj:

<ItemGroup>
  <None Update="appsettings.json">
    <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
  </None>
</ItemGroup>

Configuration by code

Alternatively, configure authentication directly in your application startup code:

builder.Services.AddAuthentication(OpenIdConnectDefaults.AuthenticationScheme)
    .AddMicrosoftIdentityWebApp(options =>
    {
        options.Instance = "https://login.microsoftonline.com/";
        options.TenantId = "your-tenant-id";
        options.ClientId = "your-client-id";
    });

Next steps

Choose the scenario that matches your application:

  • Last updated on