认证模块的注册这一步的本质是注册认证系统赖以生存的核心基础设施它不涉及任何具体的认证逻辑比如怎么读 Cookie、怎么解 JWT而是定义认证系统应该怎么运转。前面介绍过 Cookie 和 JWT 认证是怎么在代码里集成的它们有个共同点在启动类集成时都会加上这么一句。其实不光这两个任何认证方案都离不开下面这段代码。var authenticationBuilder builder.Services.AddAuthentication(options {});看名字就知道它是「添加身份认证」的意思返回一个 AuthenticationBuilder。那它到底添加了什么它是一个容器的扩展方法我们直接进它内部看实现。2.1 基础设施层先看 AuthenticationServiceCollectionExtensionspublic static AuthenticationBuilder AddAuthentication(this IServiceCollection services){// 添加认证核心组件services.AddAuthenticationCore();// 添加数据保护组件services.AddDataProtection();// 添加 Web 编码组件services.AddWebEncoders();// 添加时间处理组件services.TryAddSingletonISystemClock, SystemClock();// services.TryAddSingleton(TimeProvider.System); // .NET 8 改用这个// 添加认证配置的集中管理组件services.TryAddSingletonIAuthenticationConfigurationProvider, DefaultAuthenticationConfigurationProvider();return new AuthenticationBuilder(services);}这里就是认证模块最核心的几个组件注册它们是 .NET Core 认证平台提供的基础也是模块能跑起来的关键。逐个说一下AddDataProtection注册数据保护服务IDataProtectionProvider为认证模块提供加密能力。主要用来加密 Cookie 票据、保护 Token 签名密钥以及防止敏感数据被篡改。IAuthenticationConfigurationProvider负责从 IConfiguration 里加载认证相关的配置比如 JWT 的签发者Issuer、受众Audience、密钥来源这些。有了它认证方案就能从 appsettings.json 或环境变量里读配置不用硬编码。AddAuthenticationCore注册认证模块的核心服务包括执行认证、获取认证处理器、管理认证方案是整个认证功能的骨架。ISystemClock提供统一的 UTC 时间源在校验 Cookie、JWT 是否过期时调用。好处是单元测试时可以注入 Mock 来模拟时间变化。AddWebEncoders负责认证模块里一些 URL 的编解码工作比如处理回调 URL、编码 Cookie 数据、编解码令牌相关数据。可以这么理解加密保护、配置读取、核心服务、时间校验、数据编码这几块凑在一起共同构成了认证模块这套基础设施。image2.2 核心引擎 AddAuthenticationCore如果说 AddDataProtection 和 ISystemClock 是保证引擎正常运转的润滑油和电源那么 AddAuthenticationCore 就是这台引擎的缸体和曲轴——它定义了动力产生的核心逻辑。所以这部分我们主要围绕 AddAuthenticationCore 展开。用红花绿叶来打比方AddAuthenticationCore 就是那朵红花其他几个是衬托它的绿叶但绿叶也缺一不可。理解成「引擎」更贴切后面顺带也会简单聊下 IAuthenticationConfigurationProvider。看 AuthenticationCoreServiceCollectionExtensionspublic static IServiceCollection AddAuthenticationCore(this IServiceCollection services){if (services null){throw new ArgumentNullException(nameof(services));}services.TryAddScopedIAuthenticationService, AuthenticationService(); services.TryAddSingletonIClaimsTransformation, NoopClaimsTransformation(); // Can be replaced with scoped ones that use DbContext services.TryAddScopedIAuthenticationHandlerProvider, AuthenticationHandlerProvider(); services.TryAddSingletonIAuthenticationSchemeProvider, AuthenticationSchemeProvider(); return services;}AddAuthenticationCore() 里注册了 4 个关键服务。这段代码展示的是引擎内部的构造它不涉及任何具体的 Cookie 或 JWT只是单纯定义了「必须具备哪些功能」。当它执行完毕.NET Core 的认证舞台就具备了运转能力。image1认证入口 IAuthenticationService这是认证系统统一对外的接口默认实现是 AuthenticationService定义了 5 个核心方法public interface IAuthenticationService{// 1. 认证获取请求的任何认证数据如解析 Cookie/Token 得到用户身份Task AuthenticateAsync(HttpContext context, string scheme);// 2. 质询用于未经身份验证的请求如返回 401 状态码或重定向到登录页 Task ChallengeAsync(HttpContext context, string scheme, AuthenticationProperties properties); // 3. 禁止当已认证用户尝试访问不允许访问的资源时使用如返回 403 状态码 Task ForbidAsync(HttpContext context, string scheme, AuthenticationProperties properties); // 4. 登录建立关联将用户主体ClaimsPrincipal写入认证票据 Task SignInAsync(HttpContext context, string scheme, ClaimsPrincipal principal, AuthenticationProperties properties); // 5. 登出移除任何相关联的认证数据如清除 Cookie Task SignOutAsync(HttpContext context, string scheme, AuthenticationProperties properties);}参考上一篇的 Cookie 登录当我们在控制器里调用 HttpContext.SignInAsync() 时实际上就是在调用这个服务。不过它自己不干活只负责根据指令找到方案然后交给方案里具体的 Handler 去执行。你会发现这 5 个方法都要接收一个 scheme 参数。为什么都要一个 scheme 因为可能同时存在多个方案比如 Cookie JWT得明确告诉它这次操作针对的是哪个方案。2全局配置数据容器 AuthenticationOptionsAuthenticationOptions 是认证模块的全局配置容器内部维护了一个 SchemeMap 字典用来存储所有已注册方案的名称和对应的 AuthenticationSchemeBuilder。比如我们调用 AddCookie()最终就是往 SchemeMap 里加入 Cookie 方案。它主要存三部分信息默认方案如 DefaultAuthenticateScheme、DefaultChallengeScheme、DefaultSignInScheme、DefaultSignOutScheme、DefaultForbidScheme。方案列表所有已注册方案的名称和显示名称。方案与 Handler 的映射每个方案名称对应一个 AuthenticationSchemeBuilder其中包含了 HandlerType。它本身只是数据的容器具体的注册逻辑由 AddScheme 操作它具体的查询逻辑由 IAuthenticationSchemeProvider 读取它。3方案注册与字典管理 IAuthenticationSchemeProviderIAuthenticationSchemeProvider 负责管理所有注册过的认证方案Scheme默认实现是 AuthenticationSchemeProvider。当调用 AddCookie 或 AddJwtBearer 注册方案时这些方案信息比如名字叫 Cookies、对应的 Handler 类型是什么都会被存放到类似这样的字典里Dictionarystring, 方案 _schemes new ();_schemes.Add(“cookie”, “Cookie方案”);_schemes.Add(“jwt”, “Jwt方案”);这里有一条清晰的链路AddCookie() 把方案写入 AuthenticationOptions.SchemeMap数据仓库→ IAuthenticationSchemeProvider 从仓库里查询 → 查到的结果交给 IAuthenticationHandlerProvider 去实例化。4处理器的实例化激活 IAuthenticationHandlerProviderIAuthenticationHandlerProvider 负责实例化具体的认证处理器Handler默认实现是 AuthenticationHandlerProvider。上一步 IAuthenticationSchemeProvider 只提供了具体的方案IAuthenticationHandlerProvider 则是根据方案把真正的执行对象从 DI 容器里拉出来放到当前的请求上下文中。5身份二次加工 IClaimsTransformationIClaimsTransformation 用于在认证成功后对用户的身份声明Claims进行二次加工或转换。默认注入的是 NoopClaimsTransformation也就是什么都不做——这代表用户认证通过后拿到的 Claims 原封不动。但如果你想在用户登录后自动从数据库查一下他的最新角色并追加进身份里就可以自己实现这个接口替换掉默认实现。3.认证方案的注册基础设施搭好之后AddScheme 的作用就是把具体的认证策略Handler和配置Options绑起来挂到刚搭好的「方案管理器」里。上面认证的基本运转能力已经具备了接下来我们挑 JWT 作为探究对象。3.1 调用扩展方法进入注册流程先看 JwtBearerExtensions// 添加 JWT 方案public static AuthenticationBuilder AddJwtBearer(this AuthenticationBuilder builder, string authenticationScheme, string? displayName, Action configureOptions){// 用于从配置文件中自动绑定基础选项builder.Services.TryAddEnumerable(ServiceDescriptor.SingletonIConfigureOptions, JwtBearerConfigureOptions());// 在所有常规配置执行完毕后提供默认兜底配置 builder.Services.TryAddEnumerable(ServiceDescriptor.SingletonIPostConfigureOptionsJwtBearerOptions, JwtBearerPostConfigureOptions()); // 将 JWT Bearer 认证方案与对应的处理器JwtBearerHandler绑定 return builder.AddSchemeJwtBearerOptions, JwtBearerHandler(authenticationScheme, displayName, configureOptions);}AddJwtBearer() 是一个静态扩展方法内部先注册了「配置绑定」和「兜底配置」两个服务然后调用 AuthenticationBuilder.AddSchemeJwtBearerOptions, JwtBearerHandler()把具体的选项类型 JwtBearerOptions 和处理器类型 JwtBearerHandler 作为泛型参数传进去正式进入通用的方案注册流程。3.2 进入 AddSchemeHelper看 AuthenticationBuilderprivate AuthenticationBuilder AddSchemeHelperTOptions, [DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.PublicConstructors)] THandler(string authenticationScheme,string? displayName,Action? configureOptions)where TOptions : AuthenticationSchemeOptions, new()where THandler : class, IAuthenticationHandler{var state new AddSchemeHelperState(typeof(THandler));// 1. 配置全局的 AuthenticationOptions将当前方案名称、处理器类型、显示名称注册进去 Services.ConfigureAuthenticationOptions(o { o.AddScheme(authenticationScheme, scheme { scheme.HandlerType state.HandlerType; scheme.DisplayName displayName; }); }); // 2. 如果有自定义的配置委托则将其绑定到当前方案名称上 if (configureOptions ! null) { Services.Configure(authenticationScheme, configureOptions); } // 3. 为当前方案的选项添加验证逻辑构建时通过内置的 Validate 方法检查 Services.AddOptionsTOptions(authenticationScheme).Validate(o { o.Validate(authenticationScheme); return true; }); // 4. 将自定义的认证处理器 Handler 注册为瞬态服务 Services.AddTransientTHandler(); return this;}它才是这部分的主角作用就是「添加一种方案」而添加需要几个对象方案需要的配置 TOptions有约束它必须是 AuthenticationSchemeOptions 的派生类。方案的具体执行者 THandler也有要求它必须是 AuthenticationHandler 类型的派生类。这里说「派生类」而不是「子类」是因为中间隔着几层继承也是允许的。接着看AddScheme 最终调用了私有方法 AddSchemeHelper。它的第一个动作是实例化一个 AddSchemeHelperState 对象把 THandler也就是 JwtBearerHandler的类型信息存进它的 HandlerType 属性。这个对象的作用是在后面的委托链里保留 Handler 的类型信息——因为 Configure 委托是延后执行的得先把类型捕获下来。3.3 AuthenticationOptions 注册方案映射AddSchemeHelper 通过下面这段Services.Configure(o {o.AddScheme(authenticationScheme, scheme {scheme.HandlerType state.HandlerType;scheme.DisplayName displayName;});});把当前方案信息写入全局配置对象 AuthenticationOptions。看 AuthenticationOptionspublic class AuthenticationOptions{private readonly IList _schemes new List();public IEnumerableAuthenticationSchemeBuilder Schemes _schemes; // 定义了一个方案字典 public IDictionarystring, AuthenticationSchemeBuilder SchemeMap { get; } new Dictionarystring, AuthenticationSchemeBuilder(StringComparer.Ordinal); public void AddScheme(string name, ActionAuthenticationSchemeBuilder configureBuilder) { if (name null) { throw new ArgumentNullException(nameof(name)); } if (configureBuilder null) { throw new ArgumentNullException(nameof(configureBuilder)); } if (SchemeMap.ContainsKey(name)) { throw new InvalidOperationException(Scheme already exists: name); } var builder new AuthenticationSchemeBuilder(name); configureBuilder(builder); _schemes.Add(builder); SchemeMap[name] builder; }}AuthenticationOptions.AddScheme 做了这么几件事校验方案名称是否已存在防止重复注册。实例化一个 AuthenticationSchemeBuilder传入方案名称例如 Bearer再把 AddSchemeHelperState 里保存的 HandlerType即 JwtBearerHandler 的类型赋值给 Builder 的 HandlerType 属性。image把 Builder 同时加到 _schemes 列表和 SchemeMap 字典中以方案名称为键。如果调用 AddJwtBearer 时传了 configureOptions 委托那么此时也会把用于配置 Issuer、Audience 的委托绑定到对应的方案名称上让后面解析 JwtBearerOptions 时能按方案名称拿到对应的配置实例。最后再调用 Services.AddTransient()把具体的认证处理器 JwtBearerHandler 注册到 DI 容器每次请求需要时重新实例化。这一步走完AuthenticationOptions 内部维护的 SchemeMap 字典里就包含了方案名称和 AuthenticationSchemeBuilder 的映射关系。3.4 方案注册小结先看整体流程图image整个注册流程走完后依赖注入容器里就有了AuthenticationOptions 的 SchemeMap 字典存储了所有注册方案的名称、显示名称和对应的 HandlerType。每个方案对应的 Options 配置实例按方案名称隔离存好。每个方案对应的 Handler 类型注册为瞬态服务由容器统一管理。用大白话概括一通操作下来其实就干了一件重要的事——把方案转成一个 AuthenticationSchemeBuilder 对象然后存进 AuthenticationOptions 里等着后续使用。4.请求认证执行UseAuthentication 负责把注册好的认证系统真正接入 HTTP 请求的处理管道它本质上就是注册了 AuthenticationMiddleware 中间件。打个比方如果把 HTTP 请求比作水管里的水那 UseAuthentication 就是给水管中间又加了一截这一截专门负责对水做检查——放到这里就是对 HTTP 请求做检查看你有没有经过认证。那接下来要看的就是 HTTP水在这一截水管里到底做了哪些事。源码 https://source.dot.net/#Microsoft.AspNetCore.Authentication/AuthenticationMiddleware.cs ,20a6e8d8983fbe5cpublic class AuthenticationMiddleware{private readonly RequestDelegate _next;public AuthenticationMiddleware(RequestDelegate next, IAuthenticationSchemeProvider schemes) { // 校验参数确保中间件管道和认证方案提供者不为空 if (next null) throw new ArgumentNullException(nameof(next)); if (schemes null) throw new ArgumentNullException(nameof(schemes)); _next next; Schemes schemes; } public IAuthenticationSchemeProvider Schemes { get; set; } public async Task Invoke(HttpContext context) { // 保存原始请求路径信息到特性中以便后续处理使用 context.Features.SetIAuthenticationFeature(new AuthenticationFeature { OriginalPath context.Request.Path, OriginalPathBase context.Request.PathBase }); // 尝试获取所有实现了 IAuthenticationRequestHandler 的处理程序并执行 var handlers context.RequestServices.GetRequiredServiceIAuthenticationHandlerProvider(); foreach (var scheme in await Schemes.GetRequestHandlerSchemesA