### Start Server

Source: https://github.com/azuread/microsoft-identity-web/blob/master/tests/DevApps/SidecarAdapter/typescript/README.md

Use this command to start the development server for the application.

```sh
npm run start
```

--------------------------------

### Setup Azure SDK Integration

Source: https://github.com/azuread/microsoft-identity-web/blob/master/docs/calling-downstream-apis/from-web-apps.md

Install necessary packages and register the MicrosoftIdentityTokenCredential for Azure service authentication.

```bash
dotnet add package Microsoft.Identity.Web.Azure
dotnet add package Azure.Storage.Blobs
```

```csharp
using Microsoft.Identity.Web;

builder.Services.AddAuthentication(OpenIdConnectDefaults.AuthenticationScheme)
    .AddMicrosoftIdentityWebApp(builder.Configuration.GetSection("AzureAd"))
    .EnableTokenAcquisitionToCallDownstreamApi()
    .AddInMemoryTokenCaches();

// Add Azure token credential
builder.Services.AddMicrosoftIdentityAzureTokenCredential();
```

--------------------------------

### Setup Microsoft Graph Integration

Source: https://github.com/azuread/microsoft-identity-web/blob/master/docs/calling-downstream-apis/from-web-apps.md

Install the required NuGet package and configure the GraphServiceClient in the application startup.

```bash
dotnet add package Microsoft.Identity.Web.GraphServiceClient
```

```csharp
// Startup configuration
builder.Services.AddAuthentication(OpenIdConnectDefaults.AuthenticationScheme)
    .AddMicrosoftIdentityWebApp(builder.Configuration.GetSection("AzureAd"))
    .EnableTokenAcquisitionToCallDownstreamApi()
    .AddMicrosoftGraph(options =>
    {
        options.Scopes = "user.read mail.read";
    })
    .AddInMemoryTokenCaches();
```

--------------------------------

### Verify tool installation

Source: https://github.com/azuread/microsoft-identity-web/blob/master/tools/app-provisioning-tool/vs2019-16.9-how-to-use.md

Lists installed .NET tools to confirm that msidentity-app-sync is correctly configured.

```bash
dotnet tool list -g
```

--------------------------------

### Install Dependencies

Source: https://github.com/azuread/microsoft-identity-web/blob/master/tests/DevApps/SidecarAdapter/typescript/README.md

Run this command in your terminal to install all necessary project dependencies.

```sh
npm install
```

--------------------------------

### Install Microsoft.Identity.Web packages

Source: https://github.com/azuread/microsoft-identity-web/blob/master/docs/frameworks/msal-dotnet-framework.md

Use these commands to install the necessary packages for token cache serialization and certificate management.

```powershell
# Token cache serialization
Install-Package Microsoft.Identity.Web.TokenCache

# Certificate management
Install-Package Microsoft.Identity.Web.Certificate
```

```bash
dotnet add package Microsoft.Identity.Web.TokenCache
dotnet add package Microsoft.Identity.Web.Certificate
```

--------------------------------

### Build and install templates from repository

Source: https://github.com/azuread/microsoft-identity-web/wiki/Web-API-Template

Builds the project templates locally from the cloned repository and installs the resulting NuGet package.

```Shell
dotnet pack /p:ClientSemVer=1.8.2
cd ProjectTemplates
cd bin
cd Debug
dotnet new -i Microsoft.Identity.Web.ProjectTemplates.1.4.0.nupkg
```

--------------------------------

### Daemon Application Example with Azure SDK

Source: https://github.com/azuread/microsoft-identity-web/blob/master/docs/calling-downstream-apis/azure-sdks.md

This C# example demonstrates setting up a service provider and using MicrosoftIdentityTokenCredential to authenticate with Azure Blob Storage in a daemon application. Ensure you have the necessary Microsoft.Extensions.DependencyInjection, Microsoft.Identity.Abstractions, Microsoft.Identity.Web, and Azure.Storage.Blobs NuGet packages installed.

```csharp
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Identity.Abstractions;
using Microsoft.Identity.Web;
using Azure.Storage.Blobs;

class Program
{
    static async Task Main(string[] args)
    {
        // Build service provider
        var tokenAcquirerFactory = TokenAcquirerFactory.GetDefaultInstance();
        tokenAcquirerFactory.Services.AddMicrosoftIdentityAzureTokenCredential();
        var sp = tokenAcquirerFactory.Build();
        
        // Get credential
        var credential = sp.GetRequiredService<MicrosoftIdentityTokenCredential>();
        credential.Options.RequestAppToken = true;
        
        // Use with Azure SDK
        var blobClient = new BlobServiceClient(
            new Uri("https://myaccount.blob.core.windows.net"),
            credential);
        
        var container = blobClient.GetBlobContainerClient("data");
        
        await foreach (var blob in container.GetBlobsAsync())
        {
            Console.WriteLine($"Blob: {blob.Name}");
        }
    }
}
```

--------------------------------

### Build and Install msidentity-app-sync from Repository

Source: https://github.com/azuread/microsoft-identity-web/blob/master/tools/app-provisioning-tool/README.md

