roduction keys.

using Microsoft.AspNetCore.Authentication.JwtBearer;
using Microsoft.IdentityModel.Tokens;

var builder = WebApplication.CreateBuilder(args);

// Register Authentication with multiple schemes
builder.Services.AddAuthentication(options =>
{
    options.DefaultAuthenticateScheme = JwtBearerDefaults.AuthenticationScheme;
    options.DefaultChallengeScheme = JwtBearerDefaults.AuthenticationScheme;
    options.DefaultSignInScheme = CookieAuthenticationDefaults.AuthenticationScheme;
})
.AddJwtBearer(JwtBearerDefaults.AuthenticationScheme, options =>
{
    options.TokenValidationParameters = new TokenValidationParameters
    {
        ValidateIssuer = true,
        ValidateAudience = true,
        ValidateLifetime = true,
        ValidateIssuerSigningKey = true,
        ValidIssuer = builder.Configuration["Jwt:Issuer"],
        ValidAudience = builder.Configuration["Jwt:Audience"],
        IssuerSigningKey = new SymmetricSecurityKey(
            Encoding.UTF8.GetBytes(builder.Configuration["Jwt:Key"]!)),
        ClockSkew = TimeSpan.Zero // Enforce strict expiration
    };
    
    // Custom event handling for logging and diagnostics
    options.Events = new JwtBearerEvents
    {
        OnAuthenticationFailed = context =>
        {
            // Log specific failure reasons
            return Task.CompletedTask;
        },
        OnTokenValidated = context =>
        {
            // Enrich claims or check against a blacklist
            return Task.CompletedTask;
        }
    };
})
.AddCookie(CookieAuthenticationDefaults.AuthenticationScheme, options =>
{
    options.Cookie.HttpOnly = true;
    options.Cookie.SameSite = SameSiteMode.Strict;
    options.Cookie.SecurePolicy = CookieSecurePolicy.Always;
    options.ExpireTimeSpan = TimeSpan.FromHours(1);
    options.SlidingExpiration = false;
});

// Register Authorization with Policies
builder.Services.AddAuthorization(options =>
{
    options.AddPolicy("AdminAccess", policy => 
        policy.RequireClaim("role", "admin"));
    options.AddPolicy("MfaRequired", policy => 
        policy.RequireAssertion(context => 
            context.User.HasClaim(c => c.Type == "mfa_verified" && c.Value == "true")));
});

2. Middleware Pipeline Orchestration

The order of middleware is critical. UseAuthentication must precede UseAuthorization. Authentication resolves the user identity; Authorization enforces policies based on that identity.

var app = builder.Build();

// Strict HTTPS redirection
app.UseHsts();
app.UseHttpsRedirection();

// Static files, CORS, and Routing
app.UseRouting();

// Authentication and Authorization Middleware
app.UseAuthentication();
app.UseAuthorization();

app.MapControllers();
app.Run();

3. Token Generation and Refresh Pattern

Stateless JWTs require a refresh mechanism to balance security (short-lived access tokens) and usability. Implement a token service that issues both tokens and manages refresh token storage securely.

public class TokenService
{
    private readonly IConfiguration _config;
    private readonly IDistributedCache _cache; // For refresh token storage

    public TokenService(IConfiguration config, IDistributedCache cache)
    {
        _config = config;
        _cache = cache;
    }

