Security & Identity
Complete Guide

User / Service
    │
    ▼  authenticates with
Microsoft Entra ID  ──────────────────────────────────────────────────────────┐
    │  issues                                                                  │
    ▼                                                                          │
JWT Access Token  (OAuth 2.0 Bearer)                                          │
    │                                                                          │
    ▼  sent to                                                                 │
Your API / Microservice                                                        │
    │  validates JWT (signature, issuer, audience, expiry, claims)             │
    │                                                                          │
    │  needs a secret? calls                                                   │
    ▼                                                                          │
Azure Key Vault  ◄── authenticated via Managed Identity (no password needed) ◄┘
    │  returns secret value
    ▼
Your Business Logic

# ── App Service ──────────────────────────────────────────────────────
az webapp identity assign \
  --resource-group myRG \
  --name myWebApp

# Capture the principal ID for role assignments
PRINCIPAL_ID=$(az webapp identity show \
  --resource-group myRG --name myWebApp \
  --query principalId --output tsv)

# ── Azure Function ────────────────────────────────────────────────────
az functionapp identity assign \
  --resource-group myRG \
  --name myFunctionApp

# ── Azure Container App ───────────────────────────────────────────────
az containerapp identity assign \
  --resource-group myRG \
  --name myContainerApp \
  --system-assigned

# ── Grant identity access to Key Vault secrets ────────────────────────
az role assignment create \
  --assignee "$PRINCIPAL_ID" \
  --role "Key Vault Secrets User" \
  --scope "/subscriptions/<sub>/resourceGroups/<rg>/providers/Microsoft.KeyVault/vaults/<vault>"

# ── Grant identity access to Service Bus (send + receive) ─────────────
az role assignment create \
  --assignee "$PRINCIPAL_ID" \
  --role "Azure Service Bus Data Owner" \
  --scope "/subscriptions/<sub>/resourceGroups/<rg>/providers/Microsoft.ServiceBus/namespaces/<ns>"

using Azure.Identity;
using Azure.Security.KeyVault.Secrets;
using Azure.Messaging.ServiceBus;

// DefaultAzureCredential tries credentials in order:
//  1. Environment variables (CI/CD service principal)
//  2. Workload Identity (AKS pods)
//  3. Managed Identity (App Service, Functions, VMs)
//  4. Azure CLI (local dev)
//  5. Visual Studio / VS Code (local dev)
var credential = new DefaultAzureCredential();

// ── Key Vault ─────────────────────────────────────────────────────────
var kvClient = new SecretClient(
    new Uri("https://myvault.vault.azure.net/"),
    credential);

KeyVaultSecret secret = await kvClient.GetSecretAsync("db-connection-string");
string connectionString = secret.Value;

// ── Service Bus ───────────────────────────────────────────────────────
var sbClient = new ServiceBusClient(
    "<namespace>.servicebus.windows.net",
    credential); // No connection string — Managed Identity token

// ── Blob Storage ──────────────────────────────────────────────────────
var blobClient = new BlobServiceClient(
    new Uri("https://mystorageaccount.blob.core.windows.net/"),
    credential);

// ── Azure SQL (with Managed Identity token) ───────────────────────────
// In connection string: Authentication=Active Directory Managed Identity
// Or in EF Core:
services.AddDbContext<AppDbContext>((sp, options) =>
{
    var conn = new SqlConnection(configuration["Database:ConnectionString"]);
    conn.AccessToken = await new DefaultAzureCredential()
        .GetTokenAsync(new TokenRequestContext(
            ["https://database.windows.net/.default"]));
    options.UseSqlServer(conn);
});

# 1. Create user-assigned managed identity (independent resource)
az identity create \
  --resource-group myRG \
  --name platform-reader-identity

# Capture identifiers
CLIENT_ID=$(az identity show -g myRG -n platform-reader-identity --query clientId -o tsv)
PRINCIPAL_ID=$(az identity show -g myRG -n platform-reader-identity --query principalId -o tsv)

# 2. Assign roles ONCE — shared by all resources using this identity
az role assignment create \
  --assignee "$PRINCIPAL_ID" \
  --role "Key Vault Secrets User" \
  --scope "/subscriptions/<sub>/resourceGroups/<rg>/providers/Microsoft.KeyVault/vaults/myVault"

# 3. Attach the same identity to multiple resources
az webapp identity assign \
  --resource-group myRG \
  --name myWebApp \
  --identities /subscriptions/<sub>/resourceGroups/<rg>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/platform-reader-identity

