ASP.NET Core Auth — ClockSkew Zero Locked Out 10K Users

Every production web application eventually asks the same question: who is this person, and can I trust what they are claiming? Get that wrong and you either lock out legitimate users or hand the keys to attackers. Authentication is not a framework checkbox. It is a system-level design choice that affects everything from token expiry handling and reverse proxy configuration to database modeling and incident response when something starts returning 401 at 2 AM.

ASP.NET Core ships with a first-class, pluggable authentication system that is significantly cleaner than the old OWIN model from classic ASP.NET. In .NET 8 and .NET 9, the model is mature: middleware-driven, scheme-based, strongly typed, and flexible enough to support cookies for browser apps, JWT bearer for APIs, OpenID Connect for enterprise SSO, and OAuth providers like Google or Microsoft in the same application.

What matters in production is not whether you can copy-paste AddJwtBearer() from a blog post. It is whether you understand what UseAuthentication() actually does, how the default scheme is resolved, why HttpContext.User is empty when middleware order is wrong, why reverse proxies break cookies unless forwarded headers are configured correctly, and why one overly aggressive security setting like ClockSkew = 0 can take out every user in the system.

By the end you will understand the authentication pipeline end to end, how ClaimsPrincipal and ClaimsIdentity actually fit together, how to configure cookie and JWT auth safely for 2026-era deployments, how Data Protection key management underpins every encrypted cookie in your system, and the production mistakes that separate clean rollouts from painful outages.

What Authentication in ASP.NET Core Actually Does

ASP.NET Core authentication is middleware-driven and scheme-based. That sounds abstract until you follow one request through the pipeline.

When app.UseAuthentication() runs, it does not blindly iterate over every registered handler. It calls IAuthenticationService.AuthenticateAsync() using the default authentication scheme unless an endpoint or policy specifies a different one. That service resolves the handler for the scheme, invokes it, and asks one question: can you authenticate this request?

If the handler succeeds, it returns an AuthenticateResult with a ClaimsPrincipal. The middleware assigns that principal to HttpContext.User. That is the whole point of UseAuthentication() — turning raw credentials into a principal the rest of the pipeline can trust.

If the handler returns NoResult, the request continues anonymously. If it fails, the failure is recorded and a later authorization challenge can turn that into a 401 or redirect depending on the scheme.

The scheme model is the architectural win here. You can register cookies, JWT bearer, OpenID Connect, API key auth, and custom HMAC auth side by side. Each scheme has a name, options, and a handler. The default scheme decides what happens when [Authorize] does not specify one explicitly. If you forget to set a default, the app becomes ambiguous in exactly the ways you do not want during an incident.

The most important type in the whole stack is ClaimsPrincipal. It is what ultimately lands in HttpContext.User. A ClaimsPrincipal can hold multiple ClaimsIdentity instances — one per successful authentication mechanism. That is how a hybrid app can support cookie auth for MVC pages and bearer auth for API endpoints in the same process without pretending they are the same thing.

In .NET 8 and .NET 9, the APIs are mature. The code is cleaner than it was in earlier Core releases, but the underlying rules have not changed: choose schemes deliberately, set a default explicitly, and get middleware order correct or nothing else matters.

using Microsoft.AspNetCore.Authentication;
using Microsoft.AspNetCore.Authentication.Cookies;
using Microsoft.AspNetCore.Authentication.JwtBearer;
using Microsoft.AspNetCore.HttpOverrides;
using Microsoft.IdentityModel.Tokens;
using System.Security.Claims;
using System.Text;

var builder = WebApplication.CreateBuilder(args);

// Explicit default scheme — never rely on implicit resolution
builder.Services.AddAuthentication(options =>
{
    options.DefaultAuthenticateScheme = JwtBearerDefaults.AuthenticationScheme;
    options.DefaultChallengeScheme = JwtBearerDefaults.AuthenticationScheme;
})
.AddJwtBearer(options =>
{
    options.TokenValidationParameters = new TokenValidationParameters
    {
        ValidateIssuer = true,
        ValidIssuer = builder.Configuration["Jwt:Issuer"],
        ValidateAudience = true,
        ValidAudience = builder.Configuration["Jwt:Audience"],
        ValidateLifetime = true,
        ClockSkew = TimeSpan.FromMinutes(5),
        ValidateIssuerSigningKey = true,
        IssuerSigningKey = new SymmetricSecurityKey(
            Encoding.UTF8.GetBytes(builder.Configuration["Jwt:SecretKey"]!))
    };
})
.AddCookie(CookieAuthenticationDefaults.AuthenticationScheme, options =>
{
    options.Cookie.HttpOnly = true;
    options.Cookie.SecurePolicy = CookieSecurePolicy.Always;
    options.Cookie.SameSite = SameSiteMode.Lax;
    options.ExpireTimeSpan = TimeSpan.FromMinutes(20);
    options.SlidingExpiration = true;
});