Installs the msidentity-app-sync tool globally after cloning the repository, building the project, and packing it. This method is useful for development or when using a specific version from the source.

```Shell
git clone https://github.com/AzureAD/microsoft-identity-web
cd tools\app-provisioning-tool
dotnet pack
dotnet tool install --global --add-source app-provisioning-tool\nupkg msidentity-app-sync
```

--------------------------------

### Install Microsoft.Identity.Web and Microsoft.Extensions.Hosting

Source: https://github.com/azuread/microsoft-identity-web/blob/master/docs/getting-started/daemon-app.md

Use the dotnet CLI to add the necessary packages for Microsoft.Identity.Web and hosting capabilities.

```bash
dotnet add package Microsoft.Identity.Web
dotnet add package Microsoft.Extensions.Hosting
```

--------------------------------

### Build and Install msidentity-app-sync from Repository

Source: https://github.com/azuread/microsoft-identity-web/blob/master/tools/README.md

Builds, packs, and installs the msidentity-app-sync .NET CLI tool locally from the source repository. This is useful for development or testing the tool directly.

```bash
cd tools/app-provisioning-tool
dotnet build
dotnet pack
dotnet tool install --global --add-source ./app-provisioning-tool/bin/Debug msidentity-app-sync
```

--------------------------------

### Install msidentity-app-sync tool

Source: https://github.com/azuread/microsoft-identity-web/blob/master/tools/app-provisioning-tool/vs2019-16.9-how-to-use.md

Installs the global .NET tool required for automating Azure AD application registration and project configuration.

```bash
dotnet tool install -g msidentity-app-sync
```

--------------------------------

### Build and Install .NET Core Templates from Repository

Source: https://github.com/azuread/microsoft-identity-web/wiki/Web-App-Template

Builds the project templates from the Microsoft.Identity.Web repository and installs them locally. This involves cloning the repo, packing the project, and then installing the generated NuGet package.

```Shell
dotnet pack /p:ClientSemVer=1.15.2
cd ProjectTemplates
cd bin
cd Debug
dotnet new -i Microsoft.Identity.Web.ProjectTemplates.1.15.2.nupkg
```

--------------------------------

### Install Microsoft.Identity.Web.Azure Package

Source: https://github.com/azuread/microsoft-identity-web/blob/master/README-Azure.md

Use the dotnet CLI to add the Microsoft.Identity.Web.Azure package to your project.

```sh
dotnet add package Microsoft.Identity.Web.Azure
```

--------------------------------

### Install Microsoft.Identity.Web.OWIN via Package Manager Console

Source: https://github.com/azuread/microsoft-identity-web/blob/master/docs/frameworks/owin.md

Use this command in the Package Manager Console to install the Microsoft.Identity.Web.OWIN NuGet package.

```powershell
Install-Package Microsoft.Identity.Web.OWIN
```

--------------------------------

### Install .NET Core Templates from NuGet

Source: https://github.com/azuread/microsoft-identity-web/wiki/Web-App-Template

Installs the Microsoft.Identity.Web.ProjectTemplates NuGet package to make project templates available for use with the `dotnet new` command.

```Shell
dotnet new -i Microsoft.Identity.Web.ProjectTemplates::1.15.2
```

--------------------------------

### Install msidentity-app-sync CLI Tool

Source: https://github.com/azuread/microsoft-identity-web/blob/master/tools/README.md

Installs the msidentity-app-sync .NET CLI tool globally from NuGet. This tool automates Azure AD app registration and ASP.NET Core configuration.

```bash
dotnet tool install --global msidentity-app-sync
```

--------------------------------

### Configure Certificate and Secret Fallback

Source: https://github.com/azuread/microsoft-identity-web/blob/master/docs/authentication/credentials/client-secrets.md

Example configuration for transitioning from client secrets to certificate-based authentication.

```json
{
  "AzureAd": {
    "ClientCredentials": [
      {
        "SourceType": "KeyVault",
        "KeyVaultUrl": "https://keyvault.vault.azure.net",
        "KeyVaultCertificateName": "ProductionCert"
      },
      {
        "SourceType": "ClientSecret",
        "ClientSecret": "fallback-secret"
      }
    ]
  }
}
```

--------------------------------

### Configure OWIN Implementation

Source: https://github.com/azuread/microsoft-identity-web/blob/master/docs/calling-downstream-apis/custom-apis.md

Setup Microsoft Identity Web in an OWIN-based application.

```csharp
using Microsoft.Identity.Web;
using Microsoft.Identity.Web.OWIN;
using Owin;

public class Startup
{
    public void Configuration(IAppBuilder app)
    {
      OwinTokenAcquirerFactory factory = TokenAcquirerFactory.GetDefaultInstance<OwinTokenAcquirerFactory>();

      app.AddMicrosoftIdentityWebApp(factory);
      factory.Services
        .AddDownstreamApis(factory.Configuration.GetSection("DownstreamAPI"))
        .AddInMemoryTokenCaches();
        factory.Build();
    }
}
```

--------------------------------

### Environment-Specific Configuration (Development)

Source: https://github.com/azuread/microsoft-identity-web/blob/master/docs/advanced/logging.md