az functionapp identity assign \
  --resource-group myRG \
  --name myFunctionApp \
  --identities /subscriptions/<sub>/resourceGroups/<rg>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/platform-reader-identity

// Use a specific user-assigned identity when the resource has multiple
var credential = new ManagedIdentityCredential(
    clientId: "<user-assigned-client-id>");

// Or with DefaultAzureCredential
var credential = new DefaultAzureCredential(
    new DefaultAzureCredentialOptions
    {
        ManagedIdentityClientId = "<user-assigned-client-id>"
    });

var kvClient = new SecretClient(
    new Uri("https://myvault.vault.azure.net/"),
    credential);

# Enable OIDC issuer and Workload Identity on AKS
az aks update \
  --resource-group myRG \
  --name myAKS \
  --enable-oidc-issuer \
  --enable-workload-identity

# Get the OIDC issuer URL
OIDC_ISSUER=$(az aks show -g myRG -n myAKS --query "oidcIssuerProfile.issuerUrl" -o tsv)

# Create federated credential — links K8s service account to Entra ID app
az identity federated-credential create \
  --name aks-orders-api \
  --identity-name platform-reader-identity \
  --resource-group myRG \
  --issuer "$OIDC_ISSUER" \
  --subject "system:serviceaccount:myplatform:orders-api-sa" \
  --audience api://AzureADTokenExchange

# k8s/orders-serviceaccount.yaml
apiVersion: v1
kind: ServiceAccount
metadata:
  name: orders-api-sa
  namespace: myplatform
  annotations:
    azure.workload.identity/client-id: "<user-assigned-client-id>"
---
# Reference in Deployment
spec:
  template:
    metadata:
      labels:
        azure.workload.identity/use: "true"   # Inject OIDC token volume
    spec:
      serviceAccountName: orders-api-sa

# Best pattern: reference in App Settings — platform resolves at runtime
# No SDK call needed — value injected as environment variable

az webapp config appsettings set \
  --resource-group myRG \
  --name myWebApp \
  --settings \
    "DB_CONNECTION=@Microsoft.KeyVault(VaultName=myVault;SecretName=db-connstr)" \
    "STRIPE_KEY=@Microsoft.KeyVault(VaultName=myVault;SecretName=stripe-api-key)" \
    "JWT_SECRET=@Microsoft.KeyVault(VaultName=myVault;SecretName=jwt-signing-key)"

# Verify resolution status
az webapp config appsettings list \
  --resource-group myRG --name myWebApp \
  --query "[?contains(name,'DB_CONNECTION')]"

// Register Key Vault as a configuration provider (.NET 8)
// Secrets automatically available via IConfiguration["secret-name"]
builder.Configuration.AddAzureKeyVault(
    new Uri("https://myvault.vault.azure.net/"),
    new DefaultAzureCredential(),
    new AzureKeyVaultConfigurationOptions
    {
        ReloadInterval = TimeSpan.FromMinutes(30) // Poll for updated secrets
    });

// Access via IConfiguration — works like any other config value
var dbConnStr = builder.Configuration["db-connstr"];
var jwtSecret = builder.Configuration["jwt-signing-key"];

// ── Or inject the SecretClient directly ──────────────────────────────
services.AddSingleton(sp => new SecretClient(
    new Uri("https://myvault.vault.azure.net/"),
    new DefaultAzureCredential()));

// ── Usage in a service ────────────────────────────────────────────────
public class ApiKeyService(SecretClient kvClient, IMemoryCache cache)
{
    public async Task<string> GetApiKeyAsync(string service, CancellationToken ct = default)
    {
        var cacheKey = $"apikey:{service}";

        // Cache for 10 minutes — reduces KV operation count
        return await cache.GetOrCreateAsync(cacheKey, async entry =>
        {
            entry.AbsoluteExpirationRelativeToNow = TimeSpan.FromMinutes(10);
            var secret = await kvClient.GetSecretAsync(service, cancellationToken: ct);
            return secret.Value.Value;
        }) ?? throw new InvalidOperationException($"Secret {service} not found");
    }
}

// Inject API keys into typed HTTP clients via KV — retrieved once at startup
services.AddHttpClient<IStripeClient, StripeClient>()
    .ConfigureHttpClient(async (sp, client) =>
    {
        var kv = sp.GetRequiredService<SecretClient>();
        var key = await kv.GetSecretAsync("stripe-api-key");
        client.DefaultRequestHeaders.Authorization =
            new AuthenticationHeaderValue("Bearer", key.Value.Value);
        client.BaseAddress = new Uri("https://api.stripe.com/v1/");
    });

