Microsoft.AspNetCore.Authentication 核心库源码指南构建与测试 ASP.NET Core 认证体系【免费下载链接】aspnetcoreASP.NET Core is a cross-platform .NET framework for building modern cloud-based web applications on Windows, Mac, or Linux.项目地址: https://gitcode.com/GitHub_Trending/as/aspnetcore本指南围绕 ASP.NET Core 仓库中认证功能的共享实现——Microsoft.AspNetCore.Authentication核心库展开介绍如何从源码构建、运行测试并结合该目录下的核心抽象认证方案、Handler、Builder、中间件、选项与事件机制讲解其工作原理与源码级实现细节。读完本文你将掌握该核心库的源码结构、开发环境搭建方法并能依据源码理解 ASP.NET Core 认证管线的完整运行链路。项目定位认证功能的共享实现Microsoft.AspNetCore.Authentication核心库位于仓库的 src/Security/Authentication/Core 目录下是 ASP.NET Core 中所有认证相关组件的公共基座。整个 Security 区域在 Security 总 README 中被划分为Authentication/识别用户的组件Authorization/判断用户是否具备所需权限的组件CookiePolicy/强制为响应 Cookie 施加安全属性的中间件perf/性能测试基础设施samples/组合上述功能区域的示例test/共享测试。当前核心库正是其中Authentication子区域的公共实现后续的 Cookies、JwtBearer、OAuth、OpenIdConnect、Google、Facebook、WsFederation、Negotiate、Certificate 等具体认证方案见 src/Security/Authentication 目录都以它为基础派生。仓库明确指出ASP.NET Security 不包含 Basic Authentication 中间件因其存在安全隐患与性能问题如在 IIS 下托管可通过 IIS 配置启用 Basic Authentication——这也是理解认证方案取舍的重要背景。从该核心库的源码目录 Core/src 可以看到一组构成认证骨架的核心类型AuthenticationHandler、AuthenticationBuilder、AuthenticationMiddleware、AuthenticationSchemeOptions、RemoteAuthenticationHandler、RemoteAuthenticationOptions以及Events/目录下的一批上下文类BaseContext、ResultContext、RedirectContext、RemoteFailureContext等。从源码构建核心库该 README 指出若要单独构建此项目可遵循仓库根目录文档 docs/BuildFromSource.md 中构建代码子集一节的说明。最简化的方式是在security父目录下直接执行 ./build.cmd这条命令会触发仓库既有的构建脚本仓库根目录另有restore.cmd、clean.cmd等配套脚本以及 Unix 平台对应的restore.sh、clean.sh。构建前需确保本机具备仓库 global.json 中声明的 .NET SDK 版本并通过根目录 NuGet.config 完成依赖源配置。运行测试README 提供了两种测试方式按 docs/BuildFromSource.md 中在命令行运行测试一节的说明执行更简化的方式在security父目录运行 ./build.cmd -t-t参数用于执行测试。此外也可以在项目src目录旁的tests目录中直接运行项目级测试 dotnet test从仓库结构看src/Security/test 保存着 Security 区域的共享测试而各认证方案自身也带有对应的测试目录例如 src/Security/Authentication/Cookies/test若需单独验证 Cookie 方案可进入对应目录执行dotnet test。核心抽象源码剖析AuthenticationHandler认证处理的抽象基类AuthenticationHandlerTOptions是核心库的灵魂类型定义于 AuthenticationHandler.cs实现IAuthenticationHandler接口要求TOptions继承自AuthenticationSchemeOptions。它向派生类型暴露了丰富的受保护成员Scheme、Options、Context当前认证方案、选项实例与HttpContextRequest、Response当前请求与响应OriginalPath/OriginalPathBase由IAuthenticationFeature提供的中间件视角下的原始路径AuthenticationMiddleware会在管线入口处记录它们Logger、UrlEncoder、TimeProvider日志、URL 编码与时间服务源码注释明确ISystemClock已过时建议改用TimeProviderOptionsMonitor用于感知运行期选项变更Events事件对象应用可在处理流程的关键节点获得控制权默认实例为空操作ClaimsIssuer签发 Claims 时使用的颁发者取Options.ClaimsIssuer或回退到Scheme.Name。InitializeAsync是每次请求进入时的初始化入口它从OptionsMonitor按方案名解析选项、设置TimeProvider再依次调用InitializeEventsAsync与InitializeHandlerAsync。事件对象的分辨优先级为Options.Events属性 →Options.EventsType从 DI 容器解析 →CreateEventsAsync创建默认实例。AuthenticateAsync的处理流程值得注意先通过ResolveTarget(Options.ForwardAuthenticate)检查是否应转发到其他方案若无转发则调用HandleAuthenticateOnceAsync——它通过_authenticateTask字段缓存结果确保同一请求中HandleAuthenticateAsync只执行一次HandleAuthenticateOnceSafeAsync则在此基础上捕获异常并转换为AuthenticateResult.Fail最终通过LoggingExtensions输出方案是否成功认证的日志。派生类必须实现的唯一抽象方法是HandleAuthenticateAsync而HandleChallengeAsync默认写 401与HandleForbiddenAsync默认写 403为虚方法认证方案可覆写以改变行为如把 401 改写为跳转登录页的 302。AuthenticationBuilder 与 AddAuthentication 扩展AuthenticationBuilder见 AuthenticationBuilder.cs封装了IServiceCollection提供三个核心注册方法AddSchemeTOptions, THandler注册普通认证方案。底层AddSchemeHelper会执行向AuthenticationOptions注册方案记录HandlerType与DisplayName、用Services.Configure(authenticationScheme, ...)配置选项、注册带校验的命名选项Validate中调用o.Validate(authenticationScheme)、以 Transient 生命周期注册 Handler并追加PostConfigureAuthenticationSchemeOptions把 DI 中的TimeProvider注入选项AddRemoteSchemeTOptions, THandler注册基于RemoteAuthenticationHandler的远程认证方案额外追加EnsureSignInScheme后置配置——它确保SignInScheme存在options.SignInScheme ?? _authOptions.DefaultSignInScheme ?? _authOptions.DefaultSchemeAddPolicyScheme注册PolicySchemeHandler用于把认证操作重定向到其他方案。对应的AddAuthentication扩展定义于 AuthenticationServiceCollectionExtensions.cs提供三个重载无参数版、defaultScheme版等价于配置o.DefaultScheme defaultScheme与ActionAuthenticationOptions配置版。无参数版除注册认证核心服务外还注册了 Data Protection、Web Encoders、TimeProvider.System、ISystemClock已过时但保留兼容以及IAuthenticationConfigurationProvider。AuthenticationMiddleware管线中的认证执行者AuthenticationMiddleware见 AuthenticationMiddleware.cs的工作分三步在HttpContext.Features中设置IAuthenticationFeature记录原始Path与PathBase遍历IAuthenticationSchemeProvider.GetRequestHandlerSchemesAsync()返回的方案若某个 Handler 实现了IAuthenticationRequestHandler且HandleRequestAsync()返回true则请求被该 Handler 接管并短路返回这是远程认证回调路径得以处理的机制否则查找默认认证方案执行context.AuthenticateAsync成功时把result.Principal赋给context.User并设置IHttpAuthenticationFeature与IAuthenticateResultFeature特性随后await _next(context)继续管线。选项体系AuthenticationSchemeOptions 与远程认证扩展AuthenticationSchemeOptions见 AuthenticationSchemeOptions.cs是所有认证方案选项的基类核心属性包括ClaimsIssuer生成 Claims 时的颁发者Events/EventsType事件实例或其 DI 服务类型ForwardDefault/ForwardDefaultSelector默认转发目标方案/按请求动态选择转发方案的委托ForwardAuthenticate/ForwardChallenge/ForwardForbid/ForwardSignIn/ForwardSignOut分别控制五类认证操作的转发目标TimeProvider测试用时间源。其转发解析逻辑ResolveTarget优先级为最具体的ForwardXxx→ForwardDefaultSelector→ForwardDefault首个非空结果即为转发目标若目标等于当前方案名则视为禁用转发。这解释了为什么选项文档注释要求将目标设为当前方案以禁用转发。RemoteAuthenticationOptions见 RemoteAuthenticationOptions.cs在基类之上补充了远程认证所需的配置CallbackPath远程身份提供方回跳的请求路径必填缺失时Validate()抛出ArgumentExceptionSignInScheme认证成功后持久化用户身份的方案通常对应 Cookie 方案缺省回退到DefaultSignInSchemeBackchannelTimeout与远程提供方通信的超时默认 60 秒BackchannelHttpHandler/Backchannel通信用的HttpMessageHandler/HttpClientAccessDeniedPath/ReturnUrlParameter用户拒绝授权时的跳转路径及回跳参数默认ReturnUrlRemoteAuthenticationTimeout完成整个认证流程的时间上限默认 15 分钟SaveTokens是否把 access/refresh token 存入AuthenticationProperties默认false以缩小认证 Cookie 体积CorrelationCookie防伪关联 Cookie 的构建器默认名称前缀.AspNetCore.Correlation.HttpOnly true、SameSite None、SecurePolicy Always、IsEssential trueDataProtectionProvider数据保护提供方。Validate(string scheme)还额外校验若SignInScheme与当前方案同名会抛出InvalidOperationException远程方案不能自己充当登录持久化方案。远程认证RemoteAuthenticationHandler 与关联 Cookie 防伪RemoteAuthenticationHandlerTOptions见 RemoteAuthenticationHandler.cs实现了IAuthenticationRequestHandler专门处理由外部托管的身份提供方完成认证的场景。其关键机制ShouldHandleRequestAsync判断Options.CallbackPath Request.Path决定是否接管当前请求HandleRequestAsync在命中回调路径时调用RemoteAuthenticationAntiforgery.HandleWithoutAntiforgeryVerdictAsync包装的HandleRequestCoreAsync其中调用HandleRemoteAuthenticateAsync解析票证失败时构造RemoteFailureContext触发Events.RemoteFailure并可能抛出AuthenticationFailureException关联 CookieCorrelationCookie的默认属性SameSiteNone、Secure与常量CorrelationProperty .xsrf、CorrelationMarker N、AuthSchemeKey .AuthScheme共同构成 OpenID Connect/OAuth 方案中防 CSRF 的基础设施。数据序列化与 SecureDataFormat核心库还提供了票证与属性的序列化基础设施TicketSerializer.cs、TicketDataFormat.cs、PropertiesSerializer.cs、PropertiesDataFormat.cs 以及ISecureDataFormatT/IDataSerializerT接口。它们使得认证票证AuthenticationTicket可以被加密后写入 CookieCookie 方案即依赖这一能力持久化登录状态。更多信息若需深入了解 Security 区域的整体结构可查阅 Security README要了解整个 ASP.NET Core 仓库的构建与贡献流程可阅读根目录 README.md 与 CONTRIBUTING.md。需要说明的是ASP.NET Core 的完整认证文档如方案、Handler、转发与事件的高级用法由官方文档站点提供本仓库内则以源码与上述 README 为准。【免费下载链接】aspnetcoreASP.NET Core is a cross-platform .NET framework for building modern cloud-based web applications on Windows, Mac, or Linux.项目地址: https://gitcode.com/GitHub_Trending/as/aspnetcore创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考