认证管道源码解析

简介

ASP.NET Core 的认证系统由认证处理器（AuthenticationHandler）、认证方案（AuthenticationScheme）和认证中间件组成。理解认证管道的内部流程，有助于实现自定义认证方案和排查认证问题。

特点

• 1.认证架构 — Scheme/Handler/Ticket 三层
• 2.Cookie 认证 — Cookie 认证流程深入
• 3.JWT 认证 — Bearer Token 验证流程
• 4.自定义认证 — 实现 AuthenticationHandler
• 5.Claims 管理 — 声明和角色的底层机制

认证架构

核心组件关系

// 认证系统核心组件：
// 1. IAuthenticationService — 认证服务入口
// 2. IAuthenticationHandler — 认证处理器（具体逻辑）
// 3. AuthenticationScheme — 认证方案（名称+处理器类型）
// 4. AuthenticationTicket — 认证票据（ClaimsPrincipal + Properties）
// 5. ClaimsPrincipal — 当前用户（包含 ClaimsIdentity）
// 6. AuthenticationMiddleware — 认证中间件

// 注册认证服务
builder.Services.AddAuthentication(options =>
{
    options.DefaultAuthenticateScheme = CookieAuthenticationDefaults.AuthenticationScheme;
    options.DefaultChallengeScheme = CookieAuthenticationDefaults.AuthenticationScheme;
    options.DefaultSignInScheme = CookieAuthenticationDefaults.AuthenticationScheme;
})
.AddCookie(options =>
{
    options.LoginPath = "/login";
    options.AccessDeniedPath = "/access-denied";
})
.AddJwtBearer(options =>
{
    options.Authority = "https://your-identity-server";
    options.Audience = "your-api";
});

// 中间件注册（顺序重要）
app.UseAuthentication(); // 认证：识别用户是谁
app.UseAuthorization();  // 授权：决定用户能做什么

认证中间件流程

// AuthenticationMiddleware 核心逻辑（简化版）
public class AuthenticationMiddleware
{
    private readonly RequestDelegate _next;

    public async Task Invoke(HttpContext context)
    {
        var authService = context.RequestServices.GetRequiredService<IAuthenticationService>();

        // 调用默认认证方案进行认证
        var result = await authService.AuthenticateAsync(
            context, context.Features.Get<IAuthenticateResultFeature>()?.Scheme?.Name
            ?? _defaultScheme);

        if (result.Succeeded)
        {
            // 设置 HttpContext.User
            context.User = result.Principal!;
        }

        // 将认证结果存入 Features
        context.Features.Set(new AuthenticationFeature
        {
            User = result.Principal ?? new ClaimsPrincipal(),
            Path = context.Request.Path,
            QueryString = context.Request.QueryString
        });

        await _next(context);
    }
}

// 认证结果
public class AuthenticateResult
{
    public ClaimsPrincipal? Principal { get; set; }  // 用户
    public AuthenticationProperties? Properties { get; set; } // 属性
    public AuthenticationTicket? Ticket { get; set; } // 票据
    public bool Succeeded => Ticket != null;
    public string? FailureMessage { get; set; }
}

Cookie 认证流程

Cookie 认证处理器

// CookieAuthenticationHandler 核心流程
// 1. AuthenticateAsync：从 Cookie 读取并验证
// 2. SignInAsync：创建认证 Cookie
// 3. SignOutAsync：删除认证 Cookie
// 4. ChallengeAsync：重定向到登录页

// 登录流程
[HttpPost("/login")]
public async Task<IActionResult> Login(LoginModel model)
{
    if (!ValidateUser(model.Username, model.Password))
        return Unauthorized();

    var claims = new List<Claim>
    {
        new(ClaimTypes.NameIdentifier, user.Id.ToString()),
        new(ClaimTypes.Name, user.Username),
        new(ClaimTypes.Role, user.Role),
        new("Department", user.Department),
        new(JwtRegisteredClaimNames.Jti, Guid.NewGuid().ToString())
    };

    var identity = new ClaimsIdentity(claims,
        CookieAuthenticationDefaults.AuthenticationScheme);
    var principal = new ClaimsPrincipal(identity);

    // SignInAsync 内部流程：
    // 1. 序列化 ClaimsPrincipal 为加密字符串
    // 2. 创建 AuthenticationTicket
    // 3. 使用 IDataProtector 加密
    // 4. 写入 Response.Cookies
    await HttpContext.SignInAsync(
        CookieAuthenticationDefaults.AuthenticationScheme,
        principal,
        new AuthenticationProperties
        {
            IsPersistent = true, // 持久 Cookie
            ExpiresUtc = DateTimeOffset.UtcNow.AddDays(7),
            AllowRefresh = true
        });

    return Ok();
}