// Function triggered by Key Vault Event Grid event
[Function("RotateDbPassword")]
public async Task Run(
    [EventGridTrigger] EventGridEvent evt,
    ILogger<RotateDbPassword> log)
{
    if (evt.EventType != "Microsoft.KeyVault.SecretNearExpiry") return;

    var secretName = evt.Subject; // e.g. "orders-db-password"
    log.LogInformation("Rotating secret: {SecretName}", secretName);

    var kvClient = new SecretClient(
        new Uri("https://myvault.vault.azure.net/"),
        new DefaultAzureCredential());

    // 1. Generate new credential at the database
    var newPassword = await _dbAdmin.RotatePasswordAsync(secretName);

    // 2. Write new version to Key Vault
    var newSecret = new KeyVaultSecret(secretName, newPassword);
    newSecret.Properties.ExpiresOn = DateTimeOffset.UtcNow.AddDays(90);
    newSecret.Properties.Tags["RotatedAt"] = DateTime.UtcNow.ToString("o");

    await kvClient.SetSecretAsync(newSecret);

    // 3. Apps calling GetSecretAsync("<name>") without a version
    //    automatically receive the new version on next call.
    log.LogInformation("Secret {SecretName} rotated. New version created.", secretName);
}

// Set up rotation policy on the secret (automate reminders)
// via CLI:
// az keyvault secret set-attributes
//   --vault-name myVault --name orders-db-password
//   --expires "$(date -u -d '+90 days' '+%Y-%m-%dT%H:%M:%SZ')"
//   --tags "RotationPolicy=90days"

Authorization Endpoint  (GET)
  https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/authorize

Token Endpoint  (POST)
  https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token

JWKS (public keys for JWT verification)
  https://login.microsoftonline.com/<tenant-id>/discovery/v2.0/keys

OpenID Configuration (discovery document)
  https://login.microsoftonline.com/<tenant-id>/v2.0/.well-known/openid-configuration

STEP 1 — User clicks "Login" — browser redirects to Entra ID
GET https://login.microsoftonline.com/<tenant>/oauth2/v2.0/authorize
  ?client_id=<app-id>
  &response_type=code
  &redirect_uri=https://myapp.com/auth/callback
  &scope=openid profile email api://myapi/Orders.Read
  &state=<random-csrf-token>
  &code_challenge=<base64url(sha256(code_verifier))>
  &code_challenge_method=S256

STEP 2 — User authenticates at Entra ID
         (MFA, Conditional Access evaluated here)

STEP 3 — Entra ID redirects back with authorization code
GET https://myapp.com/auth/callback
  ?code=<authorization-code>
  &state=<same-state>

STEP 4 — Server exchanges code for tokens (back-channel — never exposed to browser)
POST https://login.microsoftonline.com/<tenant>/oauth2/v2.0/token
  Content-Type: application/x-www-form-urlencoded

  grant_type=authorization_code
  &client_id=<app-id>
  &client_secret=<client-secret>      ← confidential client only
  &code=<authorization-code>
  &redirect_uri=https://myapp.com/auth/callback
  &code_verifier=<original-random-string>   ← PKCE verifier

STEP 5 — Entra ID returns tokens
{
  "access_token":  "<jwt>",          ← Send to APIs
  "id_token":      "<jwt>",          ← User identity (for the app)
  "refresh_token": "<opaque>",       ← Get new access tokens silently
  "expires_in":    3600,
  "token_type":    "Bearer"
}

// .NET 8 — MSAL Client Credentials (app-only token)
// NuGet: Microsoft.Identity.Client

var app = ConfidentialClientApplicationBuilder
    .Create("<client-id>")
    .WithClientSecret("<client-secret>")          // Or .WithCertificate(cert)
    .WithAuthority($"https://login.microsoftonline.com/<tenant-id>")
    .Build();

var result = await app.AcquireTokenForClient(
    scopes: ["api://target-api/.default"])  // .default = all app permissions
    .ExecuteAsync();

string accessToken = result.AccessToken;

// ── Or via DefaultAzureCredential (Managed Identity — no secret) ───────
var credential  = new DefaultAzureCredential();
var tokenCtx    = new TokenRequestContext(["api://target-api/.default"]);
var tokenResult = await credential.GetTokenAsync(tokenCtx);

// ── Attach to HttpClient ──────────────────────────────────────────────
httpClient.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", tokenResult.Token);

// Orders API received user's access token.
// Needs to call Inventory API AS the user (delegated permissions).