Example of appsettings.Development.json to enable Debug logging for Microsoft.Identity and PII logging.

```json
{
  "Logging": {
    "LogLevel": {
      "Microsoft.Identity": "Debug"
    }
  },
  "AzureAd": {
    "EnablePiiLogging": true
  }
}
```

--------------------------------

### Install .NET Core Dependencies

Source: https://github.com/azuread/microsoft-identity-web/blob/master/tests/DevApps/blazorserver-calls-api/README-Incremental.md

Run these commands in the respective project directories to restore .NET Core dependencies.

```console
cd Client
dotnet restore
```

```console
cd Service
dotnet restore
```

--------------------------------

### Configure Environment and Build Environment

Source: https://github.com/azuread/microsoft-identity-web/blob/master/TESTING.md

Commands to set up the repository environment and build the solution.

```batch
cd C:\
git clone https://github.com/AzureAD/microsoft-identity-web idweb
```

```batch
Set MicrosoftIdentityWebVersion=2.4.0
```

```batch
dotnet build Microsoft.Identity.Web.sln
```

--------------------------------

### Create a new Aspire project

Source: https://github.com/azuread/microsoft-identity-web/blob/master/docs/frameworks/aspire.md

Initializes a new .NET Aspire starter project using the CLI.

```sh
aspire new aspire-starter --name MyService
```

--------------------------------

### Protect Controller Actions with RequiredScope Attribute

Source: https://github.com/azuread/microsoft-identity-web/blob/master/docs/authentication/authorization.md

Apply the [Authorize] and [RequiredScope] attributes to controllers or actions to enforce specific scopes for access. The example shows how to protect a GET endpoint.

```csharp
using Microsoft.AspNetCore.Authorization;
using Microsoft.Identity.Web.Resource;

[Authorize]
[RequiredScope("access_as_user")]
public class TodoListController : ControllerBase
{
    [HttpGet]
    public IActionResult GetTodos()
    {
        // Only accessible if token has "access_as_user" scope
        return Ok(new[] { "Todo 1", "Todo 2" });
    }
}
```

--------------------------------

### Get Access Token for App (C#)

Source: https://github.com/azuread/microsoft-identity-web/wiki/daemon-scenarios

Use this method to obtain an access token for an application's own identity. The scope parameter must be the resource identifier with the '.default' suffix. The optional tenant parameter should be a GUID or domain name for specific tenant access.

```CSharp
public async Task<string> ITokenAcquisition.GetAccessTokenForAppAsync(string scope, string? tenant = null)
```

--------------------------------

### Clone and Run ASP.NET OpenID Connect Sample

Source: https://github.com/azuread/microsoft-identity-web/blob/master/docs/frameworks/owin.md

Instructions to clone a sample ASP.NET MVC application using Microsoft.Identity.Web.OWIN and run it after updating configuration.

```bash
git clone https://github.com/Azure-Samples/ms-identity-aspnet-webapp-openidconnect
cd ms-identity-aspnet-webapp-openidconnect
# Update Web.config with your Azure AD app registration
# Run in Visual Studio
```

--------------------------------

### Initialize project with dotnet new

Source: https://github.com/azuread/microsoft-identity-web/blob/master/tools/app-provisioning-tool/README.md

Use this command to create a new web application project template configured for authentication.

```text
dotnet new <template> --auth <authOption> [--calls-graph] [--called-api-url <URI> --called-api-scopes <scopes>]
```

--------------------------------

### Program.cs setup for token acquisition and downstream APIs

Source: https://github.com/azuread/microsoft-identity-web/wiki/generic-api

Configure services for token acquisition and register downstream APIs dynamically from appsettings.json in Program.cs.

```csharp
// Enable the token acquisition
builder.Services.AddTokenAcquisition();
builder.Services.AddInMemoryTokenCaches();
```

```csharp
// Read the web APIs from the appsettings.json
Dictionary<string, DownstreamApiOptions> downstreamApiOptions = new Dictionary<string, DownstreamApiOptions>();
builder.Configuration.GetSection("DownstreamApis").Bind(downstreamApiOptions);
foreach (var options in downstreamApiOptions)
{
  builder.Services.AddDownstreamApi(options.Key, 
                                    builder.Configuration.GetSection($"DownstreamApis:{options.Key}"));
}
```

```csharp
using Microsoft.AspNetCore.Authentication.JwtBearer;
using Microsoft.Identity.Abstractions;
using Microsoft.Identity.Web;
using Microsoft.Identity.Web.TokenCacheProviders.InMemory;

var builder = WebApplication.CreateBuilder(args);

// Add services to validate the tokens
builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddMicrosoftIdentityWebApi(builder.Configuration.GetSection("AzureAd"));

// Enable the token acquisition
builder.Services.AddTokenAcquisition();
builder.Services.AddInMemoryTokenCaches();

// Read the web APIs from the appsettings.json
Dictionary<string, DownstreamApiOptions> downstreamApiOptions = new Dictionary<string, DownstreamApiOptions>();
builder.Configuration.GetSection("DownstreamApis").Bind(downstreamApiOptions);
foreach (var options in downstreamApiOptions)
{
    builder.Services.AddDownstreamApi(options.Key,
                                      builder.Configuration.GetSection($"DownstreamApis:{options.Key}"));
}

builder.Services.AddControllers();
// Learn more about configuring Swagger/OpenAPI at https://aka.ms/aspnetcore/swashbuckle
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

app.UseHttpsRedirection();

app.UseAuthorization();

app.MapControllers();

app.Run();
```