    public async Task<TokenResponse> GenerateTokensAsync(User user)
    {
        var securityKey = new SymmetricSecurityKey(
            Encoding.UTF8.GetBytes(_config["Jwt:Key"]!));
        var credentials = new SigningCredentials(securityKey, SecurityAlgorithms.HmacSha256);

        var claims = new[]
        {
            new Claim(JwtRegisteredClaimNames.Sub, user.Id.ToString()),
            new Claim(JwtRegisteredClaimNames.Email, user.Email),
            new Claim("role", user.Role),
            new Claim(JwtRegisteredClaimNames.Jti, Guid.NewGuid().ToString())
        };

        var token = new JwtSecurityToken(
            issuer: _config["Jwt:Issuer"],
            audience: _config["Jwt:Audience"],
            claims: claims,
            expires: DateTime.UtcNow.AddMinutes(15), // Short-lived access token
            signingCredentials: credentials
        );

        var accessToken = new JwtSecurityTokenHandler().WriteToken(token);
        var refreshToken = Guid.NewGuid().ToString();

        // Store refresh token with expiration
        var refreshEntry = new DistributedCacheEntryOptions
        {
            AbsoluteExpirationRelativeToNow = TimeSpan.FromDays(7),
            SlidingExpiration = TimeSpan.FromDays(1)
        };
        await _cache.SetStringAsync($"refresh:{user.Id}", refreshToken, refreshEntry);

        return new TokenResponse { AccessToken = accessToken, RefreshToken = refreshToken };
    }
}

4. Claims Transformation for Dynamic Data

Authentication establishes identity, but authorization often requires fresh data. Use IClaimsTransformation to enrich the principal with database lookups or external service checks without re-authenticating.

public class DynamicClaimsTransformer : IClaimsTransformation
{
    private readonly IUserRepository _repo;

    public DynamicClaimsTransformer(IUserRepository repo) => _repo = repo;

    public async Task<ClaimsPrincipal> TransformAsync(ClaimsPrincipal principal)
    {
        if (principal.Identity?.IsAuthenticated != true) return principal;

        var userId = principal.FindFirstValue(JwtRegisteredClaimNames.Sub);
        if (userId == null) return principal;

        var user = await _repo.GetUserAsync(Guid.Parse(userId));
        if (user == null) return principal;

        var identity = (ClaimsIdentity)principal.Identity;
        
        // Add fresh claims from database
        identity.AddClaims(new[]
        {
            new Claim("tenant_id", user.TenantId.ToString()),
            new Claim("department", user.Department)
        });

        return principal;
    }
}

// Registration
builder.Services.AddTransient<IClaimsTransformation, DynamicClaimsTransformer>();

Pitfall Guide

Production authentication failures rarely stem from algorithmic weaknesses; they result from implementation errors and configuration drift. The following pitfalls represent the most common failure modes observed in .NET deployments.

1. Missing UseAuthorization Middleware: Developers often configure authentication services and decorate controllers with [Authorize], but omit app.UseAuthorization() in the pipeline. The middleware does not enforce policies; it only executes them. Without the middleware, authorization attributes are ignored, leaving endpoints accessible.
2. Ignoring ClockSkew in Token Validation: Default JWT validation includes a 5-minute clock skew tolerance. In distributed systems with significant time drift, this can allow replay attacks or premature token usage. Set ClockSkew = TimeSpan.Zero and ensure all servers sync via NTP.
3. Storing PII in JWT Claims: JWTs are signed but not encrypted. Any party with the token can decode and read claims. Storing sensitive data like email addresses, SSNs, or internal IDs exposes this data to clients and logs. Use opaque references or minimize claims to essential identifiers.
4. Algorithm Confusion (HS256 vs. RS256): Using symmetric algorithms (HS256) requires sharing the secret key with clients, which is a security violation. Always use asymmetric algorithms (RS256 or ES256) for JWTs where the client only needs the public key for verification, and the server holds the private key.
5. Refresh Token Rotation Failure: Failing to implement refresh token rotation allows stolen refresh tokens to be used indefinitely. Implement rotation where a refresh token can only be used once, and the old token is invalidated immediately upon generating a new pair. Store refresh tokens in a hashed format in the database to prevent theft of the actual tokens.
6. CSRF Vulnerabilities with Cookies: If using cookies for API authentication, ensure SameSite is set to Strict or Lax. For cross-origin scenarios requiring cookies, implement anti-forgery tokens. Never rely solely on HttpOnly cookies for cross-site requests without CSRF protection.
7. Hardcoded Secrets in appsettings.json: Embedding signing keys or connection strings in source control is a critical risk. Use Azure Key Vault, AWS Secrets Manager, or Docker secrets. In development, use User Secrets (dotnet user-secrets) to prevent accidental commits.