[Authorize]
public async Task<IActionResult> GetOrderWithInventory(Guid orderId)
{
    // Get the inbound user token from the request
    string inboundToken = HttpContext.GetBearerToken()!;

    // Exchange it for a token scoped to the Inventory API (OBO flow)
    var confidentialApp = ConfidentialClientApplicationBuilder
        .Create("<orders-api-client-id>")
        .WithClientSecret("<orders-api-client-secret>")
        .WithAuthority($"https://login.microsoftonline.com/<tenant>")
        .Build();

    var userAssertion = new UserAssertion(inboundToken);
    var result = await confidentialApp
        .AcquireTokenOnBehalfOf(
            scopes: ["api://inventory-api/Inventory.Read"],
            userAssertion: userAssertion)
        .ExecuteAsync();

    // Call downstream API with the OBO token
    _httpClient.DefaultRequestHeaders.Authorization =
        new AuthenticationHeaderValue("Bearer", result.AccessToken);

    var inventory = await _httpClient.GetFromJsonAsync<InventoryData>(
        $"/api/products/{orderId}/inventory");

    return Ok(new { order = await GetOrderAsync(orderId), inventory });
}

// SPA — MSAL.js 3 with PKCE (automatic)
// NuGet/npm: @azure/msal-browser

import { PublicClientApplication, Configuration } from "@azure/msal-browser";

const msalConfig: Configuration = {
  auth: {
    clientId:    "<spa-app-client-id>",
    authority:   "https://login.microsoftonline.com/<tenant-id>",
    redirectUri: window.location.origin,
  },
  cache: {
    cacheLocation: "sessionStorage",     // sessionStorage > localStorage for security
    storeAuthStateInCookie: false,
  },
};

const msalInstance = new PublicClientApplication(msalConfig);
await msalInstance.initialize();

// Login — MSAL handles PKCE code_verifier/challenge automatically
const loginResult = await msalInstance.loginPopup({
  scopes: ["openid", "profile", "api://myapi/Orders.Read"],
});

// Silently get an access token for the API (uses refresh token / cache)
const tokenResult = await msalInstance.acquireTokenSilent({
  scopes: ["api://myapi/Orders.Read"],
  account: msalInstance.getAllAccounts()[0],
});

// Attach to fetch call
const response = await fetch("https://myapi.com/api/orders", {
  headers: {
    Authorization: `Bearer ${tokenResult.accessToken}`,
    "Content-Type": "application/json",
  },
});

// ── HEADER (algorithm + key identifier) ─────────────────────────────
{
  "typ": "JWT",
  "alg": "RS256",     // RSA-SHA256 — Entra ID always uses RS256 for access tokens
  "kid": "abc123..."  // Key ID — matches a public key in the JWKS endpoint
}

// ── PAYLOAD (claims) ─────────────────────────────────────────────────
{
  // Standard registered claims (RFC 7519)
  "iss": "https://login.microsoftonline.com/<tenant-id>/v2.0",  // Issuer
  "sub": "user-object-id",                                      // Subject (user or app)
  "aud": "api://myapi",                                         // Audience — MUST match your API
  "exp": 1746999999,                                            // Expiry (Unix timestamp)
  "iat": 1746996399,                                            // Issued At
  "nbf": 1746996399,                                            // Not Before

  // Entra ID specific claims
  "tid":   "<tenant-id>",           // Tenant ID
  "oid":   "<user-object-id>",      // Unique user object ID (stable across apps)
  "azp":   "<client-id>",           // Authorized party (client app ID)
  "azpacr":"1",                     // Client auth method: 0=public, 1=secret, 2=cert
  "ver":   "2.0",                   // Token version

  // User identity claims (with openid + profile scope)
  "name":               "Alice Smith",
  "preferred_username": "alice@contoso.com",
  "email":              "alice@contoso.com",
  "given_name":         "Alice",
  "family_name":        "Smith",

  // Authorization claims
  "scp":   "Orders.Read Orders.Write",  // Delegated scopes (user present)
  "roles": ["Orders.Admin"],            // App roles assigned to user/app

  // OIDC nonce (when id_token)
  "nonce": "<random-value>",

  // Continuous Access Evaluation
  "xms_cc": { "values": ["cp1"] }    // CAE-capable client
}

// ── SIGNATURE ────────────────────────────────────────────────────────
// RS256: RSA signature of base64url(header) + "." + base64url(payload)
// Verify using public key from:
// https://login.microsoftonline.com/<tenant>/discovery/v2.0/keys

// Program.cs — Orders API
var tenantId = builder.Configuration["AzureAd:TenantId"]!;
var audience  = builder.Configuration["AzureAd:Audience"]!; // api://myorders-api