--------------------------------

### Create client web app via CLI

Source: https://github.com/azuread/microsoft-identity-web/blob/master/tests/DevApps/B2CWebAppCallsWebApi/README.md

Initialize a new MVC project with SingleOrg authentication using the .NET CLI.

```Sh
md TodoListClient
cd TodoListClient
dotnet new mvc --auth SingleOrg --client-id <Enter_the_Application_Id_here> --tenant-id <yourTenantId>
```

--------------------------------

### Install templates from NuGet

Source: https://github.com/azuread/microsoft-identity-web/wiki/Web-API-Template

Installs the Microsoft Identity Web project templates from NuGet.org.

```Shell
dotnet new -i Microsoft.Identity.Web.ProjectTemplates::1.8.2
```

--------------------------------

### User-Assigned Managed Identity Example

Source: https://github.com/azuread/microsoft-identity-web/blob/master/docs/authentication/credentials/certificateless.md

Example of a subject identifier for a user-assigned managed identity.

```plaintext
microsoft:azure:managed-identity:12345678-1234-1234-1234-123456789012:my-resource-group:my-identity
```

--------------------------------

### Configure Multiple Authentication Schemes in Startup.cs

Source: https://github.com/azuread/microsoft-identity-web/wiki/Multiple-Authentication-Schemes

In Startup.cs, configure multiple authentication schemes using `.AddMicrosoftIdentityWebApp`. Ensure that `.AddAuthentication()` does not have a default scheme defined if you intend to specify it per operation.

```csharp
services.AddAuthentication(OpenIdConnectDefaults.AuthenticationScheme) 
        .AddMicrosoftIdentityWebApp(Configuration.GetSection("AzureAd"), OpenIdConnectDefaults.AuthenticationScheme)
            .EnableTokenAcquisitionToCallDownstreamApi(Configuration.GetValue<string>("DownstreamApi:Scopes")?.Split(' '))
                .AddMicrosoftGraph(Configuration.GetSection("DownstreamApi"))
                .AddInMemoryTokenCaches();

services.AddAuthentication() 
        .AddMicrosoftIdentityWebApp(Configuration.GetSection("AzureAdB2C"), "B2C", "cookiesB2C")
            .EnableTokenAcquisitionToCallDownstreamApi(Configuration.GetValue<string>("DownstreamB2CApi:Scopes")?.Split(' '))
                .AddDownstreamWebApi("DownstreamB2CApi", Configuration.GetSection("DownstreamB2CApi"));
```

--------------------------------

### Install AzureAD PowerShell Module

Source: https://github.com/azuread/microsoft-identity-web/blob/master/tests/DevApps/blazorserver-calls-api/AppCreationScripts/AppCreationScripts.md

Installs the AzureAD module for either all users or the current user.

```PowerShell
Install-Module AzureAD
```

```PowerShell
Install-Module AzureAD -Scope CurrentUser
```

--------------------------------

### Install Downstream API Package

Source: https://github.com/azuread/microsoft-identity-web/blob/master/docs/calling-downstream-apis/AgentIdentities-Readme.md

Installs the NuGet package required for downstream API integration.

```bash
dotnet add package Microsoft.Identity.Web.DownstreamApi
```

--------------------------------

### Display tool help

Source: https://github.com/azuread/microsoft-identity-web/blob/master/tools/app-provisioning-tool/vs2019-16.9-how-to-use.md

Displays available command line options for the msidentity-app-sync tool.

```bash
msidentity-app-sync –help
```

--------------------------------

### Perform GET Requests with IDownstreamApi

Source: https://github.com/azuread/microsoft-identity-web/blob/master/docs/calling-downstream-apis/from-web-apps.md

Execute GET requests to custom APIs with optional query parameters.

```csharp
// Simple GET
var data = await _downstreamApi.GetForUserAsync<MyData>(
    "MyAPI",
    options => options.RelativePath = "api/resource");

// GET with query parameters
var results = await _downstreamApi.GetForUserAsync<SearchResults>(
    "MyAPI",
    options =>
    {
        options.RelativePath = "api/search";
        options.QueryParameters = new Dictionary<string, string>
        {
            ["query"] = "test",
            ["limit"] = "10"
        };
    });
```

--------------------------------

### Add Session Services in Startup.cs

Source: https://github.com/azuread/microsoft-identity-web/wiki/Hybrid-SPA

Configure session services in your Startup.cs file. This is a prerequisite for enabling the hybrid SPA flow.

```csharp
services.AddSession(options =>
{
      options.Cookie.IsEssential = true;
});
```

--------------------------------

### Configure Client Certificate from Path

Source: https://github.com/azuread/microsoft-identity-web/wiki/Certificates

