在 ASP.NET Core 里做用户登录功能Cookie 身份验证是我用得最多、也最愿意推荐给刚入门的人的一种方案。平时帮同事排查问题十有八九遇到的都是这类需求做一个后台管理系统、公司内部知识库、个人博客的登录区要求不复杂但要正规可用还要能处理“登录之后刷新就掉了”“接口返回 302”“cookie 不知道怎么设置才安全”这类让人头疼的问题。这篇文章我就完整地讲一遍 Cookie 身份验证的原理和实操步骤从服务配置、登录注销、授权控制到生产环境下的安全选项和问题排查全部梳理出来。适合正在用 ASP.NET Core 做 Web 项目的开发者尤其是刚接触认证授权这块、被各种概念绕晕的朋友。看完之后你可以直接照着搭出一套能用的 Cookie 登录体系。1. 先弄懂 Cookie 身份验证在做什么1.1 HTTP 状态困境与 Cookie 的切入点HTTP 协议本身是无状态的。每个请求都是独立的服务器处理完一个请求就“忘记”你是谁了。但业务上又需要“记住”登录状态于是 Cookie 机制成了最经典的解决方案。Cookie 身份验证的思路很简单用户第一次登录时服务器验证过用户名和密码之后把用户信息打包进一个加密的 Cookie返回给浏览器。浏览器后续每次请求都会自动带上这个 Cookie服务器解出来一看就知道是谁在发请求、有没有权限。ASP.NET Core 里这套机制做得相当顺手。你不需要手写加密解密、不需要自己维护 Session 表框架已经内置了一个完整的 Cookie 认证管道只需要做几块配置和接入代码就能跑起来。1.2 为什么我选 Cookie 而不是 JWT 或 Session很多人一上来就问现在不都流行 JWT 吗JWT Token 确实在前后端完全分离的场景下很有优势比如微信公众号网页、手机 API、第三方开放平台。但如果你做的是传统的服务端渲染 MVC 项目、一个后台管理系统或者页面和服务端交互比较紧密的站点Cookie 身份验证反而更简单、更稳。Cookie 方案由浏览器自动携带、自动过期、自动续期配置滑动过期后开发阶段少写很多代码。而 JWT 需要前端手动维护 Token 的存储、附带和失效处理一旦刷新页面Token 丢了就是满盘皆输。Session 方案则是把数据存在服务器端一个 Session 数据库或内存存储要额外维护扩展时还要考虑分布式 Session 的问题。Cookie 身份验证的典型优势是框架内建支持配置即用用户身份信息直接写在加密 Cookie 中服务器不用为每个用户都保存状态也可以结合持久化方式存但默认无状态更省事Cookie 默认会带 HttpOnly 和 SameSite 防护安全默认值调得不错中途想升级到 JWT 或 OAuth2 也不冲突可以并存过渡1.3 Cookie 身份验证的工作流程整个流程拆开看是下面这个闭环用户访问受保护的页面比如/Dashboard/Index认证中间件发现请求没有携带有效 Cookie默认行为是把请求重定向到登录页地址类似/Account/Login?ReturnUrl%2FDashboard%2FIndex用户填写账号密码提交服务器校验通过后调用SignInAsync把身份信息写入加密 Cookie浏览器拿到 Cookie后续请求自动携带认证中间件读取 Cookie还原身份User.Identity.IsAuthenticated变为 true授权中间件再判断是否能访问有了这个整体概念之后后面每一步配置和代码你就不会觉得是“背流程”了而是知道每一步在整条链条里承担什么职责。2. 从零搭建环境准备与服务配置2.1 项目初始化和依赖安装我建议直接用 ASP.NET Core 的 Web 应用模板做基础不管是 MVC 还是 Razor Pages 都行只要是个 Web 项目就好。我用的是 .NET 8 版本API 在这几个大版本里几乎没有变化换到 .NET 6 或 .NET 7 也完全适用。创建项目的命令很简单dotnet new mvc -n CookieAuthDemo cd CookieAuthDemo不需要额外安装 NuGet 包。Microsoft.AspNetCore.Authentication.Cookies是框架自带的你在项目文件里看不到它显式引用因为它包含在共享框架里了这一点对新手很友好。如果你用的是 Visual Studio向导里选择“ASP.NET Core Web 应用模型-视图-控制器”然后一路下一步就行。如果创建的是空模板要确保 CSPROJ 里是Microsoft.NET.Sdk.Web。2.2 注册认证服务与中间件顺序在Program.cs里核心配置是两块注册服务和注册中间件管道。服务注册代码builder.Services.AddAuthentication(CookieAuthenticationDefaults.AuthenticationScheme) .AddCookie(options { options.LoginPath /Account/Login; options.LogoutPath /Account/Logout; options.AccessDeniedPath /Account/AccessDenied; });中间件注册代码必须放在合适的位置var app builder.Build(); app.UseHttpsRedirection(); app.UseStaticFiles(); app.UseRouting(); app.UseAuthentication(); app.UseAuthorization(); app.MapControllers(); app.MapDefaultControllerRoute(); app.Run();这里有一条很多人踩过的坑UseAuthentication必须放在UseRouting之后、UseAuthorization之前。中间件的顺序决定了认证是否生效。如果你把UseAuthentication放在UseRouting前面有些版本会出现身份迟迟不加载的问题如果你漏掉了UseAuthentication那[Authorize]虽然会拦截请求但永远不会放行因为没有任何身份被还原出来。还有个容易忽略的点如果你的项目是从老版本升级上来的UseAuthentication出现的时机更重要。我在某个项目里见过有人把app.UseMvc(...)和认证中间件顺序排错结果所有匿名请求都在认证环节被吃掉连静态文件都打不开页面全红。2.3 关键配置项逐项拆解AddCookie里的options是整个认证行为的总开关。以下是我常用的一组配置附上每一项的解释.AddCookie(options { options.LoginPath /Account/Login; options.LogoutPath /Account/Logout; options.AccessDeniedPath /Account/AccessDenied; options.Cookie.Name MyApp.Auth; options.Cookie.HttpOnly true; options.Cookie.SecurePolicy CookieSecurePolicy.SameAsRequest; options.Cookie.SameSite SameSiteMode.Lax; options.ExpireTimeSpan TimeSpan.FromHours(2); options.SlidingExpiration true; options.ReturnUrlParameter returnUrl; });选项说明配置项作用我的建议LoginPath未登录时重定向的登录页地址指定到自己项目的登录 ActionLogoutPath注销时跳转的地址会触发注销逻辑时使用AccessDeniedPath已登录但无权限时跳转地址搭配角色授权使用Cookie.Name指定 Cookie 名字多项目共存时特别有用避免冲突Cookie.HttpOnly禁止 JavaScript 读取 Cookie最好保持 true防 XSS 窃取Cookie.SecurePolicyHTTPS 环境下是否只传 Cookie生产建议 AlwaysCookie.SameSite跨站请求时 Cookie 的发送策略Lax 是最常用稳妥值ExpireTimeSpanCookie 认证有效期看业务一般 1~8 小时SlidingExpiration持续操作是否自动续期建议开提升体验ReturnUrlParameter登录后回跳地址的 Query 参数名默认就是 returnUrlExpireTimeSpan和SlidingExpiration这两个要放在一起理解。ExpireTimeSpan是绝对到期时间比如设置 2 小时那么从签发的那一刻算起2 小时后失效。SlidingExpiration打开后用户只要在过期前的“半个时间窗口”内有新请求就会自动续期不需要重新登录。这个机制对后台管理系统特别友好员工挂着一个页面不动过了三四个小时再操作也不会莫名其妙被踢出去。但要注意滑动过期有个前提请求必须真正经过了认证中间件并且用户身份有效。如果你在服务器内存里缓存了某些用户数据滑动续期只会续期 Cookie不会刷新缓存里的数据时间这点后面排查问题时会提到。2.4 数据保护密钥的说明ASP.NET Core 的 Cookie 加密依赖数据保护Data Protection系统。默认情况下密钥存放在本地用户目录。开发环境没问题但部署到生产环境时如果你有多台服务器轮流负载均衡或者服务器经常被重新部署就会遇到“在一台机器上登录换一台机器请求就掉登录”的问题。解决方法是把密钥持久化到一个共享位置builder.Services.AddDataProtection() .PersistKeysToFileSystem(new DirectoryInfo(\\nas-share\keys)) .SetApplicationName(MyApp) .ProtectKeysWithDpapi();这里我只是给个方向实际生产环境用数据库或 Redis 持久化密钥也可以。记住一句话Cookie 加密能力和应用名、密钥存储强相关。改了机器名、换了应用名、密钥丢了之前的登录 Cookie 全部作废。3. 核心实操登录、注销与受保护页面3.1 登录 Action 的完整实现没有真实数据库之前先用一个固定账号演示完整流程。实际项目中这地方替换成你自己的用户表和密码哈希校验即可。创建AccountControllerpublic class AccountController : Controller { [HttpGet] public IActionResult Login(string returnUrl null) { ViewData[ReturnUrl] returnUrl; return View(); } [HttpPost] [ValidateAntiForgeryToken] public async TaskIActionResult Login(LoginViewModel model, string returnUrl null) { if (!ModelState.IsValid) { return View(model); } // 实际项目这里应该查数据库用密码哈希做比对。 // 这里演示固定用户真实场景一定不要在代码里写死密码。 if (model.UserName ! admin || model.Password ! 123456) { ModelState.AddModelError(, 用户名或密码错误); return View(model); } var claims new ListClaim { new Claim(ClaimTypes.Name, model.UserName), new Claim(DisplayName, 管理员), new Claim(ClaimTypes.Role, Admin), new Claim(Department, IT) }; var identity new ClaimsIdentity(claims, CookieAuthenticationDefaults.AuthenticationScheme); var principal new ClaimsPrincipal(identity); await HttpContext.SignInAsync( CookieAuthenticationDefaults.AuthenticationScheme, principal, new AuthenticationProperties { IsPersistent model.RememberMe, ExpiresUtc DateTimeOffset.UtcNow.AddHours(2), RedirectUri returnUrl }); if (Url.IsLocalUrl(returnUrl)) { return Redirect(returnUrl); } return RedirectToAction(Index, Home); } }这里有三个关键点需要展开说。第一ClaimsIdentity的认证类型参数。第三个参数传的是CookieAuthenticationDefaults.AuthenticationScheme即Cookies。这个字符串必须和鉴权时用的一致。如果你传错或者传空字符串用户登录成功了但User.Identity.IsAuthenticated依然是 false因为框架不知道这个身份属于哪种认证方式。第二Url.IsLocalUrl(returnUrl)这一步一定不要省。它是防开放重定向漏洞的最后一道闸。如果returnUrl是外部地址就不能直接Redirect(returnUrl)否则攻击者可以伪造你的登录链接登录成功后把你带到钓鱼网站。用IsLocalUrl判断后非本地地址一律跳到首页这是安全红线。第三ValidateAntiForgeryToken需要视图里有对应的Html.AntiForgeryToken()或标签帮助器生成一个防伪标记。ASP.NET Core MVC 的form标签帮助器在[HttpPost]方法里会自动检查但如果你的页面是静态 HTML 或用了纯 AJAX 提交就必须手动生成和传递这个 token。3.2 创建登录视图登录视图放在Views/Account/Login.cshtmlmodel LoginViewModel { ViewData[Title] 登录; } h2登录/h2 form asp-controllerAccount asp-actionLogin methodpost input typehidden namereturnUrl valueViewData[ReturnUrl] / div label asp-forUserName用户名/label input asp-forUserName classform-control / span asp-validation-forUserName classtext-danger/span /div div label asp-forPassword密码/label input asp-forPassword classform-control typepassword / span asp-validation-forPassword classtext-danger/span /div div input asp-forRememberMe / label asp-forRememberMe记住我/label /div button typesubmit classbtn btn-primary登录/button div asp-validation-summaryModelOnly classtext-danger/div /formLoginViewModel的定义就是普通的三字段模型UserName、Password、RememberMe。这里有一个容易被忽略的点returnUrl必须通过隐藏字段传回后台否则登录成功后浏览器会丢失目标地址。因为returnUrl虽然在当前地址的 Query String 里有但form提交会把参数放到表单体里如果你不在隐藏字段里保留它后台就收不到。登录成功之后浏览器会Set-Cookie一个加密字符串。你打开浏览器开发者工具在“应用”或“网络”标签里能找到名为MyApp.Auth的 Cookie内容是一长串看不出语义的字符。看着像乱码其实里面包含了角色、用户名、过期时间等声明的完整加密信息。这个加密是框架用数据保护系统做的不是 Base64 编码完事所以你不用担心被用户篡改。3.3 注销与身份过期处理注销逻辑相对简单[HttpPost] [ValidateAntiForgeryToken] public async TaskIActionResult Logout() { await HttpContext.SignOutAsync(CookieAuthenticationDefaults.AuthenticationScheme); return RedirectToAction(Index, Home); }注意我用了[HttpPost]而不是[HttpGet]。我在实际项目里见过有人把注销放在 GET 请求里结果一个页面引用了a href/Account/Logout之后被爬虫或预加载请求触发用户莫名其妙就被登出了。用 POST 方式可以避免这种误触发。视图里用form包一个按钮即可form asp-controllerAccount asp-actionLogout methodpost button typesubmit classbtn btn-link退出登录/button /form还有一种情况是身份过期。比如用户登录后电脑休眠了很久超过 2 小时后回来点了一下页面。这时候认证中间件会识别到 Cookie 过期自动重定向到登录页。但有一个体验细节如果你自定义了OnRedirectToLogin事件来处理 AJAX 请求就会知道过期这件事不总是“整个页面刷新”。一个后台系统的仪表盘可能每隔一分钟向后端发一次心跳请求Cookie 过期后心跳请求会收到 302而不是 JSON 数据。这就是后面要讲的问题排查重点之一。3.4 扩展角色与多种策略授权登录之后给控制器或 Action 加上[Authorize]标签就进入了“必须登录”的门[Authorize] public class DashboardController : Controller { public IActionResult Index() { return View(); } }角色控制用[Authorize(Roles Admin)][Authorize(Roles Admin)] public class AdminController : Controller { public IActionResult Index() View(); }当用户已登录但没有 Admin 角色时认证中间件会看到“身份有效但授权不通过”于是把请求转到AccessDeniedPath配置的地址也就是我们前面配置的/Account/AccessDenied。这个地址对应一个普通的视图或 Action就是一个无权限提示页。多策略授权更细一点可以自定义IAuthorizationRequirement和AuthorizationHandler比如“部门为 IT 且职级不低于主管”的用户才能访问某个报表页面。这些内容建立在 Cookie 身份验证之上逻辑会更长。新手阶段先掌握[Authorize]、[Authorize(Roles ...)]和[AllowAnonymous]这三个标签就够用了。4. 完整示例与配置清单4.1 最小可运行 Demo 全览把前面所有片段拼起来一个最小的可运行项目结构如下CookieAuthDemo/ ├── Controllers/ │ ├── HomeController.cs │ └── AccountController.cs ├── Models/ │ └── LoginViewModel.cs ├── Views/ │ ├── Account/ │ │ └── Login.cshtml │ └── Dashboard/ │ └── Index.cshtml ├── Program.cs └── CookieAuthDemo.csprojProgram.cs全文件大致如下var builder WebApplication.CreateBuilder(args); builder.Services.AddControllersWithViews(); builder.Services.AddAuthentication(CookieAuthenticationDefaults.AuthenticationScheme) .AddCookie(options { options.LoginPath /Account/Login; options.LogoutPath /Account/Logout; options.AccessDeniedPath /Account/AccessDenied; options.Cookie.Name MyApp.Auth; options.Cookie.HttpOnly true; options.Cookie.SecurePolicy CookieSecurePolicy.SameAsRequest; options.ExpireTimeSpan TimeSpan.FromHours(2); options.SlidingExpiration true; }); var app builder.Build(); app.UseHttpsRedirection(); app.UseStaticFiles(); app.UseRouting(); app.UseAuthentication(); app.UseAuthorization(); app.MapControllerRoute( name: default, pattern: {controllerHome}/{actionIndex}/{id?}); app.Run();在这个基础上你访问/Dashboard/Index时未登录状态会自动跳到/Account/Login?returnUrl%2FDashboard%2FIndex输入 admin / 123456 登录后会回跳到 Dashboard 页面。这个流程已经是一个完整的 Cookie 认证闭环。4.2 生产环境推荐配置把 Demo 跑通只是第一步。要上生产我建议至少做下面这些改动builder.Services.AddDataProtection() .PersistKeysToFileSystem(new DirectoryInfo(/secure/storage/dpkeys)) .SetApplicationName(MyApp); builder.Services.AddAuthentication(CookieAuthenticationDefaults.AuthenticationScheme) .AddCookie(options { options.Cookie.Name MyApp.Auth; options.Cookie.HttpOnly true; options.Cookie.SecurePolicy CookieSecurePolicy.Always; options.Cookie.SameSite SameSiteMode.Lax; options.ExpireTimeSpan TimeSpan.FromHours(8); options.SlidingExpiration true; options.Events.OnRedirectToLogin context { if (context.Request.Path.StartsWithSegments(/api)) { context.Response.StatusCode StatusCodes.Status401Unauthorized; return Task.CompletedTask; } context.Response.Redirect(context.RedirectUri); return Task.CompletedTask; }; });生产环境还要配合密文管理这里的密钥路径在我的例子里写得比较随意真实项目建议放在受保护的目录或对象存储里。SameSiteMode.Lax也有一个权衡如果你要从别的站点通过a链接跳转到本系统且需要携带 CookieLax 允许顶级导航携带但 POST 跨站就不会带了。需要全站跨站提交表单的场景得认真评估是不是该换成None并强制 HTTPS。绝大多数传统后台管理系统Lax 是安全又实用的默认值。Cookie.SecurePolicy在生产环境设成Always意味着 Cookie 只在 HTTPS 连接下发送。如果厂里内网基础架构没配好HTTP 跳转 HTTPS 没完全覆盖就会出现“HTTPS 页面登录成功跳回 HTTP 页面又变成未登录”的诡异问题。所以设Always前确认全站 HTTPS 是统一可用的。4.3 记住我功能与安全提醒IsPersistent控制的是会话 Cookie 还是持久 Cookie。不勾选“记住我”时Cookie 是浏览器会话级别关闭浏览器就没了。勾选后Cookie 按ExpiresUtc写入浏览器本地下次打开浏览器还在。从安全角度看记住我功能相当于在你电脑上放了一把钥匙。公共电脑绝对不能开。我的做法是明确对比值敏感的应用干脆不提供勾选框内部后台则保留但缩短过期时间并配合设备指纹信息。真要做到高安全强度还可以在用户表里存一个TokenVersion用户改密码或强制下线时把版本号加一旧 Cookie 立刻失效。这个做法不复杂但能有效解决“改完密码旧 Cookie 还在”的漏洞。5. 常见问题与排查技巧实录5.1 为什么登录后刷新页面又回到登录页这个现象通常是三个原因之一。第一个是中间件顺序错了UseAuthentication不在管道里或者位置不对。排查方法在某个受保护 Action 的 View 里输出User.Identity.IsAuthenticated如果所有请求都是 false不管登录多少次都没用那几乎可以确定是认证中间件没生效。第二个是ClaimsIdentity的认证类型传错。登录时用了new ClaimsIdentity(claims)这种不带 authenticationType 的重载结果身份对象被标记为未经认证。IsAuthenticated靠的是Identity.AuthenticationType是否为空判断。如果为空Cookie 虽然写进浏览器了但读出来永远是匿名。第三个是数据保护密钥问题。开发环境在一台机器上做过 Cookie改了应用名或者清了本地密钥后旧 Cookie 就读不出来了。这种“掉登录”经常是在某次重启之后集中爆发。解决方法是把密钥永久化或者干脆让用户重新登录一次新 Cookie 就正常了。5.2 为什么一直收到 302 而不是 401Cookie 身份验证基于重定向驱动所以当 API 请求或 AJAX 请求未认证时默认行为是 302 跳到登录页。这对普通页面来说没问题但对接口来说就很麻烦前端拿到 302 往往不知道怎么处理有的浏览器还会把响应体吞掉。处理方案就是我前面提到配置里的OnRedirectToLogin事件。根据请求路径判断如果是/api开头就改成返回 401如果是普通页面仍然跳转登录页。在AddCookie的Events里这样写options.Events.OnRedirectToLogin context { if (context.Request.Path.StartsWithSegments(/api)) { context.Response.StatusCode StatusCodes.Status401Unauthorized; return Task.CompletedTask; } context.Response.Redirect(context.RedirectUri); return Task.CompletedTask; };同样的道理OnRedirectToAccessDenied也可以对 API 请求返回 403。5.3 修改密码后旧的 Cookie 还能用默认情况下修改密码并不会撤销已经签发的 Cookie。因为 Cookie 里只是声明集合和过期时间认证中间件不会去数据库查“这个用户的最新密码版本是多少”。如果你的业务要求“修改密码后其它设备立即下线”就得自己加一层控制。我之前在项目里是用声明加 TokenVersion 的方式实现的用户表加一个SecurityStamp字段每次改密码、封号、重置时更新它登录时把SecurityStamp写进 Claim在每个请求经过认证后的某个环节比如全局过滤器或中间件读取当前用户在数据库的SecurityStamp和 Cookie 里的 Claim 比对不一致就SignOutAsync并跳转登录这个方案不影响 Cookie 认证本身的性能只多一次数据库查询。不过要注意每次请求都查库可能带来额外开销可以用短缓存比如几十秒做优化但我个人更倾向于“安全型应用宁可多查一次”。敏感操作做这种校验值得。5.4 服务器多实例部署时登录随机失效这是数据保护密钥没有共享导致的。假设你有 A、B 两台服务器负载均衡轮询转发请求。用户第一次请求被 A 处理登录时 A 用自己的密钥加密 Cookie。下一个请求被 B 处理B 用自己的密钥去解密发现解不开于是视为匿名用户跳转登录页。用户就感觉登录总是“时灵时不灵”。解决办法就是密钥持久化并且要落在所有实例都能访问到的地方。我上面写的PersistKeysToFileSystem是其中一种要求文件目录可共享比如 NAS 或对象存储挂载目录。如果不想搞文件共享可以用PersistKeysToDbContext把密钥存在数据库或用PersistKeysToStackExchangeRedis存在 Redis。配置之后还要确保SetApplicationName在所有实例上一致否则密钥对不上。5.5 CSRF 与 XSS 的防护提醒Cookie 身份验证天然要面对两个 Web 安全经典问题跨站请求伪造CSRF和跨站脚本XSS。CSRF 的典型场景是用户登录了后台Cookie 自动带上这时访问了恶意页面恶意页面偷偷提交一个 POST 请求到你的后台因为浏览器会自动携带当前站点的 Cookie服务器就会以为这是用户本人发起的合法请求。ASP.NET Core 的防伪机制可以解决表单提交场景视图里生成一个随机的防伪 token表单提交时校验服务器端。我建议所有 POST 的 Action 都加上[ValidateAntiForgeryToken]并且视图里用表单标签帮助器生成防伪字段。这套机制不要在“反正不是公开站点”的心态下省掉内网系统被 CSRF 打的案例一点也不少。XSS 的风险在于如果页面里任何位置输出了未经编码的用户输入比如用户名、评论内容攻击者注入一段脚本就能读取内存中的数据虽然 HttpOnly 能挡掉直接读取 Cookie但脚本仍然可以代替用户提交请求。所以养成一个习惯视图里一律用编码输出富文本必须走白名单过滤不用Html.Raw处理不可信内容。5.6 疑难杂症排查速查表现象可能原因排查手段登录后立即回到登录页中间件顺序错 / 认证类型为空检查 Program.cs 管道顺序输出 IsAuthenticated刷新掉登录数据保护密钥丢失查看应用日志、确认密钥持久化403 而不是 401已登录但无角色检查 AccessDeniedPath 是否配置API 返回 302 页面未登录接口请求被重定向配置 OnRedirectToLogin 返回 401多实例随机掉线密钥未共享统一数据保护存储和应用名Cookie 太大塞了太多 Claim精简声明大对象放数据库只放标识Cookie 过期时间不对ExpireTimeSpan 与 IsPersistent 混用理解两个参数含义看 Set-Cookie 头写在最后Cookie 身份验证这块最核心的东西搞明白之后真到了项目上你会发现它其实就是“配置 登录/注销 授权标记”三件套。我一开始也在中间件顺序上栽过跟头在登录页和跳转逻辑之间折腾了大半天后来多做了几个项目回头看才发现那些原理层面的理解才是省时间的钥匙。如果你正准备给你的项目加上登录功能先不用整太多框架和概念从 Cookie 身份验证起步是最稳的。照着这篇文章把最小闭环跑通再根据你的业务逐步加上数据库用户、角色、策略、安全加固整个系统就能很扎实地长起来。