builder.Services
    .AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer(options =>
    {
        // Authority = Entra ID OIDC discovery URL
        // Middleware auto-downloads signing keys from JWKS endpoint
        options.Authority = $"https://login.microsoftonline.com/{tenantId}/v2.0";

        // Audience validation — CRITICAL — prevents token confusion attacks
        options.Audience = audience;

        options.TokenValidationParameters = new TokenValidationParameters
        {
            ValidateIssuerSigningKey = true,  // Verify RS256 signature
            ValidateIssuer           = true,  // Verify iss matches authority
            ValidateAudience         = true,  // Verify aud matches our API
            ValidateLifetime         = true,  // Reject expired tokens
            ClockSkew                = TimeSpan.FromMinutes(5), // Tolerate 5-min clock drift

            // For multi-tenant apps — accept tokens from multiple tenants
            // ValidIssuers = new[] {
            //   $"https://login.microsoftonline.com/{tenantId}/v2.0",
            //   $"https://login.microsoftonline.com/common/v2.0",
            // }
        };

        options.Events = new JwtBearerEvents
        {
            OnTokenValidated = ctx =>
            {
                // Additional custom validation after standard checks
                var tid = ctx.Principal!.FindFirst("tid")?.Value;
                if (tid != tenantId)
                {
                    ctx.Fail("Token from unexpected tenant");
                }
                return Task.CompletedTask;
            },
            OnAuthenticationFailed = ctx =>
            {
                logger.LogWarning("JWT auth failed: {Error}", ctx.Exception.Message);
                return Task.CompletedTask;
            },
            OnChallenge = ctx =>
            {
                // Custom 401 body
                ctx.HandleResponse();
                ctx.Response.StatusCode  = 401;
                ctx.Response.ContentType = "application/problem+json";
                return ctx.Response.WriteAsJsonAsync(new
                {
                    type   = "https://tools.ietf.org/html/rfc7235#section-3.1",
                    title  = "Unauthorized",
                    status = 401,
                    detail = "A valid Bearer token is required"
                });
            }
        };
    });

// Define policies in Program.cs
builder.Services.AddAuthorizationBuilder()
    // Delegated (user present) — checks scp claim
    .AddPolicy("Orders.Read", policy =>
        policy.RequireAuthenticatedUser()
              .RequireClaim("scp", "Orders.Read"))

    .AddPolicy("Orders.Write", policy =>
        policy.RequireAuthenticatedUser()
              .RequireClaim("scp", "Orders.Write"))

    // App role — checks roles claim
    .AddPolicy("OrdersAdmin", policy =>
        policy.RequireAuthenticatedUser()
              .RequireClaim("roles", "Orders.Admin"))

    // Service-to-service — app-only token (no user)
    .AddPolicy("ServiceToService", policy =>
        policy.RequireClaim("azp")
              .RequireClaim("idtyp", "app"))

    // Combined: must have scope AND be from expected tenant
    .AddPolicy("TrustedOrders", policy =>
        policy.RequireAuthenticatedUser()
              .RequireClaim("scp", "Orders.Read")
              .RequireClaim("tid", tenantId));

// Apply to endpoints
group.MapGet("/",          GetOrders).RequireAuthorization("Orders.Read");
group.MapPost("/",         CreateOrder).RequireAuthorization("Orders.Write");
group.MapDelete("/{id}",   DeleteOrder).RequireAuthorization("OrdersAdmin");
group.MapGet("/internal",  InternalGet).RequireAuthorization("ServiceToService");

// ── Reading claims in handlers ────────────────────────────────────────
private static async Task<IResult> CreateOrderAsync(
    CreateOrderCommand cmd,
    ClaimsPrincipal user,   // Injected automatically from HttpContext.User
    ISender sender,
    CancellationToken ct)
{
    var userId   = user.FindFirstValue("oid")!;       // Stable user ID
    var tenantId = user.FindFirstValue("tid")!;
    var scopes   = user.FindFirstValue("scp")!;       // Granted scopes

    var enrichedCmd = cmd with { RequestedBy = userId };
    var result = await sender.Send(enrichedCmd, ct);
    return result.IsSuccess ? Results.Created(...) : Results.Problem(...);
}

// For scenarios like background services, message consumers,
// or validating tokens outside of HTTP pipeline

