authentication

Authentication & Authorization Patterns

Reference for securing ASP.NET Core APIs. Covers JWT bearer, ASP.NET Identity, OIDC, policy-based authorization, and resource-based authorization. Used by dnp-planner, dnp-api-scaffolder, and dnp-tdd-developer-hard.

Quick Decision Guide

Scenario	Approach
API consumed by SPAs or mobile apps with an external IdP	JWT Bearer
Server-rendered app with local user accounts + roles	ASP.NET Identity
Federated login (Google, Entra ID, Keycloak)	OIDC + AddOpenIdConnect
Fine-grained permissions beyond roles	Policy-based + IAuthorizationHandler
Resource ownership check (user can only edit their own order)	Resource-based authorization

Required Pipeline Order

// Order matters — authentication must run before authorization
app.UseAuthentication();  // sets HttpContext.User
app.UseAuthorization();   // evaluates policies

JWT Bearer Authentication

builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer(options =>
    {
        // Authority issues and validates tokens (OIDC discovery endpoint)
        options.Authority = builder.Configuration["Auth:Authority"];
        options.Audience  = builder.Configuration["Auth:Audience"];

        options.TokenValidationParameters = new TokenValidationParameters
        {
            ValidateIssuer           = true,
            ValidateAudience         = true,
            ValidateLifetime         = true,
            ValidateIssuerSigningKey = true,
            // Zero skew — reject tokens within the default 5-minute grace window
            ClockSkew = TimeSpan.Zero
        };

        // Map non-standard claim names (e.g., Keycloak uses "preferred_username")
        options.MapInboundClaims = false;
        options.TokenValidationParameters.NameClaimType = "preferred_username";

        options.Events = new JwtBearerEvents
        {
            OnAuthenticationFailed = ctx =>
            {
                logger.LogWarning(ctx.Exception, "JWT authentication failed");
                return Task.CompletedTask;
            }
        };
    });

builder.Services.AddAuthorization();