// 登出流程
[HttpPost("/logout")]
public async Task<IActionResult> Logout()
{
    await HttpContext.SignOutAsync(
        CookieAuthenticationDefaults.AuthenticationScheme);
    return Ok();
}

// Cookie 验证事件
builder.Services.AddCookie(options =>
{
    options.Events = new CookieAuthenticationEvents
    {
        // 每次请求验证 Cookie 时触发
        OnValidatePrincipal = async context =>
        {
            // 检查用户是否仍有效（如：未被封禁）
            var userId = context.Principal?.FindFirst(ClaimTypes.NameIdentifier)?.Value;
            if (userId != null && await IsUserBannedAsync(int.Parse(userId)))
            {
                context.RejectPrincipal(); // 拒绝认证
                await context.HttpContext.SignOutAsync();
            }
        },
        // 重定向到登录页时
        OnRedirectToLogin = context =>
        {
            if (context.Request.Path.StartsWithSegments("/api"))
            {
                context.Response.StatusCode = 401;
                return Task.CompletedTask;
            }
            context.Response.Redirect(context.RedirectUri);
            return Task.CompletedTask;
        }
    };
});

JWT Bearer 认证

JWT 认证流程

// JwtBearerHandler 核心流程：
// 1. 从 Authorization 头读取 Bearer token
// 2. 验证签名、过期时间、颁发者
// 3. 解析 Claims
// 4. 创建 ClaimsPrincipal

// 配置 JWT 认证
builder.Services.AddJwtBearer(options =>
{
    options.TokenValidationParameters = new TokenValidationParameters
    {
        ValidateIssuer = true,
        ValidateAudience = true,
        ValidateLifetime = true,
        ValidateIssuerSigningKey = true,
        ValidIssuer = "your-app",
        ValidAudience = "your-api",
        IssuerSigningKey = new SymmetricSecurityKey(
            Encoding.UTF8.GetBytes("your-secret-key-at-least-32-characters"))
    };

    // 自定义事件
    options.Events = new JwtBearerEvents
    {
        OnTokenValidated = async context =>
        {
            var userId = context.Principal?.FindFirst(ClaimTypes.NameIdentifier)?.Value;
            if (userId != null)
            {
                // 附加更多 Claims
                var claims = new List<Claim>();
                var userRoles = await GetUserRolesAsync(int.Parse(userId));
                foreach (var role in userRoles)
                    claims.Add(new Claim(ClaimTypes.Role, role));

                var identity = (ClaimsIdentity)context.Principal!.Identity!;
                identity.AddClaims(claims);
            }
        },
        OnAuthenticationFailed = context =>
        {
            if (context.Exception is SecurityTokenExpiredException)
            {
                context.Response.Headers.Append("Token-Expired", "true");
            }
            return Task.CompletedTask;
        },
        OnChallenge = context =>
        {
            // 自定义 401 响应
            context.HandleResponse();
            context.Response.StatusCode = 401;
            context.Response.WriteAsJsonAsync(new
            {
                Error = "Unauthorized",
                Message = "Token 无效或已过期"
            });
            return Task.CompletedTask;
        }
    };
});

// 生成 JWT Token
public string GenerateToken(User user)
{
    var claims = new[]
    {
        new Claim(JwtRegisteredClaimNames.Sub, user.Id.ToString()),
        new Claim(JwtRegisteredClaimNames.Name, user.Username),
        new Claim(ClaimTypes.Role, user.Role),
        new Claim(JwtRegisteredClaimNames.Jti, Guid.NewGuid().ToString()),
        new Claim(JwtRegisteredClaimNames.Iat, DateTime.UtcNow.ToString())
    };

    var key = new SymmetricSecurityKey(Encoding.UTF8.GetBytes(_config["Jwt:Key"]!));
    var credentials = new SigningCredentials(key, SecurityAlgorithms.HmacSha256);

    var token = new JwtSecurityToken(
        issuer: _config["Jwt:Issuer"],
        audience: _config["Jwt:Audience"],
        claims: claims,
        expires: DateTime.UtcNow.AddHours(2),
        signingCredentials: credentials);

    return new JwtSecurityTokenHandler().WriteToken(token);
}