public class JwtValidator(IConfiguration config)
{
    public async Task<ClaimsPrincipal> ValidateAsync(string token)
    {
        var tenantId = config["AzureAd:TenantId"]!;
        var audience  = config["AzureAd:Audience"]!;

        // Download JWKS (signing keys) from Entra ID discovery endpoint
        var configManager = new ConfigurationManager<OpenIdConnectConfiguration>(
            $"https://login.microsoftonline.com/{tenantId}/v2.0/.well-known/openid-configuration",
            new OpenIdConnectConfigurationRetriever());

        var oidcConfig = await configManager.GetConfigurationAsync();

        var validationParams = new TokenValidationParameters
        {
            ValidIssuer              = $"https://login.microsoftonline.com/{tenantId}/v2.0",
            ValidAudience            = audience,
            IssuerSigningKeys        = oidcConfig.SigningKeys, // RS256 public keys
            ValidateIssuerSigningKey = true,
            ValidateIssuer           = true,
            ValidateAudience         = true,
            ValidateLifetime         = true,
            ClockSkew                = TimeSpan.FromMinutes(5),
        };

        var handler    = new JsonWebTokenHandler();
        var result     = handler.ValidateToken(token, validationParams);

        if (!result.IsValid)
            throw new SecurityTokenException($"Token invalid: {result.Exception?.Message}");

        return new ClaimsPrincipal(result.ClaimsIdentity);
    }
}

// ASP.NET Core web app — silent token refresh with MSAL
// NuGet: Microsoft.Identity.Web

// Program.cs
builder.Services.AddAuthentication(OpenIdConnectDefaults.AuthenticationScheme)
    .AddMicrosoftIdentityWebApp(builder.Configuration.GetSection("AzureAd"))
    .EnableTokenAcquisitionToCallDownstreamApi(
        initialScopes: ["api://myapi/Orders.Read"])
    .AddDistributedTokenCaches();  // Redis-backed token cache for scale-out

// In a controller / Minimal API handler
app.MapGet("/orders", async (ITokenAcquisition tokenAcquisition) =>
{
    // MSAL handles refresh silently — throws MsalUiRequiredException if re-auth needed
    string token = await tokenAcquisition.GetAccessTokenForUserAsync(
        scopes: ["api://myapi/Orders.Read"]);

    // Use token to call downstream API
    _httpClient.DefaultRequestHeaders.Authorization =
        new AuthenticationHeaderValue("Bearer", token);

    return await _httpClient.GetFromJsonAsync<List<Order>>("/api/v1/orders");
})
.RequireAuthorization();

# ── Register the Orders API ──────────────────────────────────────────
az ad app create \
  --display-name "Orders API" \
  --identifier-uris "api://orders-api" \
  --sign-in-audience AzureADMyOrg

ORDERS_APP_ID=$(az ad app list --display-name "Orders API" --query "[0].appId" -o tsv)

# Add delegated scopes (permissions users can grant)
az ad app update --id "$ORDERS_APP_ID" --set api='{
  "oauth2PermissionScopes": [
    {
      "id": "'$(uuidgen)'",
      "value": "Orders.Read",
      "type": "User",
      "adminConsentDisplayName": "Read orders",
      "adminConsentDescription": "Allows reading orders on behalf of the user",
      "isEnabled": true
    },
    {
      "id": "'$(uuidgen)'",
      "value": "Orders.Write",
      "type": "User",
      "adminConsentDisplayName": "Create and update orders",
      "adminConsentDescription": "Allows creating and updating orders on behalf of the user",
      "isEnabled": true
    }
  ]
}'

# Add app roles (permissions apps or users can be assigned)
az ad app update --id "$ORDERS_APP_ID" --set appRoles='[
  {
    "id": "'$(uuidgen)'",
    "value": "Orders.Admin",
    "displayName": "Orders Administrator",
    "description": "Can manage all orders and configuration",
    "isEnabled": true,
    "allowedMemberTypes": ["User", "Application"]
  }
]'

# ── Register the Web App (confidential client) ────────────────────────
az ad app create \
  --display-name "Orders Web App" \
  --web-redirect-uris "https://myapp.com/auth/callback" \
  --sign-in-audience AzureADMyOrg

WEB_APP_ID=$(az ad app list --display-name "Orders Web App" --query "[0].appId" -o tsv)

# Create client secret
az ad app credential reset \
  --id "$WEB_APP_ID" \
  --display-name "prod-secret" \
  --end-date "2027-01-01"

{
  "AzureAd": {
    "Instance":    "https://login.microsoftonline.com/",
    "TenantId":    "<your-tenant-id>",
    "ClientId":    "<orders-api-app-id>",
    "Audience":    "api://orders-api",
    "ClientSecret": "@Microsoft.KeyVault(VaultName=myVault;SecretName=orders-api-client-secret)"
  }
}