Load a certificate from a local disk path.

```Json
{
 "ClientCertificates": [
 {
  "SourceType": "Path",
  "CertificateDiskPath": "c:\\temp\\WebAppCallingWebApiCert.pfx",
  "CertificatePassword": "password"
 }]
}
```

```CSharp
microsoftIdentityOptions.ClientCertificates = new CertificateDescription[] {
 CertificateDescription.FromPath(@"c:	emp\WebAppCallingWebApiCert.pfx",
                                     "password")
};
```

--------------------------------

### App Service System-Assigned Managed Identity Example

Source: https://github.com/azuread/microsoft-identity-web/blob/master/docs/authentication/credentials/certificateless.md

Example of a subject identifier for an App Service using a system-assigned managed identity.

```plaintext
microsoft:azure:websites:12345678-1234-1234-1234-123456789012:my-resource-group:my-app-name
```

--------------------------------

### Downstream API Configuration Example

Source: https://github.com/azuread/microsoft-identity-web/wiki/Web-APIs

Example configuration for a downstream API in appsettings.json, including ClientId, TenantId, ClientSecret, and BaseUrl/Scopes for the API.

```json
{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "ClientId": "[Client_id-of-web-api-eg-2ec40e65-ba09-4853-bcde-bcb60029e596]",
    "TenantId": "common",

   // To call an API
   "ClientSecret": "[Copy the client secret added to the app from the Azure portal]",
   "ClientCertificates": [
  ]
 },
 "GraphBeta": {
    "BaseUrl": "https://graph.microsoft.com/beta",
    "Scopes": "user.read"
    }
}
```

--------------------------------

### CIAM with Tenant ID (GUID) Configuration

Source: https://github.com/azuread/microsoft-identity-web/blob/master/docs/authority-configuration/ciam-authority-examples.md

Configure CIAM using the tenant's GUID instead of its domain name in the Authority URL.

```json
{
  "AzureAd": {
    "Authority": "https://contoso.ciamlogin.com/12345678-1234-1234-1234-123456789012",
    "ClientId": "11111111-1111-1111-1111-111111111111"
  }
}
```

--------------------------------

### Build with .NET 10 Preview Targets

Source: https://github.com/azuread/microsoft-identity-web/blob/master/README.md

Use this command to build the solution including .NET 10 preview targets. This requires setting the `TargetNetNext` property to `True`.

```bash
# Build with .NET 10 preview targets included
dotnet build Microsoft.Identity.Web.sln -p:TargetNetNext=True
```

```bash
# Or using MSBuild
msbuild Microsoft.Identity.Web.sln -p:TargetNetNext=True
```

--------------------------------

### Configure Web App to Call Downstream API (with scopes)

Source: https://github.com/azuread/microsoft-identity-web/wiki/Web-Apps

In `Startup.cs`, enable token acquisition to call downstream APIs by adding `.EnableTokenAcquisitionToCallDownstreamApi()` and specifying the required scopes. Choose a token cache implementation like `.AddInMemoryTokenCaches()`.

```CSharp
using Microsoft.Identity.Web;

public class Startup
{
 const string scopesToRequest = "user.read";
  ...
  public void ConfigureServices(IServiceCollection services)
  {
   ...
   services.AddMicrosoftIdentityWebAppAuthentication(Configuration)
                .EnableTokenAcquisitionToCallDownstreamApi(new string[] { scopesToRequest })
                     .AddInMemoryTokenCaches();
   ...
  }
  ...
}
```

--------------------------------

### Install OWIN Packages for .NET Framework

Source: https://github.com/azuread/microsoft-identity-web/blob/master/docs/calling-downstream-apis/from-web-apps.md

Install the necessary NuGet packages for integrating Microsoft Identity Web with OWIN-based applications on .NET Framework.

```powershell
Install-Package Microsoft.Identity.Web.OWIN
Install-Package Microsoft.Owin.Host.SystemWeb
```

--------------------------------

### Install Microsoft Graph PowerShell Module

Source: https://github.com/azuread/microsoft-identity-web/blob/master/docs/frameworks/aspire.md

Install the Microsoft.Graph.Applications module for PowerShell. This is a prerequisite for using Microsoft Graph PowerShell cmdlets for automated provisioning.

```powershell
# Prerequisites (one-time)
Install-Module Microsoft.Graph.Applications -Scope CurrentUser
```

--------------------------------

### Replace legacy authentication in Startup.cs

Source: https://github.com/azuread/microsoft-identity-web/wiki/migrating-aspnetcore3x-webapps

Comparison of the legacy AddAzureAD configuration versus the new AddMicrosoftIdentityWebApp approach.

```csharp
using Microsoft.Identity.Web;

public class Startup
{
  ...
  public void ConfigureServices(IServiceCollection services)
  {
   ...
   services.AddAuthentication(AzureADDefaults.AuthenticationScheme)
        .AddAzureAD(options => Configuration.Bind("AzureAd", options));
   ...
  }
  ...
}
```