自定义认证处理器

API Key 认证

// 自定义认证方案
public class ApiKeyAuthenticationHandler : AuthenticationHandler<AuthenticationSchemeOptions>
{
    private readonly IUserService _userService;

    public ApiKeyAuthenticationHandler(
        IOptionsMonitor<AuthenticationSchemeOptions> options,
        ILoggerFactory logger,
        UrlEncoder encoder,
        ISystemClock clock,
        IUserService userService)
        : base(options, logger, encoder, clock)
    {
        _userService = userService;
    }

    protected override async Task<AuthenticateResult> HandleAuthenticateAsync()
    {
        // 从请求头读取 API Key
        if (!Request.Headers.TryGetValue("X-API-Key", out var apiKeyHeader))
        {
            return AuthenticateResult.NoResult();
        }

        var apiKey = apiKeyHeader.ToString();
        var user = await _userService.ValidateApiKeyAsync(apiKey);

        if (user == null)
        {
            return AuthenticateResult.Fail("Invalid API Key");
        }

        // 创建 Claims
        var claims = new[]
        {
            new Claim(ClaimTypes.NameIdentifier, user.Id.ToString()),
            new Claim(ClaimTypes.Name, user.Name),
            new Claim("ApiKey", apiKey)
        };

        var identity = new ClaimsIdentity(claims, Scheme.Name);
        var principal = new ClaimsPrincipal(identity);
        var ticket = new AuthenticationTicket(principal, Scheme.Name);

        return AuthenticateResult.Success(ticket);
    }
}

// 注册自定义认证
builder.Services.AddAuthentication()
    .AddScheme<AuthenticationSchemeOptions, ApiKeyAuthenticationHandler>(
        "ApiKey", options => { });

// 使用
[Authorize(AuthenticationSchemes = "ApiKey")]
app.MapGet("/api/data", () => "Protected data");

多认证方案组合

在实际项目中，往往需要同时支持多种认证方式（Cookie 用于页面、JWT 用于 API、API Key 用于第三方集成）。

// 多方案注册
builder.Services.AddAuthentication(options =>
{
    options.DefaultScheme = "Smart"; // 默认使用智能方案选择器
})
.AddCookie("Cookies", options =>
{
    options.LoginPath = "/login";
    options.ExpireTimeSpan = TimeSpan.FromHours(12);
})
.AddJwtBearer("Bearer", options =>
{
    options.TokenValidationParameters = new TokenValidationParameters
    {
        ValidateIssuer = true,
        ValidateAudience = true,
        ValidateLifetime = true,
        ValidateIssuerSigningKey = true,
        ValidIssuer = "your-app",
        ValidAudience = "your-api",
        IssuerSigningKey = new SymmetricSecurityKey(
            Encoding.UTF8.GetBytes("your-secret-key-at-least-32-characters"))
    };
})
.AddScheme<AuthenticationSchemeOptions, ApiKeyAuthenticationHandler>("ApiKey", null)
.AddPolicyScheme("Smart", "Smart Scheme Selector", options =>
{
    // 根据请求特征自动选择认证方案
    options.ForwardDefaultSelector = context =>
    {
        // API Key 请求
        if (context.Request.Headers.ContainsKey("X-API-Key"))
            return "ApiKey";

        // Authorization 头带有 Bearer
        var authHeader = context.Request.Headers.Authorization.ToString();
        if (authHeader.StartsWith("Bearer ", StringComparison.OrdinalIgnoreCase))
            return "Bearer";

        // 默认使用 Cookie（浏览器请求）
        return "Cookies";
    };
});

// 端点级别指定方案
app.MapGet("/api/data", [Authorize(AuthenticationSchemes = "Bearer,ApiKey")]
    () => "API data (JWT or API Key)");

app.MapGet("/dashboard", [Authorize(AuthenticationSchemes = "Cookies")]
    () => "Dashboard (Cookie only)");