// Extension methods for clean claim extraction
public static class ClaimsPrincipalExtensions
{
    // Get the stable user identity (use oid, not sub)
    public static string GetUserId(this ClaimsPrincipal principal)
        => principal.FindFirstValue("oid")
           ?? throw new UnauthorizedAccessException("oid claim missing");

    public static string GetTenantId(this ClaimsPrincipal principal)
        => principal.FindFirstValue("tid")
           ?? throw new UnauthorizedAccessException("tid claim missing");

    // Check delegated scope (user present)
    public static bool HasScope(this ClaimsPrincipal principal, string scope)
    {
        var scopes = principal.FindFirstValue("scp")?.Split(' ') ?? [];
        return scopes.Contains(scope, StringComparer.OrdinalIgnoreCase);
    }

    // Check app role (user or app-only)
    public static bool HasAppRole(this ClaimsPrincipal principal, string role)
    {
        var roles = principal.FindAll("roles").Select(c => c.Value);
        return roles.Contains(role, StringComparer.OrdinalIgnoreCase);
    }

    // Detect app-only token (no user — service-to-service)
    public static bool IsAppOnlyToken(this ClaimsPrincipal principal)
        => principal.FindFirstValue("idtyp") == "app";
}

// Usage in endpoint handler
private static async Task<IResult> GetSensitiveOrderAsync(
    Guid id, ClaimsPrincipal user, ISender sender, CancellationToken ct)
{
    // Fine-grained check beyond what the [Authorize] policy covers
    if (!user.HasScope("Orders.Read") && !user.HasAppRole("Orders.Admin"))
        return Results.Forbid();

    var userId = user.IsAppOnlyToken() ? "service-account" : user.GetUserId();
    // ...
}

// B2C uses a different authority format (policy-specific)
builder.Services
    .AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer("B2C", options =>
    {
        var b2cTenant = builder.Configuration["AzureAdB2C:TenantName"]; // myb2ctenant
        var policy    = builder.Configuration["AzureAdB2C:SignInPolicy"]; // B2C_1_SignUpSignIn
        var clientId  = builder.Configuration["AzureAdB2C:ClientId"];

        options.Authority =
            $"https://{b2cTenant}.b2clogin.com/{b2cTenant}.onmicrosoft.com/{policy}/v2.0";

        options.Audience = clientId;  // B2C uses clientId as audience

        options.TokenValidationParameters = new TokenValidationParameters
        {
            ValidateIssuerSigningKey = true,
            ValidateIssuer           = true,
            ValidateAudience         = true,
            ValidateLifetime         = true,
            NameClaimType            = "name",
            // B2C custom claims
            // "emails", "city", "postalCode", etc. per user flow config
        };
    });

// Declare your API as CAE-capable in JWT validation
// This tells Entra ID to send long-lived tokens (up to 28h)
// but allows near-real-time revocation

builder.Services
    .AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer(options =>
    {
        // ... standard config ...

        options.Events = new JwtBearerEvents
        {
            OnTokenValidated = ctx =>
            {
                // Check for CAE claims_challenge — client must re-authenticate
                var token = ctx.SecurityToken as JsonWebToken;
                var xmsCc = token?.Claims.FirstOrDefault(c => c.Type == "xms_cc");

                if (xmsCc?.Value.Contains("cp1") == true)
                {
                    // Client declared CAE-capable — long-lived token in use
                    // Entra ID will call your API's introspection endpoint on revocation
                    ctx.HttpContext.Items["CAE_Enabled"] = true;
                }
                return Task.CompletedTask;
            },
            OnChallenge = ctx =>
            {
                // If token rejected due to CAE event, respond with claims challenge
                // Client must request a fresh token with step-up auth
                if (ctx.AuthenticateFailure?.Message.Contains("Lifetime validation failed") == true)
                {
                    ctx.Response.Headers["WWW-Authenticate"] +=
                        ", claims="" + BuildClaimsChallenge() + """;
                }
                return Task.CompletedTask;
            }
        };
    });

// Complete security setup — Orders.Api/Program.cs

var builder = WebApplication.CreateBuilder(args);

// ── 1. Configuration from Key Vault (no secrets in appsettings.json) ──
builder.Configuration.AddAzureKeyVault(
    new Uri("https://myvault.vault.azure.net/"),
    new DefaultAzureCredential());