```csharp
using Microsoft.Identity.Web;

public class Startup
{
  ...
  public void ConfigureServices(IServiceCollection services)
  {
  ...
     services.AddAuthentication(OpenIdConnectDefaults.AuthenticationScheme)
             .AddMicrosoftIdentityWebApp(Configuration);
  ...
  }
  ...
}
```

--------------------------------

### Install Specific Version of Microsoft.Identity.Web Project Templates

Source: https://github.com/azuread/microsoft-identity-web/wiki/Web-App-Template

Installs a specific version of the Microsoft.Identity.Web project templates. Ensure you have uninstalled any previous versions first.

```Shell
dotnet new -i Microsoft.Identity.Web.ProjectTemplates.1.9.1.nupkg
```

--------------------------------

### NuGet Dependency Versioning Example

Source: https://github.com/azuread/microsoft-identity-web/blob/master/RELEASES.md

This example shows how to specify a version range in NuGet to include patch updates but exclude minor version updates.

```xml
<dependency
id="MSALfordotNet"
version="[1.1,1.2)"
/>
```

--------------------------------

### Configure and Build Test Projects

Source: https://github.com/azuread/microsoft-identity-web/blob/master/TESTING.md

Commands to set up the environment, configure secrets, and build the repository for template testing.

```batch
cd C:\idweb
```

```batch
Set MicrosoftIdentityWebVersion=2.4.0
```

```json
"B2C_Client_ClientSecret": "secret_goes_here",
"AAD_Client_ClientSecret": "secret_goes_here",
"AAD_WebApi_ClientSecret": "secret_goes_here"
```

```batch
del ProjectTemplates\bin\Debug\*.nupkg
```

```batch
dotnet pack Microsoft.Identity.Web.sln
```

```batch
cd ProjectTemplates
```

```batch
copy nuget.config.local-build nuget.config
```

```batch
Test-templates.bat
```

--------------------------------

### Initialize Web API Project via CLI

Source: https://github.com/azuread/microsoft-identity-web/blob/master/tests/DevApps/B2CWebAppCallsWebApi/README-incremental-instructions.md

Commands to create a new directory and scaffold an ASP.NET Core Web API project configured for single-organization authentication.

```Text
md TodoListService
cd TodoListService
dotnet new webapi -au=SingleOrg
```

--------------------------------

### After: Consistent Configuration using Instance/TenantId

Source: https://github.com/azuread/microsoft-identity-web/blob/master/docs/authority-configuration/migration-authority-vs-instance.md

Migrated configuration using `AddMicrosoftIdentityWebApp` with `Instance` and `TenantId` properties set consistently. This approach is recommended for clarity and to avoid configuration conflicts.

```csharp
services.AddAuthentication(OpenIdConnectDefaults.AuthenticationScheme)
    .AddMicrosoftIdentityWebApp(options =>
    {
        options.Instance = "https://login.microsoftonline.com/";
        options.TenantId = "organizations";
        options.ClientId = "11111111-1111-1111-1111-111111111111";
    });
```

--------------------------------

### Configure Authentication Middleware in Configure()

Source: https://github.com/azuread/microsoft-identity-web/wiki/grpc

Add the `UseAuthentication` and `UseAuthorization` middleware to the `Configure` method in your `Startup.cs` file to enable authentication and authorization.

```csharp
app.UseAuthentication();
app.UseAuthorization();
```

--------------------------------

### ASP.NET Core Setup for Downstream API Calls

Source: https://github.com/azuread/microsoft-identity-web/blob/master/docs/calling-downstream-apis/custom-apis.md

Configure authentication and register downstream APIs in your ASP.NET Core application's services. This setup enables token acquisition for calling downstream APIs.

```csharp
using Microsoft.Identity.Web;

var builder = WebApplication.CreateBuilder(args);

// Add authentication
builder.Services.AddAuthentication(OpenIdConnectDefaults.AuthenticationScheme)
    .AddMicrosoftIdentityWebApp(builder.Configuration.GetSection("AzureAd"))
    .EnableTokenAcquisitionToCallDownstreamApi()
    .AddInMemoryTokenCaches();

// Register downstream APIs
builder.Services.AddDownstreamApis(
    builder.Configuration.GetSection("DownstreamApis"));

builder.Services.AddControllersWithViews();

var app = builder.Build();
app.UseAuthentication();
app.UseAuthorization();
app.MapControllers();
app.Run();
```

--------------------------------

### Configure Authentication in Startup.cs (Azure AD)

Source: https://github.com/azuread/microsoft-identity-web/wiki/grpc

Add authentication middleware to your gRPC service's `ConfigureServices` method using `AddMicrosoftWebApi`. Ensure you have the necessary NuGet packages installed.

```csharp
public Startup(IConfiguration configuration)
{
    Configuration = configuration;
}

public IConfiguration Configuration { get; }

// In ConfigureServices:
services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
        .AddMicrosoftWebApi(Configuration);
services.AddAuthorization();
```

--------------------------------

### Configure Authentication and Authorization in Startup.cs

Source: https://github.com/azuread/microsoft-identity-web/wiki/Azure-Functions

Integrate authentication and authorization middleware within the `Configure` method of your Azure Function's `Startup.cs` file.