Production Bundle

Action Checklist

• Enforce HTTPS/HSTS: Configure UseHsts and UseHttpsRedirection to prevent downgrade attacks and ensure tokens are never transmitted in cleartext.
• Implement Rate Limiting: Apply rate limiting to authentication endpoints (login, token refresh) to mitigate brute-force and credential stuffing attacks.
• Configure CORS Strictly: Define explicit allowed origins for authentication endpoints. Avoid AllowAnyOrigin in production, as it undermines cookie security and token protection.
• Enable Audit Logging: Log authentication events including successful logins, failures, token issuances, and privilege escalations. Correlate logs with request IDs for forensic analysis.
• Key Rotation Strategy: Implement automated rotation for signing keys. Use a key management service that supports versioning, allowing clients to fetch new keys via .well-known/openid-configuration without downtime.
• Validate Token Lifecycle: Ensure access tokens have short lifespans (15 minutes) and refresh tokens have absolute expiration (7-30 days). Implement immediate revocation for sensitive operations.
• Test Authorization Policies: Write integration tests that verify policies reject unauthorized users and accept authorized ones. Test edge cases like missing claims and expired tokens.

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Single Page Application (SPA)	JWT with Short TTL + Refresh Token	Decoupled client requires stateless auth; refresh tokens maintain session security.	Low infrastructure cost; moderate dev complexity for token management.
Server-Rendered Web App	Cookie-Based Authentication	Built-in CSRF protection; lower latency; seamless session management via framework.	Low cost; minimal dev overhead; high security posture.
High-Risk Financial API	Reference Tokens (Opaque)	Immediate revocation capability; no PII exposure; strict server-side control.	High latency cost; requires distributed cache or DB lookup per request.
Microservices Mesh	JWT with Mutual TLS	Service-to-service auth requires high performance; JWT avoids network hops; mTLS adds transport security.	Moderate cost; requires PKI management and key distribution.
Mobile Application	JWT with Biometric Binding	Mobile clients need offline capability; binding tokens to device biometrics prevents token theft usage.	Moderate cost; requires secure enclave integration on client.

Configuration Template

Copy this configuration into appsettings.json and adjust values for your environment. Never commit production secrets.

{
  "Jwt": {
    "Issuer": "https://auth.yourdomain.com",
    "Audience": "https://api.yourdomain.com",
    "Key": "Your-256-Bit-Secret-Here-Use-KeyVault-In-Prod",
    "AccessTokenExpirationMinutes": 15,
    "RefreshTokenExpirationDays": 7
  },
  "Cors": {
    "AllowedOrigins": [
      "https://app.yourdomain.com",
      "https://admin.yourdomain.com"
    ]
  },
  "Security": {
    "RequireHttpsMetadata": true,
    "ClockSkewSeconds": 0,
    "MaxFailedLoginAttempts": 5,
    "LockoutDurationMinutes": 30
  }
}

Quick Start Guide

1. Initialize Project: Run dotnet new webapi -n SecureApi and navigate to the directory.
2. Install Packages: Execute dotnet add package Microsoft.AspNetCore.Authentication.JwtBearer and dotnet add package Microsoft.AspNetCore.Identity.
3. Configure Services: Add the authentication and authorization code from the Core Solution to Program.cs. Replace placeholder keys with secrets from dotnet user-secrets init and dotnet user-secrets set.
4. Run and Test: Start the application with dotnet run. Use a tool like Postman or curl to request a token from a login endpoint and access a protected controller with the Authorization: Bearer <token> header. Verify that requests without tokens return 401 Unauthorized.

This implementation provides a hardened, scalable foundation for ASP.NET Core authentication. Adhere to the pitfall guidelines and production checklist to maintain security integrity as the system evolves.