// ── 2. Authentication — Entra ID JWT Bearer ────────────────────────────
builder.Services
    .AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer(options =>
    {
        options.Authority = $"https://login.microsoftonline.com/{tenantId}/v2.0";
        options.Audience  = "api://orders-api";
        options.TokenValidationParameters = new()
        {
            ValidateIssuerSigningKey = true,
            ValidateLifetime         = true,
            ClockSkew                = TimeSpan.FromMinutes(5),
        };
    });

// ── 3. Authorization policies ──────────────────────────────────────────
builder.Services.AddAuthorizationBuilder()
    .AddPolicy("Orders.Read",  p => p.RequireClaim("scp",   "Orders.Read"))
    .AddPolicy("Orders.Write", p => p.RequireClaim("scp",   "Orders.Write"))
    .AddPolicy("OrdersAdmin",  p => p.RequireClaim("roles", "Orders.Admin"))
    .AddPolicy("S2S",          p => p.RequireClaim("idtyp", "app"));

// ── 4. Rate Limiting ───────────────────────────────────────────────────
builder.Services.AddRateLimiter(o =>
{
    o.AddFixedWindowLimiter("perUser", opts =>
    {
        opts.Window        = TimeSpan.FromMinutes(1);
        opts.PermitLimit   = 100;
        opts.QueueLimit    = 10;
        opts.PartitionKey  = ctx => ctx.User.FindFirstValue("oid") ?? "anonymous";
    });
});

// ── 5. CORS (if browser clients) ───────────────────────────────────────
builder.Services.AddCors(o => o.AddPolicy("AllowSPA", p =>
    p.WithOrigins("https://myapp.com")
     .AllowAnyMethod()
     .WithHeaders("Authorization", "Content-Type")));

var app = builder.Build();

// ── 6. Security middleware pipeline (ORDER MATTERS) ────────────────────
app.UseHttpsRedirection();
app.UseCors("AllowSPA");
app.UseAuthentication();    // Must be before UseAuthorization
app.UseAuthorization();
app.UseRateLimiter();

// ── 7. Security response headers ──────────────────────────────────────
app.Use(async (ctx, next) =>
{
    ctx.Response.Headers["X-Content-Type-Options"] = "nosniff";
    ctx.Response.Headers["X-Frame-Options"]         = "DENY";
    ctx.Response.Headers["Referrer-Policy"]         = "no-referrer";
    ctx.Response.Headers["Permissions-Policy"]      = "geolocation=(), camera=()";
    ctx.Response.Headers["Strict-Transport-Security"] = "max-age=31536000; includeSubDomains";
    await next();
});

// ── 8. Endpoint mapping with layered authorization ─────────────────────
var orders = app.MapGroup("/api/v1/orders")
    .RequireAuthorization()           // Must have valid token minimum
    .WithOpenApi()
    .RequireRateLimiting("perUser");

orders.MapGet("/",       GetOrders).RequireAuthorization("Orders.Read");
orders.MapPost("/",      CreateOrder).RequireAuthorization("Orders.Write");
orders.MapDelete("/{id}", DeleteOrder).RequireAuthorization("OrdersAdmin");

// Return structured error responses for security failures
builder.Services.AddProblemDetails(options =>
{
    options.CustomizeProblemDetails = ctx =>
    {
        ctx.ProblemDetails.Extensions["traceId"] =
            Activity.Current?.Id ?? ctx.HttpContext.TraceIdentifier;
        ctx.ProblemDetails.Extensions["timestamp"] = DateTime.UtcNow;

        // Don't leak stack traces in production
        if (!ctx.HttpContext.RequestServices
            .GetRequiredService<IHostEnvironment>().IsDevelopment())
        {
            ctx.ProblemDetails.Extensions.Remove("exception");
        }
    };
});

// Custom 401 / 403 handlers
app.UseStatusCodePages(async ctx =>
{
    if (ctx.HttpContext.Response.StatusCode == 401)
    {
        await ctx.HttpContext.Response.WriteAsJsonAsync(new ProblemDetails
        {
            Type   = "https://tools.ietf.org/html/rfc7235#section-3.1",
            Title  = "Unauthorized",
            Status = 401,
            Detail = "A valid Bearer token is required. Obtain one from Entra ID."
        });
    }
    else if (ctx.HttpContext.Response.StatusCode == 403)
    {
        await ctx.HttpContext.Response.WriteAsJsonAsync(new ProblemDetails
        {
            Type   = "https://tools.ietf.org/html/rfc7231#section-6.5.3",
            Title  = "Forbidden",
            Status = 403,
            Detail = "Insufficient permissions. Required scope or role not present in token."
        });
    }
});