builder.Services.AddAuthorization();
builder.Services.AddControllers();

var app = builder.Build();

// If behind nginx, Apache, ALB, Azure Front Door, etc., this must run early
app.UseForwardedHeaders(new ForwardedHeadersOptions
{
    ForwardedHeaders = ForwardedHeaders.XForwardedFor | ForwardedHeaders.XForwardedProto
});

app.UseRouting();

// Authentication must run before Authorization
app.UseAuthentication();
app.UseAuthorization();

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

JWT Bearer Authentication — Stateless Tokens with Production Edge Cases

JWT bearer authentication is attractive because it is stateless. The API validates the token locally — signature, issuer, audience, expiry — and does not need to call the issuing server on every request. That is also where the sharp edges live. Stateless means revocation is harder, clock drift matters, token size matters, and every validation parameter is now part of your runtime security posture.

At minimum, a production JWT configuration should validate issuer, audience, signing key, and lifetime. If any of those are omitted, you are leaving one of the core trust assumptions unenforced.

ClockSkew is the parameter that gets teams in trouble because it looks like something you can tighten for extra security. The default in Microsoft.IdentityModel.Tokens is 5 minutes. That default is not permissive laziness. It is compensating for reality: distributed systems do not share a perfect clock. Even well-configured NTP still leaves you with small differences, and operational incidents are made of the cases where those differences are not small.

Setting ClockSkew = TimeSpan.Zero means nbf and exp are enforced with zero tolerance. If the validator is behind the issuer, nbf fails. If the validator is ahead, exp fails early. Either way, valid tokens become intermittently invalid. That is not a theoretical edge case — it is a production outage pattern.

A second trap is key rotation. If you hardcode a signing key and assume it changes only on deploy, your design is already obsolete. Modern identity systems rotate keys automatically. For OpenID Connect and cloud identity providers, use authority metadata and signing key resolution via configuration manager or IssuerSigningKeyResolver. Static keys are acceptable only for tightly controlled internal systems with a real rotation plan.

A third trap is token size. Large tokens do not just look ugly in devtools. They inflate every request header, stress proxies, and can exceed header limits in Kestrel, nginx, or upstream gateways. If your JWT is carrying dozens of permissions and nested claims blobs, that is not an auth design — it is a serialization accident.

using Microsoft.AspNetCore.Authentication.JwtBearer;
using Microsoft.IdentityModel.Protocols;
using Microsoft.IdentityModel.Protocols.OpenIdConnect;
using Microsoft.IdentityModel.Tokens;
using System.Security.Claims;
using System.Text;

namespace io.thecodeforge.csharp.auth;