Claims 转换与授权策略

// 自定义 Claims 转换：在认证后补充或修改 Claims
public class CustomClaimsTransformation : IClaimsTransformation
{
    private readonly IPermissionService _permissionService;

    public CustomClaimsTransformation(IPermissionService permissionService)
    {
        _permissionService = permissionService;
    }

    public async Task<ClaimsPrincipal> TransformAsync(ClaimsPrincipal principal)
    {
        var identity = principal.Identity as ClaimsIdentity;
        if (identity == null || !identity.IsAuthenticated)
            return principal;

        // 避免重复转换（每次请求都会调用）
        if (identity.HasClaim(c => c.Type == "PermissionsAdded"))
            return principal;

        var userId = identity.FindFirst(ClaimTypes.NameIdentifier)?.Value;
        if (userId == null) return principal;

        // 从数据库加载权限并添加为 Claims
        var permissions = await _permissionService.GetUserPermissionsAsync(int.Parse(userId));
        foreach (var permission in permissions)
        {
            identity.AddClaim(new Claim("Permission", permission));
        }
        identity.AddClaim(new Claim("PermissionsAdded", "true"));

        return principal;
    }
}

// 注册 Claims 转换
builder.Services.AddScoped<IClaimsTransformation, CustomClaimsTransformation>();

// 基于策略的授权
builder.Services.AddAuthorization(options =>
{
    // 基于角色的策略
    options.AddPolicy("AdminOnly", policy =>
        policy.RequireRole("Admin"));

    // 基于 Claim 的策略
    options.AddPolicy("CanEditPost", policy =>
        policy.RequireClaim("Permission", "post:edit"));

    // 复合策略
    options.AddPolicy("SeniorEditor", policy =>
    {
        policy.RequireRole("Editor");
        policy.RequireClaim("Department", "Content");
        policy.Requirements.Add(new MinimumAgeRequirement(25));
    });
});

// 自定义授权需求
public class MinimumAgeRequirement : IAuthorizationRequirement
{
    public int MinimumAge { get; }
    public MinimumAgeRequirement(int minimumAge) => MinimumAge = minimumAge;
}

public class MinimumAgeHandler : AuthorizationHandler<MinimumAgeRequirement>
{
    protected override Task HandleRequirementAsync(
        AuthorizationHandlerContext context,
        MinimumAgeRequirement requirement)
    {
        var ageClaim = context.User.FindFirst("Age");
        if (ageClaim != null && int.TryParse(ageClaim.Value, out var age) && age >= requirement.MinimumAge)
            context.Succeed(requirement);
        return Task.CompletedTask;
    }
}

// 注册处理器
builder.Services.AddSingleton<IAuthorizationHandler, MinimumAgeHandler>();

认证故障排查技巧

// 1. 启用认证详细日志
builder.Services.AddLogging(logging =>
{
    logging.AddFilter("Microsoft.AspNetCore.Authentication", LogLevel.Debug);
});

// 2. 认证诊断中间件
app.Use(async (context, next) =>
{
    var authService = context.RequestServices.GetRequiredService<IAuthenticationService>();
    var schemes = context.RequestServices.GetRequiredService<IAuthenticationSchemeProvider>();

    // 记录所有认证方案的结果
    foreach (var scheme in await schemes.GetAllSchemesAsync())
    {
        var result = await authService.AuthenticateAsync(context, scheme.Name);
        if (result.Succeeded)
        {
            var claims = result.Principal!.Claims.Select(c => $"{c.Type}={c.Value}");
            Console.WriteLine($"[Auth] Scheme: {scheme.Name}, User: {string.Join(", ", claims)}");
        }
        else if (result.Failure != null)
        {
            Console.WriteLine($"[Auth] Scheme: {scheme.Name}, Failed: {result.Failure.Message}");
        }
        else
        {
            Console.WriteLine($"[Auth] Scheme: {scheme.Name}, NoResult");
        }
    }

    await next();
});