```csharp
// Get the azure function application directory. 'C:\\whatever' for local and 'd:\\home\\whatever' for Azure
var executionContextOptions = builder.Services.BuildServiceProvider()
    .GetService<IOptions<ExecutionContextOptions>>().Value;

var currentDirectory = executionContextOptions.AppDirectory;

// Get the original configuration provider from the Azure Function
var configuration = builder.Services.BuildServiceProvider().GetService<IConfiguration>();

// Create a new IConfigurationRoot and add our configuration along with Azure's original configuration 
Configuration = new ConfigurationBuilder()
    .SetBasePath(currentDirectory)
    .AddConfiguration(configuration) // Add the original function configuration 
    .AddJsonFile("appsettings.json", optional: false, reloadOnChange: true)
    .Build();

// Replace the Azure Function configuration with our new one
builder.Services.AddSingleton(Configuration);

ConfigureServices(builder.Services);

```

--------------------------------

### Complete Autonomous Agent Service Example

Source: https://github.com/azuread/microsoft-identity-web/blob/master/docs/getting-started/daemon-app.md

A comprehensive example of a service that encapsulates agent identity management for acquiring authorization headers and listing applications via the Microsoft Graph SDK. This service requires an agent identity ID and an IServiceProvider for dependency injection.

```csharp
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Configuration;
using Microsoft.Graph;
using Microsoft.Identity.Abstractions;
using Microsoft.Identity.Web;

public class AutonomousAgentService
{
    private readonly GraphServiceClient _graphClient;
    private readonly IAuthorizationHeaderProvider _authProvider;
    private readonly string _agentIdentityId;

    public AutonomousAgentService(
        string agentIdentityId,
        IServiceProvider serviceProvider)
    {
        _agentIdentityId = agentIdentityId;
        _graphClient = serviceProvider.GetRequiredService<GraphServiceClient>();
        _authProvider = serviceProvider.GetRequiredService<IAuthorizationHeaderProvider>();
    }

    public async Task<string> GetAuthorizationHeaderAsync()
    {
        var options = new AuthorizationHeaderProviderOptions()
            .WithAgentIdentity(_agentIdentityId);

        return await _authProvider.CreateAuthorizationHeaderForAppAsync(
            "https://graph.microsoft.com/.default",
            options);
    }

    public async Task<IEnumerable<Application>> ListApplicationsAsync()
    {
        var apps = await _graphClient.Applications.GetAsync(request =>
        {
            request.Options.WithAuthenticationOptions(options =>
            {
                options.WithAgentIdentity(_agentIdentityId);
            });
        });

        return apps?.Value ?? Enumerable.Empty<Application>();
    }
}
```

--------------------------------

### Acquire Token and Call APIM

Source: https://github.com/azuread/microsoft-identity-web/blob/master/docs/advanced/api-gateways.md

Demonstrates how a client application acquires a token for the backend API and includes the subscription key for APIM.

```csharp
// Client app requests token
var result = await app.AcquireTokenSilent(
    scopes: new[] { "api://your-backend-api-client-id/access_as_user" },
    account)
    .ExecuteAsync();

// Call APIM URL with token
var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", result.AccessToken);

// Add APIM subscription key
client.DefaultRequestHeaders.Add("Ocp-Apim-Subscription-Key", "your-subscription-key");

var response = await client.GetAsync("https://your-apim.azure-api.net/api/weatherforecast");
```

--------------------------------

### Example Token Claims

Source: https://github.com/azuread/microsoft-identity-web/blob/master/docs/authentication/authorization.md

JSON representations of user-delegated and app-only tokens.

```json
{
  "aud": "api://your-api-client-id",
  "iss": "https://login.microsoftonline.com/.../v2.0",
  "scp": "access_as_user",
  "sub": "user-object-id",
  ...
}
```

```json
{
  "aud": "api://your-api-client-id",
  "iss": "https://login.microsoftonline.com/.../v2.0",
  "roles": ["TodoList.ReadWrite.All"],
  "sub": "app-object-id",
  ...
}
```

--------------------------------

### Add Microsoft.Identity.Web.GraphServiceClient Package

Source: https://github.com/azuread/microsoft-identity-web/blob/master/docs/calling-downstream-apis/GraphServiceClient-Readme.md

Install the necessary NuGet package to use the GraphServiceClient.

```shell
dotnet add package Microsoft.Identity.Web.GraphServiceClient
```

--------------------------------

### Map controllers in Startup.Configure

Source: https://github.com/azuread/microsoft-identity-web/wiki/migrating-aspnetcore3x-webapps

Ensures authentication middleware and controller mapping are correctly registered in the application pipeline.

```csharp
    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
    {
     // More code

     app.UseAuthentication();
     app.UseAuthorization();

     // More code
     app.UseEndpoints(endpoints =>
     {
      endpoints.MapRazorPages();  // If Razor pages
      endpoints.MapControllers(); // Needs to be added
     });
    }
```

--------------------------------

### Specify Certificate from Path by Configuration

Source: https://github.com/azuread/microsoft-identity-web/wiki/Using-certificates

Configure client certificate loading from a local disk path using JSON. Provide the full path to the .pfx file and its password.