public static class JwtBearerSetup
{
    public static void ConfigureJwtAuth(IServiceCollection services, IConfiguration config)
    {
        services.AddAuthentication(options =>
        {
            options.DefaultAuthenticateScheme = JwtBearerDefaults.AuthenticationScheme;
            options.DefaultChallengeScheme = JwtBearerDefaults.AuthenticationScheme;
        })
        .AddJwtBearer(options =>
        {
            options.TokenValidationParameters = new TokenValidationParameters
            {
                ValidateIssuer = true,
                ValidIssuer = config["Jwt:Issuer"],
                ValidateAudience = true,
                ValidAudience = config["Jwt:Audience"],
                ValidateLifetime = true,
                ClockSkew = TimeSpan.FromMinutes(5), // Never zero in distributed systems
                ValidateIssuerSigningKey = true,
                RoleClaimType = ClaimTypes.Role,
                NameClaimType = ClaimTypes.NameIdentifier,

                // Static symmetric key — acceptable only for tightly controlled internal systems.
                // For OIDC providers, prefer Authority/MetadataAddress and automatic key discovery.
                IssuerSigningKey = new SymmetricSecurityKey(
                    Encoding.UTF8.GetBytes(config["Jwt:SecretKey"]!))
            };

            // If using OpenID Connect or rotating keys, set Authority instead of a static key.
            // options.Authority = config["Jwt:Authority"];
            // options.MetadataAddress = config["Jwt:MetadataAddress"];
            // options.RequireHttpsMetadata = true;

            // Optional: custom key resolution for advanced rotation scenarios.
            // Do NOT return an empty list here — that would break all validation.
            options.TokenValidationParameters.IssuerSigningKeyResolver = (token, securityToken, kid, parameters) =>
            {
                return parameters.IssuerSigningKey is not null
                    ? new[] { parameters.IssuerSigningKey }
                    : Array.Empty<SecurityKey>();
            };

            options.Events = new JwtBearerEvents
            {
                OnTokenValidated = async context =>
                {
                    try
                    {
                        var identity = context.Principal?.Identity as ClaimsIdentity;
                        var userId = context.Principal?.FindFirst(ClaimTypes.NameIdentifier)?.Value;

                        if (identity is null || string.IsNullOrWhiteSpace(userId))
                        {
                            context.Fail("Missing user identifier claim.");
                            return;
                        }

                        // Example: attach a tenant claim from a fast cache or in-memory lookup.
                        // Keep this cheap. Expensive DB calls here turn auth into a latency tax.
                        identity.AddClaim(new Claim("auth_pipeline_version", "2026.1"));
                    }
                    catch (Exception ex)
                    {
                        context.Fail($"Token validation pipeline failed: {ex.Message}");
                    }
                },
                OnAuthenticationFailed = context =>
                {
                    // Useful for diagnostics. Do not leak full failure details to clients.
                    context.NoResult();
                    return Task.CompletedTask;
                }
            };

            // Increase token size if you absolutely must — but first ask why your token is that large.
            options.MaxTokenSizeInBytes = 16 * 1024;
        });
    }
}

Cookie Authentication — Stateful Sessions with Real Security Controls

Cookie authentication is still the best fit for browser-based applications in ASP.NET Core. It is stateful in the practical sense that the browser carries an encrypted authentication ticket, and the server decrypts and validates that ticket on every request. It integrates naturally with redirects, anti-forgery, and per-request revocation. It is not old-fashioned. It is the right tool for the browser problem.

The problem is that most cookie authentication issues are configuration issues, not framework issues.

CookieSecurePolicy is one of the most misunderstood settings in the stack. AddCookie() does not magically switch defaults between development and production. Its default behavior is None unless you explicitly set it. That means if you do nothing, the framework will happily issue cookies over HTTP. In development that is convenient. In production it is negligent. Set it deliberately.

For most production applications, CookieSecurePolicy.Always is correct. If the app sits behind a reverse proxy that terminates TLS, SameAsRequest can also be correct — but only if forwarded headers are configured first so Request.IsHttps reflects the original client scheme. Without forwarded headers, SameAsRequest behaves like insecure HTTP on the app server side.

Sliding expiration is the usability feature that becomes a security problem when teams misunderstand it. It extends the session on activity, which is good for real users. It also extends the session for whoever currently holds the cookie. That means a stolen cookie remains useful as long as the attacker stays active. Sliding expiration is fine — but pair it with an absolute expiration policy and a revocation check through OnValidatePrincipal.

And do not forget the physical size of the cookie. Authentication cookies are encrypted, signed, and base64-encoded. Large claim sets turn into large headers. Browsers, proxies, and Kestrel all have limits. A 10KB auth cookie is not a nice problem to have. It is evidence that your session payload contains things that should live in a database or cache instead.

using Microsoft.AspNetCore.Authentication;
using Microsoft.AspNetCore.Authentication.Cookies;
using System.Security.Claims;

namespace io.thecodeforge.csharp.auth;

