entra-id-aspire-authentication

name	entra-id-aspire-authentication
description	Guide for adding Microsoft Entra ID (Azure AD) authentication to .NET Aspire applications. Use this when asked to add authentication, Entra ID, Azure AD, OIDC, or identity to an Aspire app, or when working with Microsoft.Identity.Web in Aspire projects.
license	MIT

Entra ID Authentication for .NET Aspire Applications

This skill helps you integrate Microsoft Entra ID (Azure AD) authentication into .NET Aspire distributed applications using Microsoft.Identity.Web.

When to Use This Skill

• Adding user authentication to Aspire apps
• Protecting APIs with JWT Bearer authentication
• Configuring OIDC sign-in for Blazor Server
• Setting up token acquisition for downstream API calls
• Implementing service-to-service authentication

Architecture Overview

User Browser → Blazor Server (OIDC) → Entra ID → Access Token → Protected API (JWT)

Key Components:

• Blazor Frontend: Uses AddMicrosoftIdentityWebApp for OIDC + MicrosoftIdentityMessageHandler for token attachment
• API Backend: Uses AddMicrosoftIdentityWebApi for JWT validation
• Aspire: Service discovery with https+http://servicename URLs

---

Pre-Implementation Checklist

Before starting, the agent MUST:

1. Detect Project Types

Scan each project's Program.cs to identify its type:

# Find all Program.cs files in solution
Get-ChildItem -Recurse -Filter "Program.cs" | ForEach-Object {
    $content = Get-Content $_.FullName -Raw
    $projectDir = Split-Path $_.FullName -Parent
    $projectName = Split-Path $projectDir -Leaf
    
    # Skip AppHost and ServiceDefaults
    if ($projectName -match "AppHost|ServiceDefaults") { return }
    
    $isWebApp = $content -match "AddRazorComponents|MapRazorComponents|AddServerSideBlazor"
    $isApi = $content -match "MapGet|MapPost|MapPut|MapDelete|AddControllers"
    
    if ($isWebApp) {
        Write-Host "WEB APP: $projectName (has Razor/Blazor components)"
    } elseif ($isApi) {
        Write-Host "API: $projectName (exposes endpoints)"
    }
}

Detection rules:

Pattern in Program.cs	Project Type
AddRazorComponents / MapRazorComponents / AddServerSideBlazor	Blazor Web App
MapGet / MapPost / AddControllers (without Razor)	Web API

Note: APIs can call other APIs (downstream). The Aspire .WithReference() shows service dependencies, not necessarily web-to-API relationships.

2. Confirm with User

AGENT: Show detected topology and ask for confirmation:

"I detected:

• Web App (Blazor): {webProjectName}
• API: {apiProjectName}

The web app will authenticate users and call the API. Is this correct?"

3. Establish Workflow

AGENT: Explain the two-phase approach:

"I'll implement authentication in two phases:

Phase 1 (now): Add authentication code with placeholder values. The app will build but won't run until app registrations are configured.

Phase 2 (after): Use the entra-id-aspire-provisioning skill to create Entra ID app registrations and update the configuration with real values.

Ready to proceed with Phase 1?"

---

Implementation Checklist

CRITICAL: Complete ALL steps in order. Do not skip any step.

API Project Steps

• Step 1.1: Add Microsoft.Identity.Web package
• Step 1.2: Update appsettings.json with AzureAd section
• Step 1.3: Update Program.cs with JWT Bearer authentication
• Step 1.4: Add RequireAuthorization() to protected endpoints

Web/Blazor Project Steps

• Step 2.1: Add Microsoft.Identity.Web package
• Step 2.2: Update appsettings.json with AzureAd and scopes
• Step 2.3: Update Program.cs with OIDC, token acquisition, and BlazorAuthenticationChallengeHandler
• Step 2.4: Verify Microsoft.Identity.Web version includes Blazor helpers (v3.3.0+)
• Step 2.5: Create UserInfo.razor component (LOGIN BUTTON)
• Step 2.6: Update MainLayout.razor to include UserInfo
• Step 2.7: Update Routes.razor with AuthorizeRouteView
• Step 2.8: Store client secret in user-secrets
• Step 2.9: Add try/catch with ChallengeHandler on every page calling APIs

---

Step-by-Step Implementation

Prerequisites

1. .NET Aspire solution with API and Web (Blazor) projects
2. Azure AD tenant

Two-phase workflow:

• Phase 1: Add authentication code with placeholder values → App will build but not run
• Phase 2: Run entra-id-aspire-provisioning skill to create app registrations → App will run

Part 1: Protect the API with JWT Bearer

1.1 Add Package:

cd MyService.ApiService
dotnet add package Microsoft.Identity.Web

1.2 Configure appsettings.json:

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "<your-tenant-id>",
    "ClientId": "<your-api-client-id>",
    "Audiences": ["api://<your-api-client-id>"]
  }
}

1.3 Update Program.cs:

using Microsoft.AspNetCore.Authentication.JwtBearer;
using Microsoft.Identity.Web;

var builder = WebApplication.CreateBuilder(args);
builder.AddServiceDefaults();

// Add JWT Bearer authentication
builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddMicrosoftIdentityWebApi(builder.Configuration.GetSection("AzureAd"));

builder.Services.AddAuthorization();

var app = builder.Build();

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

// Protect endpoints
app.MapGet("/weatherforecast", () => { /* ... */ })
    .RequireAuthorization();

app.Run();

Part 2: Configure Blazor Frontend

2.1 Add Package:

cd MyService.Web
dotnet add package Microsoft.Identity.Web

