plan-forge auth.instructions.md

.NET Authentication & Authorization

Middleware Pipeline Order

// ⚠️ ORDER MATTERS — incorrect ordering breaks auth silently
var app = builder.Build();

app.UseHttpsRedirection();
app.UseCors();
app.UseAuthentication();   // 1. WHO are you? (parses token → ClaimsPrincipal)
app.UseAuthorization();    // 2. CAN you do this? (checks policies/roles)
app.UseRateLimiter();
app.MapControllers();

JWT / OpenID Connect Setup

OIDC with Identity Provider (Entra ID / Auth0 / Keycloak)

builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer(options =>
    {
        options.Authority = builder.Configuration["Auth:Authority"];
        options.Audience = builder.Configuration["Auth:Audience"];
        options.RequireHttpsMetadata = !builder.Environment.IsDevelopment();

        options.TokenValidationParameters = new TokenValidationParameters
        {
            ValidateIssuer = true,
            ValidateAudience = true,
            ValidateLifetime = true,
            ValidateIssuerSigningKey = true,
            ClockSkew = TimeSpan.FromMinutes(1), // Default 5 min is too generous
            NameClaimType = "name",
            RoleClaimType = "roles",
        };

        // Map external claims to internal user context
        options.Events = new JwtBearerEvents
        {
            OnTokenValidated = context =>
            {
                var tenantId = context.Principal?.FindFirst("tenant_id")?.Value;
                if (!string.IsNullOrEmpty(tenantId))
                {
                    var identity = (ClaimsIdentity)context.Principal!.Identity!;
                    identity.AddClaim(new Claim("tenant_id", tenantId));
                }
                return Task.CompletedTask;
            },
        };
    });

Configuration (appsettings.json)

{
  "Auth": {
    "Authority": "https://login.microsoftonline.com/{tenant-id}/v2.0",
    "Audience": "api://{client-id}"
  }
}

Policy-Based Authorization