```json
{
    "ClientCertificates": [
      {
       "SourceType": "Path",
       "CertificateDiskPath": "c:\\temp\\WebAppCallingWebApiCert.pfx",
      "CertificatePassword": "password"
      }]
}

```

--------------------------------

### Configure App-Only Tokens

Source: https://github.com/azuread/microsoft-identity-web/blob/master/docs/frameworks/aspire.md

Setup for service-to-service authentication without a user context.

```csharp
// Configure with RequestAppToken = true
builder.Services.AddHttpClient<WeatherApiClient>(client =>
{
    client.BaseAddress = new("https+http://apiservice");
})
.AddMicrosoftIdentityMessageHandler(options =>
{
    options.Scopes.Add("api://<api-client-id>/.default");
    options.RequestAppToken = true;
});
```

--------------------------------

### Trigger Sign-up Experience in ASP.NET Core

Source: https://github.com/azuread/microsoft-identity-web/wiki/Web-Apps

Use this action to initiate the sign-up process by setting the 'prompt' property to 'create'. This redirects the user to the identity provider to create a new guest account.

```csharp
services.AddAuthentication(OpenIdConnectDefaults.AuthenticationScheme)
        .AddMicrosoftIdentityWebApp(options =>
{
    Configuration.Bind("AzureAD", options);
    options.Events ??= new OpenIdConnectEvents();
    options.Events.OnTokenValidated += OnTokenValidatedFunc;
});
```

--------------------------------

### Example Support Request Format

Source: https://github.com/azuread/microsoft-identity-web/blob/master/docs/advanced/logging.md

When contacting support, provide this information along with the correlation ID, timestamp, tenant ID, and error code.

```text
Subject: Token acquisition failing for user.read scope

Correlation ID: 12345678-1234-1234-1234-123456789012
Timestamp: 2025-01-15 14:32:45 UTC
Tenant ID: contoso.onmicrosoft.com
Error Code: AADSTS50058
```

--------------------------------

### Uninstall project templates

Source: https://github.com/azuread/microsoft-identity-web/wiki/Web-API-Template

Removes the installed Microsoft Identity Web project templates.

```Shell
cd ProjectTemplates
dotnet new -u Microsoft.Identity.Web.ProjectTemplates
```

--------------------------------

### Copy NuGet Package and Configuration

Source: https://github.com/azuread/microsoft-identity-web/blob/master/TESTING.md

Commands to prepare the local environment for template testing using release packages.

```batch
copy "%UserProfile%\Downloads\Packages\Packages\Microsoft.Identity.Web.ProjectTemplates.%MicrosoftIdentityWebVersion%.nupkg" ProjectTemplates\bin\Debug
```

```batch
copy nuget.config.release-build nuget.config
```

--------------------------------

### Configure Redis Connection Strings

Source: https://github.com/azuread/microsoft-identity-web/blob/master/docs/authentication/token-cache/troubleshooting.md

Examples for local and Azure Redis connection strings.

```json
{
  "ConnectionStrings": {
    "Redis": "localhost:6379"
  }
}
```

```json
{
  "ConnectionStrings": {
    "Redis": "<cache-name>.redis.cache.windows.net:6380,password=<key>,ssl=True,abortConnect=False"
  }
}
```

--------------------------------

### After: Configuration using Configuration Section (Recommended)

Source: https://github.com/azuread/microsoft-identity-web/blob/master/docs/authority-configuration/migration-authority-vs-instance.md

The recommended approach for migrating authority configuration, using `AddMicrosoftIdentityWebApp` with `Configuration.GetSection("AzureAd")`. This pattern centralizes configuration in `appsettings.json`.

```csharp
services.AddAuthentication(OpenIdConnectDefaults.AuthenticationScheme)
    .AddMicrosoftIdentityWebApp(Configuration.GetSection("AzureAd"));
```

--------------------------------

### Run Application via CLI

Source: https://github.com/azuread/microsoft-identity-web/blob/master/docs/frameworks/aspire.md

Commands to restore dependencies, build the solution, and launch the AppHost project.

```powershell
# From solution root
dotnet restore
dotnet build

# Launch AppHost (starts both Web and API)
dotnet run --project .\MyService.AppHost\MyService.AppHost.csproj
```

--------------------------------

### Sample Diagnostic Output

Source: https://github.com/azuread/microsoft-identity-web/wiki/Web-API-Troubleshooting

Example of the log output generated when diagnostic events are enabled.

```text
Microsoft.Identity.Web.Resource.JwtBearerMiddlewareDiagnostics: Debug: Begin OnMessageReceivedAsync. 
Microsoft.Identity.Web.Resource.JwtBearerMiddlewareDiagnostics: Debug: End OnMessageReceivedAsync. 
Microsoft.AspNetCore.Authentication.JwtBearer.JwtBearerHandler: Information: Successfully validated the token.
Microsoft.Identity.Web.Resource.JwtBearerMiddlewareDiagnostics: Debug: Begin OnTokenValidatedAsync. 
Microsoft.Identity.Web.Resource.JwtBearerMiddlewareDiagnostics: Debug: End OnTokenValidatedAsync. 
```