2.2 Configure appsettings.json:

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "Domain": "<your-tenant>.onmicrosoft.com",
    "TenantId": "<tenant-guid>",
    "ClientId": "<web-app-client-id>",
    "CallbackPath": "/signin-oidc",
    "ClientCredentials": [
      {
        "SourceType": "ClientSecret",
        "ClientSecret": "<your-client-secret>"
      }
    ]
  },
  "WeatherApi": {
    "Scopes": ["api://<api-client-id>/.default"]
  }
}

2.3 Update Program.cs:

using Microsoft.AspNetCore.Authentication.OpenIdConnect;
using Microsoft.Identity.Web;

var builder = WebApplication.CreateBuilder(args);
builder.AddServiceDefaults();

// Authentication + token acquisition
builder.Services.AddAuthentication(OpenIdConnectDefaults.AuthenticationScheme)
    .AddMicrosoftIdentityWebApp(builder.Configuration.GetSection("AzureAd"))
    .EnableTokenAcquisitionToCallDownstreamApi()
    .AddInMemoryTokenCaches();

builder.Services.AddCascadingAuthenticationState();
builder.Services.AddRazorComponents().AddInteractiveServerComponents();

// Add Blazor authentication challenge handler for incremental consent and Conditional Access
builder.Services.AddScoped<BlazorAuthenticationChallengeHandler>();

// HttpClient with automatic token attachment
builder.Services.AddHttpClient<WeatherApiClient>(client =>
{
    client.BaseAddress = new("https+http://apiservice"); // Aspire service discovery
})
.AddMicrosoftIdentityMessageHandler(builder.Configuration.GetSection("WeatherApi").Bind);

var app = builder.Build();

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

app.MapRazorComponents<App>().AddInteractiveServerRenderMode();
app.MapGroup("/authentication").MapLoginAndLogout();

app.Run();

2.4 Blazor authentication helpers:

These helpers ship in the Microsoft.Identity.Web NuGet package (version 3.3.0+). Simply add using Microsoft.Identity.Web; — no file copying required.

AGENT: The LoginLogoutEndpointRouteBuilderExtensions class provides the MapLoginAndLogout() extension method with support for incremental consent and Conditional Access. The BlazorAuthenticationChallengeHandler class handles authentication challenges in Blazor Server components. Both are now included in Microsoft.Identity.Web and are automatically available once you reference the package.

2.6 Create UserInfo Component (Components/UserInfo.razor) — THE LOGIN BUTTON:

CRITICAL: This step is frequently forgotten. Without this, users have no way to log in!

@using Microsoft.AspNetCore.Components.Authorization

<AuthorizeView>
    <Authorized>
        <span class="nav-item">Hello, @context.User.Identity?.Name</span>
        <form action="/authentication/logout" method="post" class="nav-item">
            <AntiforgeryToken />
            <input type="hidden" name="returnUrl" value="/" />
            <button type="submit" class="btn btn-link nav-link">Logout</button>
        </form>
    </Authorized>
    <NotAuthorized>
        <a href="/authentication/login?returnUrl=/" class="nav-link">Login</a>
    </NotAuthorized>
</AuthorizeView>

2.7 Update MainLayout.razor to include UserInfo:

Find the <main> or navigation section in Components/Layout/MainLayout.razor and add the UserInfo component:

@inherits LayoutComponentBase

<div class="page">
    <div class="sidebar">
        <NavMenu />
    </div>

    <main>
        <div class="top-row px-4">
            <UserInfo />  @* <-- ADD THIS LINE *@
        </div>

        <article class="content px-4">
            @Body
        </article>
    </main>
</div>

2.8 Update Routes.razor for AuthorizeRouteView:

Replace RouteView with AuthorizeRouteView in Components/Routes.razor:

@using Microsoft.AspNetCore.Components.Authorization

<Router AppAssembly="typeof(Program).Assembly">
    <Found Context="routeData">
        <AuthorizeRouteView RouteData="routeData" DefaultLayout="typeof(Layout.MainLayout)">
            <NotAuthorized>
                <p>You are not authorized to view this page.</p>
                <a href="/authentication/login">Login</a>
            </NotAuthorized>
        </AuthorizeRouteView>
        <FocusOnNavigate RouteData="routeData" Selector="h1" />
    </Found>
</Router>

2.9 Store Client Secret in User Secrets:

Never commit secrets to source control!

cd MyService.Web
dotnet user-secrets init
dotnet user-secrets set "AzureAd:ClientCredentials:0:ClientSecret" "<your-client-secret>"

Then update appsettings.json to reference user secrets (remove the hardcoded secret):

{
  "AzureAd": {
    "ClientCredentials": [
      {
        // For more options see https://aka.ms/ms-id-web/credentials
        "SourceType": "ClientSecret"
      }
    ]
  }
}

---

Common Patterns

Protect Blazor Pages

@page "/weather"
@attribute [Authorize]

Scope Validation in API

app.MapGet("/weatherforecast", () => { /* ... */ })
    .RequireAuthorization()
    .RequireScope("access_as_user");

App-Only Tokens (Service-to-Service)

.AddMicrosoftIdentityMessageHandler(options =>
{
    options.Scopes.Add("api://<api-client-id>/.default");
    options.RequestAppToken = true;
});

Override Scopes Per Request

var request = new HttpRequestMessage(HttpMethod.Get, "/endpoint")
    .WithAuthenticationOptions(options =>
    {
        options.Scopes.Clear();
        options.Scopes.Add("api://<client-id>/specific.scope");
    });

Production: Use Managed Identity

{
  "AzureAd": {
    "ClientCredentials": [
      {
        "SourceType": "SignedAssertionFromManagedIdentity",
        "ManagedIdentityClientId": "<user-assigned-mi-client-id>"
      }
    ]
  }
}