public static class CookieAuthConfig
{
    public static void ConfigureCookieAuth(IServiceCollection services, IConfiguration config)
    {
        services.AddAuthentication(options =>
        {
            options.DefaultAuthenticateScheme = CookieAuthenticationDefaults.AuthenticationScheme;
            options.DefaultChallengeScheme = CookieAuthenticationDefaults.AuthenticationScheme;
        })
        .AddCookie(options =>
        {
            // Never rely on defaults — AddCookie() defaults to CookieSecurePolicy.None.
            options.Cookie.SecurePolicy = CookieSecurePolicy.Always;
            options.Cookie.HttpOnly = true;
            options.Cookie.SameSite = SameSiteMode.Lax;
            options.ExpireTimeSpan = TimeSpan.FromMinutes(20);
            options.SlidingExpiration = true;

            options.Events = new CookieAuthenticationEvents
            {
                OnValidatePrincipal = async context =>
                {
                    var userId = context.Principal?.FindFirst(ClaimTypes.NameIdentifier)?.Value;
                    if (string.IsNullOrWhiteSpace(userId))
                    {
                        context.RejectPrincipal();
                        await context.HttpContext.SignOutAsync();
                        return;
                    }

                    // Example: revoke session if password changed or user was disabled.
                    // Replace with a cache-backed version check or security stamp check.
                    var stillActive = await IsUserStillActiveAsync(userId);
                    if (!stillActive)
                    {
                        context.RejectPrincipal();
                        await context.HttpContext.SignOutAsync();
                    }
                }
            };
        });

        services.AddAuthorization();
    }

    private static Task<bool> IsUserStillActiveAsync(string userId)
    {
        // Replace with your real store or distributed cache lookup.
        return Task.FromResult(true);
    }
}

External OAuth and OpenID Connect — Where Real Deployments Break

External authentication in ASP.NET Core is usually sold as three lines of AddGoogle() or AddMicrosoftAccount() configuration. That is the demo version. The production version is an authentication flow that depends on exact redirect URIs, correlation cookies, forwarded headers, and browser cookie policy behavior. Most real failures happen in those moving parts, not in the provider itself.

The key concepts are simple but unforgiving. The redirect URI must match exactly what the identity provider has on file — scheme, host, port, path, and often trailing slash. The state parameter protects the flow against CSRF. The correlation cookie ties the outbound challenge to the inbound callback. If that cookie is missing on the callback request, the entire flow fails with a state or correlation error.

Why does that happen? Usually one of three reasons. First, the app is behind a reverse proxy, but forwarded headers are not configured, so ASP.NET Core generates an http callback URI instead of https. Second, the browser blocks the correlation cookie because SameSite or Secure settings do not match the cross-site redirect behavior. Third, the proxy or WAF strips or rewrites cookies on the callback path.

The fix is usually infrastructure-aware configuration, not changing provider secrets. UseForwardedHeaders() must run before authentication so the framework generates the right external URI and considers the request secure. Correlation cookies should use a secure policy explicitly. SameSite should usually be Lax unless the browser flow requires cross-site POST behavior, in which case you need None plus Secure.

Account linking is another place teams under-design. If the same person signs in with Google one day and Microsoft the next, is that one local user or two? Decide before launch. The provider's NameIdentifier or subject claim should map to a stable local user record, and your model should support multiple external logins per local account if your product needs it.

SaveTokens = true is useful when your application needs the external provider's access token later, but be aware of where those tokens live. In cookie-based sign-in flows, saved tokens often end up inside the authentication cookie. That can bloat cookie size quickly.

using Microsoft.AspNetCore.Authentication.Cookies;
using Microsoft.AspNetCore.Authentication.Google;
using System.Security.Claims;

namespace io.thecodeforge.csharp.auth;

public static class ExternalAuthSetup
{
    public static void ConfigureExternalAuth(IServiceCollection services, IConfiguration config)
    {
        services.AddAuthentication(options =>
        {
            options.DefaultScheme = CookieAuthenticationDefaults.AuthenticationScheme;
            options.DefaultChallengeScheme = GoogleDefaults.AuthenticationScheme;
        })
        .AddCookie(options =>
        {
            options.Cookie.SecurePolicy = CookieSecurePolicy.Always;
            options.Cookie.SameSite = SameSiteMode.Lax;
            options.Cookie.HttpOnly = true;
        })
        .AddGoogle(GoogleDefaults.AuthenticationScheme, options =>
        {
            options.ClientId = config["Google:ClientId"]!;
            options.ClientSecret = config["Google:ClientSecret"]!;
            options.SaveTokens = true;

            // Correlation cookie must survive the round trip.
            options.CorrelationCookie.SecurePolicy = CookieSecurePolicy.Always;
            options.CorrelationCookie.SameSite = SameSiteMode.Lax;

            options.ClaimActions.MapJsonKey(ClaimTypes.NameIdentifier, "sub");
            options.ClaimActions.MapJsonKey(ClaimTypes.Email, "email");
            options.ClaimActions.MapJsonKey(ClaimTypes.Name, "name");

            options.Events.OnCreatingTicket = context =>
            {
                if (context.Principal?.Identity is not ClaimsIdentity identity)
                    return Task.CompletedTask;

                var externalId = context.Identity?.FindFirst(ClaimTypes.NameIdentifier)?.Value;
                if (!string.IsNullOrWhiteSpace(externalId))
                {
                    identity.AddClaim(new Claim("external_id", externalId));
                }

                return Task.CompletedTask;
            };
        })
        .AddMicrosoftAccount("Microsoft", options =>
        {
            options.ClientId = config["Microsoft:ClientId"]!;
            options.ClientSecret = config["Microsoft:ClientSecret"]!;
            options.SaveTokens = true;
            options.CorrelationCookie.SecurePolicy = CookieSecurePolicy.Always;
            options.CorrelationCookie.SameSite = SameSiteMode.Lax;
        });
    }
}