// 3. Token 检查工具方法
public static class TokenDebugger
{
    public static void DumpToken(string token)
    {
        var handler = new JwtSecurityTokenHandler();
        var jwt = handler.ReadJwtToken(token);

        Console.WriteLine($"Issuer: {jwt.Issuer}");
        Console.WriteLine($"Audience: {string.Join(", ", jwt.Audiences)}");
        Console.WriteLine($"ValidFrom: {jwt.ValidFrom}");
        Console.WriteLine($"ValidTo: {jwt.ValidTo}");
        Console.WriteLine($"IsExpired: {jwt.ValidTo < DateTime.UtcNow}");
        Console.WriteLine("Claims:");
        foreach (var claim in jwt.Claims)
            Console.WriteLine($"  {claim.Type}: {claim.Value}");
    }
}

优点

• 1.灵活可扩展 — 支持多种认证方案并存
• 2.声明模型 — Claims 支持丰富的用户信息
• 3.事件驱动 — 各阶段可自定义处理
• 4.方案切换 — 不同端点使用不同认证方案

缺点

• 1.配置复杂 — 多种方案的组合配置
• 2.调试困难 — 认证失败原因不易追踪
• 3.中间件顺序 — Authentication 必须在 Authorization 之前
• 4.Cookie 大小 — 复杂 Claims 导致 Cookie 过大

总结

ASP.NET Core 认证系统基于 Scheme（方案）→ Handler（处理器）→ Ticket（票据）三层架构。AuthenticationMiddleware 在管道中调用默认方案进行认证，结果设置到 HttpContext.User。Cookie 认证通过 IDataProtector 加密 ClaimsPrincipal 写入 Cookie。JWT Bearer 从 Authorization 头读取 Token，验证签名和过期后创建 ClaimsPrincipal。自定义处理器继承 AuthenticationHandler<T>，实现 HandleAuthenticateAsync。通过 AuthenticationSchemes 属性在端点级别选择认证方案。

关键知识点

• 先分清这个主题位于请求链路、后台任务链路还是基础设施链路。
• 服务端主题通常不只关心功能正确，还关心稳定性、性能和可观测性。
• 任何框架能力都要结合配置、生命周期、异常传播和外部依赖一起看。
• 安全类主题的关键不只在认证成功，而在于权限边界、证书信任链和审计链路是否完整。

项目落地视角

• 画清请求进入、业务执行、外部调用、日志记录和错误返回的完整路径。
• 为关键链路补齐超时、重试、熔断、追踪和结构化日志。
• 把配置与敏感信息分离，并明确不同环境的差异来源。
• 明确令牌生命周期、刷新策略、作用域、Claims 和失败返回模型。

常见误区

• 只会堆中间件或组件，不知道它们在链路中的执行顺序。
• 忽略生命周期和线程池、连接池等运行时资源约束。
• 没有监控和测试就对性能或可靠性下结论。
• 只验证登录成功，不验证权限收敛和令牌失效场景。

进阶路线

• 继续向运行时行为、可观测性、发布治理和微服务协同深入。
• 把主题和数据库、缓存、消息队列、认证授权联动起来理解。
• 沉淀团队级模板，包括统一异常处理、配置约定和基础设施封装。
• 继续深入零信任、细粒度授权、证书自动化和密钥轮换。

适用场景

• 当你准备把《认证管道源码解析》真正落到项目里时，最适合先在一个独立模块或最小样例里验证关键路径。
• 适合 API 服务、后台任务、实时通信、认证授权和微服务协作场景。
• 当需求开始涉及稳定性、性能、可观测性和发布流程时，这类主题会成为基础设施能力。

落地建议

• 先定义请求链路与失败路径，再决定中间件、过滤器、服务边界和依赖方式。
• 为关键链路补日志、指标、追踪、超时与重试策略。
• 环境配置与敏感信息分离，避免把生产参数写死在代码或镜像里。

排错清单

• 先确认问题发生在路由、模型绑定、中间件、业务层还是基础设施层。
• 检查 DI 生命周期、配置来源、序列化规则和认证上下文。
• 查看线程池、连接池、缓存命中率和外部依赖超时。

复盘问题

• 如果把《认证管道源码解析》放进你的当前项目，最先要验证的输入、输出和失败路径分别是什么？
• 《认证管道源码解析》最容易在什么规模、什么边界条件下暴露问题？你会用什么指标或日志去确认？
• 相比默认实现或替代方案，采用《认证管道源码解析》最大的收益和代价分别是什么？

延伸阅读

• 输出缓存深入
• 大文件上传与断点续传
• WebSocket 深入
• URL 路由深入