Skip to content

README.md

Latest commit

 

History

History
285 lines (206 loc) · 13.7 KB

README.md

File metadata and controls

285 lines (206 loc) · 13.7 KB

Microsoft.Identity.Web Documentation

Microsoft.Identity.Web is a set of libraries that simplifies adding authentication and authorization support to services (confidential client applications) integrating with the Microsoft identity platform (formerly Azure AD v2.0). It supports:

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

Whether you're building 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, including the client credentials.

🚀 Quick Start

Choose your scenario:

📦 What's Included

Microsoft.Identity.Web provides:

✅ 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 ✅ Multiple Credential Types - Support for certificates, managed identities, and certificateless authentication ✅ Automatic Authorization Headers - Authentication is handled transparently when calling APIs ✅ Production-Ready - Used by thousands of Microsoft and customer applications

See NuGet Packages - Overview of all available packages and when to use them.

Calling APIs with Automatic Authentication

Microsoft.Identity.Web makes it easy to call protected APIs without manually managing tokens:

  • 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 Identity APIs - Call APIs on behalf of managed identities or service principals with automatic credential handling

Authentication headers are automatically added to your requests, and tokens are acquired and cached transparently. See the Calling Downstream APIs documentation and Daemon Applications and Agent Identities guide for complete details.

⚙️ Configuration Approaches

Microsoft.Identity.Web supports flexible configuration for all scenarios:

Configuration by File (Recommended)

All scenarios can be configured using 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 this to your .csproj:

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

Configuration by Code

You can also configure authentication programmatically:

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

Both approaches are available for all scenarios (web apps, web APIs, and daemon applications).

🎯 Core Scenarios

Web Applications

Build web apps that sign in users with work/school accounts or personal Microsoft accounts.

// In Program.cs
using Microsoft.AspNetCore.Authentication.OpenIdConnect;
using Microsoft.Identity.Web;

var builder = WebApplication.CreateBuilder(args);

// Add authentication with explicit scheme
builder.Services.AddAuthentication(OpenIdConnectDefaults.AuthenticationScheme)
    .AddMicrosoftIdentityWebApp(builder.Configuration.GetSection("AzureAd"));

builder.Services.AddRazorPages();

Learn more: Web Apps Scenario

Protected Web APIs

Secure your APIs and validate access tokens from clients.

// In Program.cs
using Microsoft.AspNetCore.Authentication.JwtBearer;
using Microsoft.Identity.Web;

var builder = WebApplication.CreateBuilder(args);

// Add authentication with explicit scheme
builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddMicrosoftIdentityWebApi(builder.Configuration.GetSection("AzureAd"));

builder.Services.AddControllers();

Learn more: Web APIs Scenario

Daemon Applications

Build background services, console apps, and autonomous agents that call APIs using application identity or agent identities.

// In Program.cs
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Identity.Abstractions;
using Microsoft.Identity.Web;

// Get the Token acquirer factory instance
var tokenAcquirerFactory = TokenAcquirerFactory.GetDefaultInstance();

// Configure downstream API
tokenAcquirerFactory.Services.AddDownstreamApi("MyApi",
    tokenAcquirerFactory.Configuration.GetSection("MyWebApi"));

var sp = tokenAcquirerFactory.Build();

// Call API - authentication is automatic
var api = sp.GetRequiredService<IDownstreamApi>();
var result = await api.GetForAppAsync<IEnumerable<MyData>>("MyApi");

Configuration (appsettings.json):

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "your-tenant-id",
    "ClientId": "your-client-id",
    "ClientCredentials": [
      {
        "SourceType": "ClientSecret",
        "ClientSecret": "your-client-secret"
      }
    ]
  },
  "MyWebApi": {
    "BaseUrl": "https://myapi.example.com/",
    "RelativePath": "api/data",
    "RequestAppToken": true,
    "Scopes": [ "api://your-api-id/.default" ]
  }
}

Note: ClientCredentials supports multiple authentication methods including certificates, Key Vault, managed identities, and certificateless authentication (FIC+MSI). See the Credentials Guide for all options.

Supported Scenarios:

  • Standard Daemon - Client credentials for app-only tokens
  • Autonomous Agents - Agent identities for app-only tokens with isolated identity.
  • Agent User Identity - Agent identities for user agent tokens without user interaction (Same thing)

⚠️ For agent scenarios, be sure to run them in a secure environment. That's a confidential client!

Learn more: Daemon Applications & Agent Identities

🏗️ Package Architecture

Microsoft.Identity.Web is composed of several NuGet packages to support different scenarios:

Package Purpose Target Frameworks
Microsoft.Identity.Web Core library for ASP.NET Core web apps .NET 6.0+, .NET Framework 4.6.2+
Microsoft.Identity.Web.TokenAcquisition Token acquisition services .NET 6.0+
Microsoft.Identity.Web.TokenCache Token cache serialization .NET Standard 2.0+
Microsoft.Identity.Web.DownstreamApi Helper for calling downstream APIs .NET 6.0+
Microsoft.Identity.Web.UI UI components for web apps .NET 6.0+
Microsoft.Identity.Web.GraphServiceClient Microsoft Graph SDK integration .NET 6.0+
Microsoft.Identity.Web.Certificate Certificate loading helpers .NET Standard 2.0+
Microsoft.Identity.Web.Certificateless Certificateless authentication .NET 6.0+
Microsoft.Identity.Web.OWIN OWIN/ASP.NET Framework support .NET Framework 4.6.2+

🔐 Authentication Credentials

Microsoft.Identity.Web supports multiple ways to authenticate your application:

Recommended for Production:

For Development:

See: Credential Decision Guide for choosing the right approach.

🌐 Supported .NET Versions

.NET Version Support Status Notes
.NET 9 ✅ Supported Latest release, recommended for new projects
.NET 8 ✅ Supported (LTS) Long-term support until November 2026
.NET 6 ⚠️ Deprecated Support ending in version 4.0.0 (use .NET 8 LTS)
.NET 7 ⚠️ Deprecated Support ending in version 4.0.0
.NET Framework 4.7.2 ✅ Supported For OWIN applications (via specific packages)
.NET Framework 4.6.2 ✅ Supported For OWIN applications (via specific packages)

Current stable version: 3.14.1 Upcoming: Version 4.0.0 will remove .NET 6.0 and .NET 7.0 support

📖 Documentation Structure

Getting Started

Scenarios

  • Web Applications - Sign-in users, call APIs
  • Web APIs - Protect APIs, call downstream services
  • Daemon Applications - Background services, autonomous agents, agent user identities
  • Agent identities for protected web APIs interpersonating agent identities or validating tokens from agent identities.

Authentication & Tokens

Advanced Topics

.NET Framework Support

🔗 External Resources

🤝 Contributing

We welcome contributions! See our Contributing Guide for details.

📄 License

This project is licensed under the MIT License. See LICENSE for details.

Need help? Start with our Quickstart Guides to find your use case and learn from there.