Forwarded Headers, Reverse Proxies and the Authentication Failures Nobody Expects

This is the missing piece in a surprising number of ASP.NET Core authentication incidents: the app is not serving the internet directly. It sits behind nginx, Apache, IIS as reverse proxy, AWS ALB, Azure Front Door, Cloudflare, or some combination of those. TLS terminates at the proxy. The app itself receives plain HTTP from the proxy over an internal network.

If ASP.NET Core is not told to trust forwarded headers, it sees the request as HTTP. That matters immediately. Request.IsHttps is false. Request.Scheme is http. Any code that depends on those values — cookie secure policy, redirect URI generation, external OAuth callback generation, same-origin checks — now behaves as if the app is running on insecure HTTP even though the user reached it over HTTPS.

The downstream effects are ugly and non-obvious. Cookies marked Secure may not be issued. CookieSecurePolicy.SameAsRequest behaves like insecure HTTP because the app thinks the request is HTTP. OAuth redirect URIs are generated with http instead of https and rejected by the provider. Correlation cookies do not line up with the callback flow. You debug auth for three hours and the root cause is one missing middleware registration.

The fix is simple but must be done deliberately: configure and enable forwarded headers. Restrict known proxies or networks so you do not accept spoofed forwarded headers from arbitrary clients. And put UseForwardedHeaders() early in the pipeline, before anything reads Request.Scheme or Request.IsHttps.

This is not an optional deployment detail. In 2026, almost every production ASP.NET Core app runs behind some kind of proxy or gateway. If your auth review does not include forwarded headers, it is incomplete.

using Microsoft.AspNetCore.HttpOverrides;
using System.Net;

namespace io.thecodeforge.csharp.auth;

public static class ForwardedHeadersSetup
{
    public static void ConfigureForwardedHeaders(IServiceCollection services)
    {
        services.Configure<ForwardedHeadersOptions>(options =>
        {
            options.ForwardedHeaders =
                ForwardedHeaders.XForwardedFor |
                ForwardedHeaders.XForwardedProto |
                ForwardedHeaders.XForwardedHost;

            // Always restrict trusted proxies or networks in production.
            // Do not trust arbitrary X-Forwarded-* headers from the internet.
            options.KnownProxies.Add(IPAddress.Parse("10.0.0.10"));
            // Example alternative:
            // options.KnownNetworks.Add(new IPNetwork(IPAddress.Parse("10.0.0.0"), 24));
        });
    }

    public static void UseForwarding(WebApplication app)
    {
        // Must run before authentication and before anything using Request.Scheme or Request.IsHttps
        app.UseForwardedHeaders();
    }
}

Data Protection Key Management — The Backbone of Cookie Encryption

If your app uses cookie authentication, anti-forgery, TempData, or anything else built on ASP.NET Core's Data Protection system, then your operational security posture depends on one thing: the key ring. Lose it, split it, or rotate it badly and users get logged out or requests start failing in ways that look random until you know what you are looking at.

Data Protection generates keys automatically and stores them somewhere. In local development that somewhere is a local directory. In production, that default is often a trap. Containers restart. Pods reschedule. Instances scale out. Suddenly one node encrypts a cookie with a key ring the next node has never seen. Decryption fails. The user experiences a logout loop and the team starts blaming the load balancer.

The rule is simple: in any multi-instance environment, key storage must be shared and durable. Redis works. Azure Blob Storage works. A file share works if you truly understand the reliability and access model. Azure Key Vault is not a storage system for the key ring itself in the same way — it is commonly used to protect keys at rest or store the key encryption key while the key ring lives in Blob or Redis.

There is another layer to this that teams miss: application isolation. If multiple apps share the same underlying key store and you do not set ApplicationName explicitly, you are creating a subtle cross-app key ring problem that will be painful to debug later. Always set an application name.

And do not get clever with DisableAutomaticKeyGeneration unless you have a real operational key rotation process. That setting is not an advanced security move by default. It is a way to break encryption for every new cookie when the active key expires.

using Azure.Identity;
using Microsoft.AspNetCore.DataProtection;
using StackExchange.Redis;

namespace io.thecodeforge.csharp.auth;

public static class DataProtectionSetup
{
    public static void ConfigureDataProtection(IServiceCollection services, IConfiguration config, IWebHostEnvironment env)
    {
        if (env.IsProduction())
        {
            var redis = ConnectionMultiplexer.Connect(config["Redis:ConnectionString"]!);

            services.AddDataProtection()
                .PersistKeysToStackExchangeRedis(redis, "DataProtection-Keys")
                .ProtectKeysWithAzureKeyVault(
                    new Uri(config["KeyVault:KeyIdentifier"]!),
                    new DefaultAzureCredential())
                .SetDefaultKeyLifetime(TimeSpan.FromDays(30))
                .SetApplicationName("MyApp");

            // WARNING:
            // DisableAutomaticKeyGeneration() is dangerous unless you have a real, tested,
            // audited manual key rotation process. Most teams should NOT use it.
            // If the active key expires and no new key is generated, cookie encryption fails.
            // .DisableAutomaticKeyGeneration();
        }
        else
        {
            services.AddDataProtection()
                .SetApplicationName("MyApp");
        }
    }
}

Claims Transformation and Custom Authentication Events

Authentication is not always done when the token or cookie is validated. In many real systems you still need to enrich or validate identity after the framework says the credential is structurally valid. Maybe you need tenant context from a cache. Maybe a password change should invalidate an otherwise valid cookie. Maybe a user is disabled in your own database even though the external token is still valid.

ASP.NET Core gives you two primary ways to do this: scheme-specific events and cross-cutting claims transformation.

Scheme-specific events live in the handler configuration. OnTokenValidated for JWT. OnValidatePrincipal for cookies. These are the right choice when the logic belongs to one authentication mechanism and should run in that mechanism's lifecycle.

IClaimsTransformation is different. It runs after authentication and before authorization on every authenticated request regardless of scheme. That makes it useful for truly cross-cutting enrichment — but also dangerous if it hits a database on every request. If you put an uncached external lookup in IClaimsTransformation, you have converted authentication into a per-request latency tax.

The pattern that scales is simple: put stable claims into the token or cookie at sign-in time when you can. Use transformation only for data that must be evaluated dynamically. And if transformation does need external state, cache aggressively and think in terms of identity versioning or permission snapshots rather than live database reads per request.

using Microsoft.AspNetCore.Authentication;
using System.Security.Claims;

namespace io.thecodeforge.csharp.auth;

public sealed class CustomClaimsTransformer : IClaimsTransformation
{
    private readonly IUserPermissionService _permissionService;

    public CustomClaimsTransformer(IUserPermissionService permissionService)
    {
        _permissionService = permissionService;
    }

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

        var userId = principal.FindFirst(ClaimTypes.NameIdentifier)?.Value;
        if (string.IsNullOrWhiteSpace(userId))
            return principal;

        // Prevent duplicate claims on subsequent requests.
        if (principal.HasClaim(c => c.Type == "permission"))
            return principal;

        // Keep this lookup fast and cache-backed.
        var permissions = await _permissionService.GetUserPermissionsAsync(userId);

        var identity = new ClaimsIdentity();
        identity.AddClaims(permissions.Select(p => new Claim("permission", p)));
        principal.AddIdentity(identity);

        return principal;
    }
}

// Registration:
// services.AddTransient<IClaimsTransformation, CustomClaimsTransformer>();

The Authentication Handler Pipeline — Why `Authenticate`, `Challenge`, and `Forbid` Are Not Optional

Every authentication scheme in ASP.NET Core boils down to a handler. That handler implements three abstract methods: AuthenticateAsync, ChallengeAsync, and ForbidAsync. Junior devs treat these like ceremony. They aren't. They are the contract between your middleware and your auth logic. Authenticate validates credentials and returns an AuthenticateResult. Challenge is invoked when an unauthenticated user hits a restricted endpoint — it sends the 401 or redirects to a login page. Forbid triggers when they are authenticated but lack permission — that's your 403. If you override one and not the others, you break the invariant. I've seen teams wire custom OAuth flows and forget to implement Forbid, so unauthorized users silently get 200s with empty payloads. The RemoteAuthenticationHandler<TOptions> base class adds complexity: it handles redirects, callback validation, and state management for external providers. Use it when integrating Google, GitHub, or any OIDC provider. Use AuthenticationHandler<TOptions> for everything else — JWT, custom tokens, header-based auth. Understand the base class before you write a single line of handler code.

// io.thecodeforge
public class CustomTokenHandler : AuthenticationHandler<CustomTokenOptions>
{
    protected override async Task<AuthenticateResult> HandleAuthenticateAsync()
    {
        var token = Request.Headers["X-Api-Key"].FirstOrDefault();
        if (string.IsNullOrEmpty(token))
            return AuthenticateResult.NoResult();

        if (!_validTokens.Contains(token))
            return AuthenticateResult.Fail("Invalid API key");

        var claims = new[] { new Claim(ClaimTypes.Name, "service-account") };
        var identity = new ClaimsIdentity(claims, Scheme.Name);
        var principal = new ClaimsPrincipal(identity);
        var ticket = new AuthenticationTicket(principal, Scheme.Name);

        return AuthenticateResult.Success(ticket);
    }

    protected override async Task HandleChallengeAsync(AuthenticationProperties properties)
    {
        Response.StatusCode = 401;
        Response.ContentType = "application/json";
        await Response.WriteAsync("{\"error\":\"Authentication required\"}");
    }

    protected override async Task HandleForbiddenAsync(AuthenticationProperties properties)
    {
        Response.StatusCode = 403;
        Response.ContentType = "application/json";
        await Response.WriteAsync("{\"error\":\"Insufficient permissions\"}");
    }
}

Per-Tenant Authentication Schemes — Why One Size Fits Nobody

Multi-tenant applications often store auth configuration per tenant: different OIDC authorities, separate JWT audiences, custom cookie domains. The naive approach is to register one global scheme. That breaks when Tenant A uses Azure AD and Tenant B uses a self-hosted IdentityServer. You need per-tenant authentication. ASP.NET Core supports this through IAuthenticationSchemeProvider and dynamic scheme registration. On each request, inspect the tenant (via host header, path prefix, or custom header), then retrieve or create the appropriate scheme. The AddPolicyScheme can act as a router: it wraps multiple backend schemes and delegates to the correct one based on a policy. Alternatively, register a custom IAuthenticationSchemeProvider that caches schemes per tenant and handles cleanup on configuration changes. The critical pitfall: scheme names must be unique across all tenants. Prefix them with the tenant ID. Also, manage scheme lifecycle — unregister stale schemes when a tenant is deactivated. I've fixed production outages where stale tenant schemes returned 500s because the handler tried to validate against a deleted OIDC provider.

// io.thecodeforge
public class TenantSchemeProvider : AuthenticationSchemeProvider
{
    private readonly ITenantStore _tenants;
    private readonly ConcurrentDictionary<string, AuthenticationScheme> _schemes = new();

    public TenantSchemeProvider(IOptions<AuthenticationOptions> options, ITenantStore tenants)
        : base(options)
    {
        _tenants = tenants;
    }

    public override async Task<AuthenticationScheme?> GetSchemeAsync(string name)
    {
        if (_schemes.TryGetValue(name, out var scheme))
            return scheme;

        var tenantId = ExtractTenantFromName(name);
        var tenant = await _tenants.GetTenantAsync(tenantId);
        if (tenant == null) return null;

        var builder = new AuthenticationSchemeBuilder(name);
        builder.DisplayName = tenant.DisplayName;
        builder.HandlerType = typeof(JwtBearerHandler);
        scheme = builder.Build();
        _schemes[name] = scheme;

        return scheme;
    }

    private string ExtractTenantFromName(string name) => name.Split(':')[1];
}

// Registration in Program.cs:
builder.Services.AddSingleton<IAuthenticationSchemeProvider, TenantSchemeProvider>();
builder.Services.AddAuthentication().AddJwtBearer("tenant:tenant-a", null!);
builder.Services.AddJwtBearer("tenant:tenant-b", null!);