：從Session登錄驗證到Cookie與Claims權(quán)限管理)
1. 自己用 Session 做登錄驗證問題出在哪我最早做 Web 開發(fā)那會兒身份驗證這塊見過很多同事拿 Session 硬拼。用戶登錄成功了就往 Session 里塞一個 UserId每個請求進(jìn)來自己判斷 Session 里有沒有值沒有就跳回登錄頁。這套做法在 demo 和小工具里確實能跑但項目一旦多幾個用戶、多幾個接口問題就冒出來了Session 失效、重啟、多機(jī)負(fù)載均衡時 Session 不同步用戶動不動就掉線密碼只能拿 MD5 或 SHA 存撞庫風(fēng)險高完全沒有加鹽和迭代設(shè)計忘了做鎖定策略爆破攻擊可以無限試密碼角色、權(quán)限、用戶信息全部散落在業(yè)務(wù)代碼里每個控制器自己寫一套判斷邏輯。后來切到ASP.NET Core Identity之后這些東西全部變成了框架能力密碼哈希由它管、Cookie 票據(jù)由它管、鎖定策略由它管、角色和聲明由它管甚至郵箱確認(rèn)、手機(jī)號確認(rèn)、外部登錄的 Token 存儲都有現(xiàn)成的抽象。這篇文章我不會去復(fù)述官方文檔而是按我實際改造一個模擬項目 X 的過程來講怎么從零接上 Identity、跑通注冊登錄再把容易踩的坑挨個說清楚。這套內(nèi)容適合誰剛?cè)胧?ASP.NET Core、準(zhǔn)備把用戶系統(tǒng)從自研 Session 方案換成框架方案的開發(fā)者以及已經(jīng)在用 Identity 但只停留在“能登錄”階段、想搞清楚 Cookie 和 Claims 原理的人。2. 最小可跑的搭建流程從空項目到注冊登錄2.1 創(chuàng)建項目與引入身份相關(guān)包先建一個 ASP.NET Core MVC 項目我用的是 .NET 8。模板自帶空的結(jié)構(gòu)就行不需要勾選“個人用戶賬戶”因為那個模板幫你把一堆代碼生成了反而看不清每部分在干什么。需要引入的 NuGet 包有這些Microsoft.AspNetCore.Identity.EntityFrameworkCoreMicrosoft.EntityFrameworkCore.SqlServer如果用 SQL Server別的庫也支持Microsoft.AspNetCore.Identity.UI提供默認(rèn)的 Razor 身份頁面但后面我會講為什么我一般不直接用很多人會漏掉第二個包結(jié)果寫UseSqlServer時編譯報錯一臉懵。EntityFrameworkCore 容器擴(kuò)展方法在Microsoft.EntityFrameworkCore.SqlServer這個包里不是身份包自帶的。2.2 配置數(shù)據(jù)庫上下文與 Identity 服務(wù)注冊我習(xí)慣的做法是新建一個用戶類繼承IdentityUser哪怕現(xiàn)在不擴(kuò)展任何字段也要留好擴(kuò)展口子public class ApplicationUser : IdentityUser { }再建數(shù)據(jù)庫上下文繼承IdentityDbContextApplicationUserpublic class AppDbContext : IdentityDbContextApplicationUser { public AppDbContext(DbContextOptionsAppDbContext options) : base(options) { } }然后在Program.cs里注冊builder.Services.AddDbContextAppDbContext(options options.UseSqlServer(builder.Configuration.GetConnectionString(DefaultConnection))); builder.Services.AddIdentityApplicationUser, IdentityRole(options { }) .AddEntityFrameworkStoresAppDbContext() .AddDefaultTokenProviders();AddDefaultTokenProviders容易被忽略但 email 確認(rèn)、忘記密碼、雙因素驗證的 Token 全靠它生成。不加的話后面用到GenerateEmailConfirmationTokenAsync時會直接拋異常。中間件的順序也很有講究app.UseAuthentication(); app.UseAuthorization();必須在UseAuthorization之前先UseAuthentication否則[Authorize]拿到的HttpContext.User一直是空的。這個順序錯了最常見的問題就是所有標(biāo)記了[Authorize]的頁面全部 302 到登錄頁因為框架根本不認(rèn)識當(dāng)前用戶。2.3 注冊和登錄的控制器與頁面我不直接用 Identity UI 的 Razor 頁面而是自己寫控制器操作。原因有兩個一是方便看執(zhí)行流程二是很多項目需要定制字段和跳轉(zhuǎn)邏輯自己寫比改生成代碼更干凈。注冊操作核心邏輯用UserManager[HttpPost] public async TaskIActionResult Register(RegisterViewModel model) { if (!ModelState.IsValid) { return View(model); } var user new ApplicationUser { UserName model.Email, Email model.Email }; var result await _userManager.CreateAsync(user, model.Password); if (!result.Succeeded) { foreach (var error in result.Errors) { ModelState.AddModelError(string.Empty, error.Description); } return View(model); } return RedirectToAction(Login); }登錄用SignInManager[HttpPost] public async TaskIActionResult Login(LoginViewModel model) { if (!ModelState.IsValid) { return View(model); } var result await _signInManager.PasswordSignInAsync( model.Email, model.Password, model.RememberMe, lockoutOnFailure: true); if (result.Succeeded) { return RedirectToAction(Index, Home); } if (result.IsLockedOut) { ModelState.AddModelError(string.Empty, 賬號已被鎖定請稍后再試。); return View(model); } ModelState.AddModelError(string.Empty, 用戶名或密碼錯誤。); return View(model); }這里要說清楚UserManager和SignInManager的分工這是我見過很多新人最容易搞混的地方。簡單來說UserManager管的是用戶數(shù)據(jù)的增刪改查和密碼相關(guān)操作SignInManager管的是“登錄狀態(tài)”的建立和銷毀。注冊用戶、改密碼、確認(rèn)郵箱用UserManager登錄、登出、判斷當(dāng)前用戶是什么狀態(tài)用SignInManager。2.4 跑通之后會看到什么數(shù)據(jù)庫遷移建好、跑起來之后你會發(fā)現(xiàn) Identity 自動生成了這些表AspNetUsers用戶主表里面已經(jīng)有Id、UserName、PasswordHash、SecurityStamp、ConcurrencyStamp等列AspNetRoles、AspNetRoleClaims角色定義和角色聲明AspNetUserClaims用戶聲明AspNetUserRoles用戶與角色的多對多關(guān)系A(chǔ)spNetUserLogins外部登錄信息AspNetUserTokens用于存儲認(rèn)證 Token第一次看到這么多表不用慌大部分在常規(guī)項目里只用得到其中三四張。后面我們會逐個說它們的使用場景。登錄成功后打開瀏覽器開發(fā)者工具能看到一個名為.AspNetCore.Identity.Application的 Cookie。這個 Cookie 是加密的你直接看內(nèi)容看不到用戶名和角色但這正是框架安全設(shè)計的一部分。3. 核心機(jī)制拆解Claim、Cookie、中間件到底是怎么協(xié)作的3.1 Claims 是什么和傳統(tǒng)角色判斷有什么區(qū)別早期做權(quán)限最常見的寫法是if (user.Role Admin)。這種硬編碼在角色一多就變得很痛苦每個控制器都要寫一遍判斷而且權(quán)限粒度只能到角色沒法說“這個用戶只能編輯他自己創(chuàng)建的文章”。Identity 把權(quán)限判斷的粒度下沉到了Claim層面。Claim 翻譯過來就是“聲明”是一條一條的鍵值對比如name 張三、role Admin、department 技術(shù)部。一個用戶的全部 Claim 組合在一起就是他的身份。當(dāng)用戶登錄成功后框架會把用戶的一些關(guān)鍵 Claim 寫入加密 Cookie。后續(xù)每個請求進(jìn)來框架解密 Cookie把這些 Claim 讀出來組裝成一個ClaimsPrincipal身份主體掛在HttpContext.User上。所以你在控制器里寫var name User.FindFirstValue(ClaimTypes.Name); var role User.FindFirstValue(ClaimTypes.Role);這個User對象不是實時查數(shù)據(jù)庫得到的而是從 Cookie 里的 Claims 還原出來的。這也是為什么修改了用戶的角色后要等 Cookie 過期或者重新登錄才生效——不是框架傻是你當(dāng)前這個請求的身份票據(jù)里還寫著舊角色。3.2 中間件的執(zhí)行時機(jī)認(rèn)證鏈路的完整過程是這樣的請求進(jìn)入UseAuthentication中間件。中間件查看請求是否攜帶認(rèn)證 Cookie。如果有用數(shù)據(jù)保護(hù) API 解密并驗證簽名。驗證通過后把 Cookie 里的 Claims 組裝成ClaimsPrincipal賦給HttpContext.User。請求繼續(xù)往下走進(jìn)入UseAuthorization。UseAuthorization根據(jù)端點上的[Authorize]特性判斷當(dāng)前用戶是否滿足訪問條件。曾經(jīng)有個同事問我“為什么我明明在OnPostLoginAsync里已經(jīng)登錄成功了但是HttpContext.User還是空的”答案就藏在步驟 4 和步驟 2 的時序里。登錄成功的那個請求本身并沒有攜帶認(rèn)證 CookieCookie 是在響應(yīng)時寫回瀏覽器的。所以只有下一個請求進(jìn)來UseAuthentication才能解析到身份。登錄請求當(dāng)前這一次的HttpContext.User自然就是空的了。我把這個原理解釋清楚你以后排查類似問題能少走很多彎路。3.3 Cookie 票據(jù)的格式與用途Authentication Cookie 里寫入的其實是受保護(hù)的數(shù)據(jù)包含 ClaimsPrincipal、票據(jù)簽發(fā)時間、過期時間以及一個用于防篡改的簽名。它在每次請求往返時都會被服務(wù)端解密、校驗簽名一旦中間有人試圖修改 Cookie 內(nèi)容簽名校驗立刻失敗該請求會被視為未認(rèn)證。有個設(shè)計細(xì)節(jié)很值得注意Identity 默認(rèn)不會在 Cookie 里存儲整個用戶對象。它存的是一個序列化后的 ClaimsPrincipal。這意味著如果你往ClaimsPrincipal里塞了一個非常大的自定義 Claim每次請求都會多花時間在序列化和反序列化上請求體積也會增大。我見過有人把一個上萬字符的文本塞進(jìn)自定義 Claim結(jié)果每次請求多了幾十毫秒。遇到這種情況正確方案是在數(shù)據(jù)庫里存數(shù)據(jù)Claim 里只存一個主鍵或標(biāo)識。3.4 [Authorize] 特性背后發(fā)生了什么[Authorize]在 MVC 里是一個過濾器在端點路由里是一個授權(quán)約定。它的核心邏輯往簡單了說就是兩步檢查當(dāng)前用戶是否已認(rèn)證HttpContext.User.Identity.IsAuthenticated是否為真。如果認(rèn)證了再檢查是否滿足指定的角色或策略。但有個細(xì)節(jié)容易讓人困惑如果你對著一個 API 接口標(biāo)了[Authorize]而未認(rèn)證用戶訪問它會返回什么默認(rèn)行為不是 401而是302 跳轉(zhuǎn)到登錄頁。因為 Cookie 認(rèn)證方案默認(rèn)的OnRedirectToLogin事件會把所有未授權(quán)請求重定向到登錄路徑。對于 MVC 頁面這是合理的但對 API 項目這就很惱人了。后面專門有一節(jié)講怎么處理。4. 實際項目里真正會碰到的擴(kuò)展需求4.1 給用戶表增加自定義字段Identity 最方便的地方在于它的擴(kuò)展性。比如我們要給用戶加一個“昵稱”和“頭像地址”字段public class ApplicationUser : IdentityUser { public string NickName { get; set; } public string AvatarUrl { get; set; } }改了用戶類數(shù)據(jù)庫上下文不用大動IdentityDbContextApplicationUser已經(jīng)把你的用戶類接進(jìn)了模型。然后做一次遷移dotnet ef migrations add AddNickNameAndAvatarToUser dotnet ef database update表結(jié)構(gòu)就多出兩列。這里有個實操細(xì)節(jié)新增字段后舊的注冊邏輯里如果沒有給NickName賦值默認(rèn)是 null頁面上就位上顯示空白。我習(xí)慣在注冊時強(qiáng)制要求填昵稱再配合IValidatableObject做校驗。否則每次還要在前端做判空處理麻煩。4.2 角色管理與基于角色的授權(quán)角色在 Identity 里有專屬的一張表AspNetRoles用戶和角色的關(guān)系在AspNetUserRoles。注冊用戶的代碼假設(shè)我們已有Admin角色if (!await _roleManager.RoleExistsAsync(Admin)) { await _roleManager.CreateAsync(new IdentityRole(Admin)); } await _userManager.AddToRoleAsync(user, Admin);然后在控制器方法上[Authorize(Roles Admin)] public IActionResult ManageUsers() { return View(); }或者放在控制器類上面標(biāo)記為整個控制器都需要 Admin 角色。這里要注意[Authorize]是可以疊加的類級別寫一個方法級別再寫一個邏輯上是 AND 關(guān)系。也就是說滿足的角色集合是交集而不是并集。這個特性在我的項目里用得很頻繁。比如后臺管理頁整組接口都要求管理員但里面單個導(dǎo)出接口又要求必須是超級管理員這樣一組合就非常靈活。4.3 Claims 授權(quán)、策略授權(quán)以及 JWT 混合認(rèn)證角色能管住粗粒度的權(quán)限但要實現(xiàn)“超過 18 歲才能訪問”或“編輯者只能改自己的文章”這種需求角色就不夠細(xì)了。Identity 的現(xiàn)代解法是策略授權(quán)。先在Program.cs里定義一個策略builder.Services.AddAuthorization(options { options.AddPolicy(Over18, policy policy.RequireClaim(Age, 18, 19, 20)); });然后在控制器上使用策略[Authorize(Policy Over18)] public IActionResult AdultSection() { return View(); }這里展示的是從 Claim 里直接判斷年齡是否符合實際項目里更推薦的做法是把年齡換算成出生日期范圍的 Claim這只是一個示意。再說說 JWT 混合。現(xiàn)在很多項目是前后端分離接口層用 JWTWeb 管理端用 Cookie。Identity 完全支持兩個認(rèn)證方案并存。注冊的時候這樣寫builder.Services.AddAuthentication() .AddIdentityCookies(options { }) .AddJwtBearer(options { options.TokenValidationParameters new TokenValidationParameters { ValidateIssuer true, ValidIssuer builder.Configuration[Jwt:Issuer], ValidateAudience true, ValidAudience builder.Configuration[Jwt:Audience], ValidateIssuerSigningKey true, IssuerSigningKey new SymmetricSecurityKey( Encoding.UTF8.GetBytes(builder.Configuration[Jwt:Key])) }; });這樣配置完成后同一個項目里有些端點接受 JWT有些端點接受 Cookie[Authorize]特性會自動根據(jù)請求攜帶的認(rèn)證方式選擇對應(yīng)的處理方案。默認(rèn)策略是“任何一個認(rèn)證方案成功就算認(rèn)證通過”。4.4 外部登錄的接入思路說句實話外部登錄在代碼層面并不復(fù)雜Identity 已經(jīng)把 Google、微信、GitHub 之類的外部登錄抽象成了AddGoogle、AddWeChat這類擴(kuò)展方法。每個外部登錄本質(zhì)上是三件事引導(dǎo)用戶跳轉(zhuǎn)到第三方授權(quán)頁。第三方授權(quán)成功后回調(diào)到你指定的 URL?？蚣苡媚玫降挠脩粜畔⒄冶镜赜脩粽也坏骄妥詣觿?chuàng)建新用戶并綁定外部登錄信息。這里有一個經(jīng)常讓新同事困惑的點為什么外部登錄回調(diào)之后明明第三方返回了用戶郵箱但本地的AspNetUsers表里卻沒建出用戶因為默認(rèn)配置下外部登錄返回的信息不會自動寫入本地用戶表需要你在回調(diào)事件里手動把ExternalLoginInfo落到UserManager中。如果你的項目允許外部登錄記得注冊一個事件處理器來處理OnCreatingTicket或回調(diào)后的用戶創(chuàng)建邏輯。5. 部署上線的配置陷阱和常見坑5.1 API 請求被 302 到登錄頁的修復(fù)這是我在前后端分離項目里被坑得最慘的一次。前端調(diào)登錄后的某個 API正常情況下應(yīng)該返回 401讓前端提示用戶重新登錄。結(jié)果服務(wù)端返回的是一個 302 的 HTML 頁面前端拿到響應(yīng)直接找不到數(shù)據(jù)。如果你也用 Cookie 認(rèn)證需要在配置 Cookie 時改掉默認(rèn)的重定向行為builder.Services.ConfigureApplicationCookie(options { 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; }; });改完之后API 請求未認(rèn)證時返回 401而 MVC 頁面仍然正常跳轉(zhuǎn)登錄。這個細(xì)節(jié)沒有寫進(jìn)任何顯眼文檔里但幾乎每個 API 項目都會踩到。5.2 數(shù)據(jù)保護(hù)密鑰導(dǎo)致的“上線第二天全掉線”Identity 的登錄 Cookie 是用 ASP.NET Core 的數(shù)據(jù)保護(hù) API加密的。這個 API 需要一個持久化的密鑰環(huán)。開發(fā)環(huán)境下密鑰環(huán)默認(rèn)放在本機(jī)用戶目錄的臨時文件夾里重啟一次機(jī)器密鑰可能就變了但開發(fā)機(jī)器基本無感。到了生產(chǎn)環(huán)境就麻煩了。假如你的應(yīng)用部署在容器里容器的臨時文件系統(tǒng)是內(nèi)存盤每次重啟容器密鑰環(huán)就丟掉。結(jié)果就是應(yīng)用一重啟所有用戶手上的 Cookie 全部失效所有人都被迫重新登錄。我第一次在生產(chǎn)環(huán)境遇到用戶集體掉線排查了很久才找到原因。后來統(tǒng)一做了配置把密鑰環(huán)持久化到共享存儲builder.Services.AddDataProtection() .PersistKeysToFileSystem(new DirectoryInfo(/secure/keys)) .SetApplicationName(myapp);SetApplicationName也很關(guān)鍵。同一個機(jī)器上部署多個應(yīng)用時如果應(yīng)用名不同解密時用的是各自的密鑰環(huán)不會串。但如果你把 Cookie 方案名改了或者想把測試環(huán)境和生產(chǎn)環(huán)境的密鑰共用應(yīng)用名不一致就會導(dǎo)致解密失敗。5.3 密碼策略過嚴(yán)導(dǎo)致的用戶體驗問題Identity 默認(rèn)的密碼策略要求長度至少 6 位、必須包含數(shù)字、必須包含非字母數(shù)字字符、必須包含大小寫字母。安全性當(dāng)然沒問題但面對的是普通用戶群體時這個策略會讓注冊轉(zhuǎn)化率直線下降。我通常會按業(yè)務(wù)場景微調(diào)builder.Services.AddIdentityApplicationUser, IdentityRole(options { options.Password.RequiredLength 8; options.Password.RequireDigit true; options.Password.RequireNonAlphanumeric false; options.Password.RequireUppercase true; options.Password.RequireLowercase true; options.Lockout.DefaultLockoutTimeSpan TimeSpan.FromMinutes(5); options.Lockout.MaxFailedAccessAttempts 5; })這里拆開說一下。RequireNonAlphanumeric false意思是允許純字母數(shù)字組合密碼對很多非技術(shù)用戶來說他們很難理解為什么不能設(shè)置一個“只有字母和數(shù)字”的密碼。但保留大小寫和數(shù)字組合安全性依然夠用。鎖定策略默認(rèn)是 5 次失敗鎖 5 分鐘這個對 SaaS 類產(chǎn)品偏短對后臺管理系統(tǒng)偏寬松根據(jù)你的業(yè)務(wù)負(fù)載來定。5.4 登錄狀態(tài)異常丟失的排查思路不少開發(fā)者在實際項目里會遇到“用戶明明登錄了過了兩三分鐘又讓我重新登錄”的情況。這類問題排查時我一般先看三處第一Cookie 的過期時間。默認(rèn)配置下 Cookie 是會話級別的只有 14 天內(nèi)的滑動過期行為。具體來說只要用戶在有效期內(nèi)有操作過期時間就自動延長。如果你配置了較短的ExpireTimeSpan用戶閑置一會就會掉線。這個參數(shù)要按業(yè)務(wù)來調(diào)。第二SecurityStamp機(jī)制。Identity 里有一種“強(qiáng)制注銷所有會話”的設(shè)計當(dāng)用戶改密碼、被管理員禁用、或者角色發(fā)生變化時SecurityStamp會更新。而 Cookie 里的 stamp 和數(shù)據(jù)庫里的 stamp 不一致時下一個請求就會觸發(fā)重新驗證導(dǎo)致登錄狀態(tài)失效。如果你頻繁修改用戶數(shù)據(jù)可能會讓用戶一直在“剛登錄→狀態(tài)失效→再登錄”的循環(huán)里。第三多域名部署。Cookie 是有域限制的如果你應(yīng)用同時跑在www.example.com和admin.example.com下它們之間默認(rèn)不共享 Cookie。需要正確配置Cookie.Domain或者把兩個站點放在同一個父域下。這個坑非常隱蔽因為本機(jī)開發(fā)時完全看不出來。5.5 用戶被鎖定后的提示要友好PasswordSignInAsync的lockoutOnFailure: true參數(shù)打開后如果用戶連續(xù)輸錯密碼賬號會被鎖定。但是默認(rèn)的行為是鎖定期內(nèi)繼續(xù)輸錯仍然提示“用戶名或密碼錯誤”不會明確告訴你賬號鎖定了。這個設(shè)計是出于安全考慮——避免泄露賬號鎖定狀態(tài)給攻擊者。但對真實用戶來說一直提示密碼錯誤會讓人以為是自己記錯了然后反復(fù)嘗試越試越鎖。我的處理方式是在登錄頁面加一個提示鎖定期內(nèi)再次嘗試就給一個明顯的提示比如“賬號已鎖定請 X 分鐘后再試”。畢竟對正常用戶來說明確告知并不會降低多少安全性但體驗提升非常明顯。6. 上線前要做的幾個收尾動作與我的最終建議跑通注冊登錄只是開始真正上線前還要把幾件事做掉。第一郵箱確認(rèn)。我見過不少項目直接省略郵箱確認(rèn)功能。如果你是做面向公眾的產(chǎn)品用戶用假郵箱注冊會帶來很多問題垃圾賬號、找回密碼失敗、營銷觸達(dá)質(zhì)量差。Identity 里郵箱確認(rèn)的實現(xiàn)并不復(fù)雜注冊后生成確認(rèn) Token發(fā)郵件點擊鏈接后ConfirmEmailAsync。默認(rèn)登錄邏輯里還可以配置成“未確認(rèn)郵箱的用戶不能登錄”options.SignIn.RequireConfirmedEmail true;第二密碼重置流程。不要自己寫 Token 生成邏輯。Identity 的GeneratePasswordResetTokenAsync生成的 Token 里內(nèi)置了防猜測和防篡改機(jī)制而且是綁定到用戶安全戳上的。如果你自己搞一個隨機(jī)字符串安全性大概率不如框架現(xiàn)成方案。第三啟用審計日志。用戶登錄成功、失敗、被鎖定這些事件默認(rèn)沒有任何記錄。線上出問題時你能拿到的數(shù)據(jù)非常少。我是用中間件把這些事件接出來寫進(jìn)結(jié)構(gòu)化日志里。后面排查問題時登錄日志幾乎是第一手證據(jù)。最后說一下我個人的經(jīng)驗總結(jié)吧。用 Identity 這幾年我最深的感受是不要貪多把 Cookie 認(rèn)證這一套核心機(jī)制徹底吃透比什么都管用。外部登錄、JWT、雙因素認(rèn)證這些東西都是在一個穩(wěn)固的認(rèn)證基座上加的模塊。你只要搞清楚 Claims 怎么流轉(zhuǎn)、Cookie 票據(jù)什么時候?qū)懭牒托ｒ?、SecurityStamp 的觸發(fā)條件遇到任何奇怪問題都能自己排查不會每次都在社區(qū)里做伸手黨。項目初期我給模擬項目 X 接 Identity 花了兩天后來再給另一個系統(tǒng)接只花了半天。區(qū)別就在于第一遍踩坑之后把每個配置項背后的原理都摸了一遍。這篇東西如果能把你在 Identity 上的試錯成本降低哪怕一半我覺得就沒有白寫。 ASP.NET Core Identity實戰(zhàn)：從Session登錄驗證到Cookie與Claims權(quán)限管理
1. 自己用 Session 做登錄驗證問題出在哪我最早做 Web 開發(fā)那會兒身份驗證這塊見過很多同事拿 Session 硬拼。用戶登錄成功了就往 Session 里塞一個 UserId每個請求進(jìn)來自己判斷 Session 里有沒有值沒有就跳回登錄頁。這套做法在 demo 和小工具里確實能跑但項目一旦多幾個用戶、多幾個接口問題就冒出來了Session 失效、重啟、多機(jī)負(fù)載均衡時 Session 不同步用戶動不動就掉線密碼只能拿 MD5 或 SHA 存撞庫風(fēng)險高完全沒有加鹽和迭代設(shè)計忘了做鎖定策略爆破攻擊可以無限試密碼角色、權(quán)限、用戶信息全部散落在業(yè)務(wù)代碼里每個控制器自己寫一套判斷邏輯。后來切到ASP.NET Core Identity之后這些東西全部變成了框架能力密碼哈希由它管、Cookie 票據(jù)由它管、鎖定策略由它管、角色和聲明由它管甚至郵箱確認(rèn)、手機(jī)號確認(rèn)、外部登錄的 Token 存儲都有現(xiàn)成的抽象。這篇文章我不會去復(fù)述官方文檔而是按我實際改造一個模擬項目 X 的過程來講怎么從零接上 Identity、跑通注冊登錄再把容易踩的坑挨個說清楚。這套內(nèi)容適合誰剛?cè)胧?ASP.NET Core、準(zhǔn)備把用戶系統(tǒng)從自研 Session 方案換成框架方案的開發(fā)者以及已經(jīng)在用 Identity 但只停留在“能登錄”階段、想搞清楚 Cookie 和 Claims 原理的人。2. 最小可跑的搭建流程從空項目到注冊登錄2.1 創(chuàng)建項目與引入身份相關(guān)包先建一個 ASP.NET Core MVC 項目我用的是 .NET 8。模板自帶空的結(jié)構(gòu)就行不需要勾選“個人用戶賬戶”因為那個模板幫你把一堆代碼生成了反而看不清每部分在干什么。需要引入的 NuGet 包有這些Microsoft.AspNetCore.Identity.EntityFrameworkCoreMicrosoft.EntityFrameworkCore.SqlServer如果用 SQL Server別的庫也支持Microsoft.AspNetCore.Identity.UI提供默認(rèn)的 Razor 身份頁面但后面我會講為什么我一般不直接用很多人會漏掉第二個包結(jié)果寫UseSqlServer時編譯報錯一臉懵。EntityFrameworkCore 容器擴(kuò)展方法在Microsoft.EntityFrameworkCore.SqlServer這個包里不是身份包自帶的。2.2 配置數(shù)據(jù)庫上下文與 Identity 服務(wù)注冊我習(xí)慣的做法是新建一個用戶類繼承IdentityUser哪怕現(xiàn)在不擴(kuò)展任何字段也要留好擴(kuò)展口子public class ApplicationUser : IdentityUser { }再建數(shù)據(jù)庫上下文繼承IdentityDbContextApplicationUserpublic class AppDbContext : IdentityDbContextApplicationUser { public AppDbContext(DbContextOptionsAppDbContext options) : base(options) { } }然后在Program.cs里注冊builder.Services.AddDbContextAppDbContext(options options.UseSqlServer(builder.Configuration.GetConnectionString(DefaultConnection))); builder.Services.AddIdentityApplicationUser, IdentityRole(options { }) .AddEntityFrameworkStoresAppDbContext() .AddDefaultTokenProviders();AddDefaultTokenProviders容易被忽略但 email 確認(rèn)、忘記密碼、雙因素驗證的 Token 全靠它生成。不加的話后面用到GenerateEmailConfirmationTokenAsync時會直接拋異常。中間件的順序也很有講究app.UseAuthentication(); app.UseAuthorization();必須在UseAuthorization之前先UseAuthentication否則[Authorize]拿到的HttpContext.User一直是空的。這個順序錯了最常見的問題就是所有標(biāo)記了[Authorize]的頁面全部 302 到登錄頁因為框架根本不認(rèn)識當(dāng)前用戶。2.3 注冊和登錄的控制器與頁面我不直接用 Identity UI 的 Razor 頁面而是自己寫控制器操作。原因有兩個一是方便看執(zhí)行流程二是很多項目需要定制字段和跳轉(zhuǎn)邏輯自己寫比改生成代碼更干凈。注冊操作核心邏輯用UserManager[HttpPost] public async TaskIActionResult Register(RegisterViewModel model) { if (!ModelState.IsValid) { return View(model); } var user new ApplicationUser { UserName model.Email, Email model.Email }; var result await _userManager.CreateAsync(user, model.Password); if (!result.Succeeded) { foreach (var error in result.Errors) { ModelState.AddModelError(string.Empty, error.Description); } return View(model); } return RedirectToAction(Login); }登錄用SignInManager[HttpPost] public async TaskIActionResult Login(LoginViewModel model) { if (!ModelState.IsValid) { return View(model); } var result await _signInManager.PasswordSignInAsync( model.Email, model.Password, model.RememberMe, lockoutOnFailure: true); if (result.Succeeded) { return RedirectToAction(Index, Home); } if (result.IsLockedOut) { ModelState.AddModelError(string.Empty, 賬號已被鎖定請稍后再試。); return View(model); } ModelState.AddModelError(string.Empty, 用戶名或密碼錯誤。); return View(model); }這里要說清楚UserManager和SignInManager的分工這是我見過很多新人最容易搞混的地方。簡單來說UserManager管的是用戶數(shù)據(jù)的增刪改查和密碼相關(guān)操作SignInManager管的是“登錄狀態(tài)”的建立和銷毀。注冊用戶、改密碼、確認(rèn)郵箱用UserManager登錄、登出、判斷當(dāng)前用戶是什么狀態(tài)用SignInManager。2.4 跑通之后會看到什么數(shù)據(jù)庫遷移建好、跑起來之后你會發(fā)現(xiàn) Identity 自動生成了這些表AspNetUsers用戶主表里面已經(jīng)有Id、UserName、PasswordHash、SecurityStamp、ConcurrencyStamp等列AspNetRoles、AspNetRoleClaims角色定義和角色聲明AspNetUserClaims用戶聲明AspNetUserRoles用戶與角色的多對多關(guān)系A(chǔ)spNetUserLogins外部登錄信息AspNetUserTokens用于存儲認(rèn)證 Token第一次看到這么多表不用慌大部分在常規(guī)項目里只用得到其中三四張。后面我們會逐個說它們的使用場景。登錄成功后打開瀏覽器開發(fā)者工具能看到一個名為.AspNetCore.Identity.Application的 Cookie。這個 Cookie 是加密的你直接看內(nèi)容看不到用戶名和角色但這正是框架安全設(shè)計的一部分。3. 核心機(jī)制拆解Claim、Cookie、中間件到底是怎么協(xié)作的3.1 Claims 是什么和傳統(tǒng)角色判斷有什么區(qū)別早期做權(quán)限最常見的寫法是if (user.Role Admin)。這種硬編碼在角色一多就變得很痛苦每個控制器都要寫一遍判斷而且權(quán)限粒度只能到角色沒法說“這個用戶只能編輯他自己創(chuàng)建的文章”。Identity 把權(quán)限判斷的粒度下沉到了Claim層面。Claim 翻譯過來就是“聲明”是一條一條的鍵值對比如name 張三、role Admin、department 技術(shù)部。一個用戶的全部 Claim 組合在一起就是他的身份。當(dāng)用戶登錄成功后框架會把用戶的一些關(guān)鍵 Claim 寫入加密 Cookie。后續(xù)每個請求進(jìn)來框架解密 Cookie把這些 Claim 讀出來組裝成一個ClaimsPrincipal身份主體掛在HttpContext.User上。所以你在控制器里寫var name User.FindFirstValue(ClaimTypes.Name); var role User.FindFirstValue(ClaimTypes.Role);這個User對象不是實時查數(shù)據(jù)庫得到的而是從 Cookie 里的 Claims 還原出來的。這也是為什么修改了用戶的角色后要等 Cookie 過期或者重新登錄才生效——不是框架傻是你當(dāng)前這個請求的身份票據(jù)里還寫著舊角色。3.2 中間件的執(zhí)行時機(jī)認(rèn)證鏈路的完整過程是這樣的請求進(jìn)入UseAuthentication中間件。中間件查看請求是否攜帶認(rèn)證 Cookie。如果有用數(shù)據(jù)保護(hù) API 解密并驗證簽名。驗證通過后把 Cookie 里的 Claims 組裝成ClaimsPrincipal賦給HttpContext.User。請求繼續(xù)往下走進(jìn)入UseAuthorization。UseAuthorization根據(jù)端點上的[Authorize]特性判斷當(dāng)前用戶是否滿足訪問條件。曾經(jīng)有個同事問我“為什么我明明在OnPostLoginAsync里已經(jīng)登錄成功了但是HttpContext.User還是空的”答案就藏在步驟 4 和步驟 2 的時序里。登錄成功的那個請求本身并沒有攜帶認(rèn)證 CookieCookie 是在響應(yīng)時寫回瀏覽器的。所以只有下一個請求進(jìn)來UseAuthentication才能解析到身份。登錄請求當(dāng)前這一次的HttpContext.User自然就是空的了。我把這個原理解釋清楚你以后排查類似問題能少走很多彎路。3.3 Cookie 票據(jù)的格式與用途Authentication Cookie 里寫入的其實是受保護(hù)的數(shù)據(jù)包含 ClaimsPrincipal、票據(jù)簽發(fā)時間、過期時間以及一個用于防篡改的簽名。它在每次請求往返時都會被服務(wù)端解密、校驗簽名一旦中間有人試圖修改 Cookie 內(nèi)容簽名校驗立刻失敗該請求會被視為未認(rèn)證。有個設(shè)計細(xì)節(jié)很值得注意Identity 默認(rèn)不會在 Cookie 里存儲整個用戶對象。它存的是一個序列化后的 ClaimsPrincipal。這意味著如果你往ClaimsPrincipal里塞了一個非常大的自定義 Claim每次請求都會多花時間在序列化和反序列化上請求體積也會增大。我見過有人把一個上萬字符的文本塞進(jìn)自定義 Claim結(jié)果每次請求多了幾十毫秒。遇到這種情況正確方案是在數(shù)據(jù)庫里存數(shù)據(jù)Claim 里只存一個主鍵或標(biāo)識。3.4 [Authorize] 特性背后發(fā)生了什么[Authorize]在 MVC 里是一個過濾器在端點路由里是一個授權(quán)約定。它的核心邏輯往簡單了說就是兩步檢查當(dāng)前用戶是否已認(rèn)證HttpContext.User.Identity.IsAuthenticated是否為真。如果認(rèn)證了再檢查是否滿足指定的角色或策略。但有個細(xì)節(jié)容易讓人困惑如果你對著一個 API 接口標(biāo)了[Authorize]而未認(rèn)證用戶訪問它會返回什么默認(rèn)行為不是 401而是302 跳轉(zhuǎn)到登錄頁。因為 Cookie 認(rèn)證方案默認(rèn)的OnRedirectToLogin事件會把所有未授權(quán)請求重定向到登錄路徑。對于 MVC 頁面這是合理的但對 API 項目這就很惱人了。后面專門有一節(jié)講怎么處理。4. 實際項目里真正會碰到的擴(kuò)展需求4.1 給用戶表增加自定義字段Identity 最方便的地方在于它的擴(kuò)展性。比如我們要給用戶加一個“昵稱”和“頭像地址”字段public class ApplicationUser : IdentityUser { public string NickName { get; set; } public string AvatarUrl { get; set; } }改了用戶類數(shù)據(jù)庫上下文不用大動IdentityDbContextApplicationUser已經(jīng)把你的用戶類接進(jìn)了模型。然后做一次遷移dotnet ef migrations add AddNickNameAndAvatarToUser dotnet ef database update表結(jié)構(gòu)就多出兩列。這里有個實操細(xì)節(jié)新增字段后舊的注冊邏輯里如果沒有給NickName賦值默認(rèn)是 null頁面上就位上顯示空白。我習(xí)慣在注冊時強(qiáng)制要求填昵稱再配合IValidatableObject做校驗。否則每次還要在前端做判空處理麻煩。4.2 角色管理與基于角色的授權(quán)角色在 Identity 里有專屬的一張表AspNetRoles用戶和角色的關(guān)系在AspNetUserRoles。注冊用戶的代碼假設(shè)我們已有Admin角色if (!await _roleManager.RoleExistsAsync(Admin)) { await _roleManager.CreateAsync(new IdentityRole(Admin)); } await _userManager.AddToRoleAsync(user, Admin);然后在控制器方法上[Authorize(Roles Admin)] public IActionResult ManageUsers() { return View(); }或者放在控制器類上面標(biāo)記為整個控制器都需要 Admin 角色。這里要注意[Authorize]是可以疊加的類級別寫一個方法級別再寫一個邏輯上是 AND 關(guān)系。也就是說滿足的角色集合是交集而不是并集。這個特性在我的項目里用得很頻繁。比如后臺管理頁整組接口都要求管理員但里面單個導(dǎo)出接口又要求必須是超級管理員這樣一組合就非常靈活。4.3 Claims 授權(quán)、策略授權(quán)以及 JWT 混合認(rèn)證角色能管住粗粒度的權(quán)限但要實現(xiàn)“超過 18 歲才能訪問”或“編輯者只能改自己的文章”這種需求角色就不夠細(xì)了。Identity 的現(xiàn)代解法是策略授權(quán)。先在Program.cs里定義一個策略builder.Services.AddAuthorization(options { options.AddPolicy(Over18, policy policy.RequireClaim(Age, 18, 19, 20)); });然后在控制器上使用策略[Authorize(Policy Over18)] public IActionResult AdultSection() { return View(); }這里展示的是從 Claim 里直接判斷年齡是否符合實際項目里更推薦的做法是把年齡換算成出生日期范圍的 Claim這只是一個示意。再說說 JWT 混合。現(xiàn)在很多項目是前后端分離接口層用 JWTWeb 管理端用 Cookie。Identity 完全支持兩個認(rèn)證方案并存。注冊的時候這樣寫builder.Services.AddAuthentication() .AddIdentityCookies(options { }) .AddJwtBearer(options { options.TokenValidationParameters new TokenValidationParameters { ValidateIssuer true, ValidIssuer builder.Configuration[Jwt:Issuer], ValidateAudience true, ValidAudience builder.Configuration[Jwt:Audience], ValidateIssuerSigningKey true, IssuerSigningKey new SymmetricSecurityKey( Encoding.UTF8.GetBytes(builder.Configuration[Jwt:Key])) }; });這樣配置完成后同一個項目里有些端點接受 JWT有些端點接受 Cookie[Authorize]特性會自動根據(jù)請求攜帶的認(rèn)證方式選擇對應(yīng)的處理方案。默認(rèn)策略是“任何一個認(rèn)證方案成功就算認(rèn)證通過”。4.4 外部登錄的接入思路說句實話外部登錄在代碼層面并不復(fù)雜Identity 已經(jīng)把 Google、微信、GitHub 之類的外部登錄抽象成了AddGoogle、AddWeChat這類擴(kuò)展方法。每個外部登錄本質(zhì)上是三件事引導(dǎo)用戶跳轉(zhuǎn)到第三方授權(quán)頁。第三方授權(quán)成功后回調(diào)到你指定的 URL?？蚣苡媚玫降挠脩粜畔⒄冶镜赜脩粽也坏骄妥詣觿?chuàng)建新用戶并綁定外部登錄信息。這里有一個經(jīng)常讓新同事困惑的點為什么外部登錄回調(diào)之后明明第三方返回了用戶郵箱但本地的AspNetUsers表里卻沒建出用戶因為默認(rèn)配置下外部登錄返回的信息不會自動寫入本地用戶表需要你在回調(diào)事件里手動把ExternalLoginInfo落到UserManager中。如果你的項目允許外部登錄記得注冊一個事件處理器來處理OnCreatingTicket或回調(diào)后的用戶創(chuàng)建邏輯。5. 部署上線的配置陷阱和常見坑5.1 API 請求被 302 到登錄頁的修復(fù)這是我在前后端分離項目里被坑得最慘的一次。前端調(diào)登錄后的某個 API正常情況下應(yīng)該返回 401讓前端提示用戶重新登錄。結(jié)果服務(wù)端返回的是一個 302 的 HTML 頁面前端拿到響應(yīng)直接找不到數(shù)據(jù)。如果你也用 Cookie 認(rèn)證需要在配置 Cookie 時改掉默認(rèn)的重定向行為builder.Services.ConfigureApplicationCookie(options { 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; }; });改完之后API 請求未認(rèn)證時返回 401而 MVC 頁面仍然正常跳轉(zhuǎn)登錄。這個細(xì)節(jié)沒有寫進(jìn)任何顯眼文檔里但幾乎每個 API 項目都會踩到。5.2 數(shù)據(jù)保護(hù)密鑰導(dǎo)致的“上線第二天全掉線”Identity 的登錄 Cookie 是用 ASP.NET Core 的數(shù)據(jù)保護(hù) API加密的。這個 API 需要一個持久化的密鑰環(huán)。開發(fā)環(huán)境下密鑰環(huán)默認(rèn)放在本機(jī)用戶目錄的臨時文件夾里重啟一次機(jī)器密鑰可能就變了但開發(fā)機(jī)器基本無感。到了生產(chǎn)環(huán)境就麻煩了。假如你的應(yīng)用部署在容器里容器的臨時文件系統(tǒng)是內(nèi)存盤每次重啟容器密鑰環(huán)就丟掉。結(jié)果就是應(yīng)用一重啟所有用戶手上的 Cookie 全部失效所有人都被迫重新登錄。我第一次在生產(chǎn)環(huán)境遇到用戶集體掉線排查了很久才找到原因。后來統(tǒng)一做了配置把密鑰環(huán)持久化到共享存儲builder.Services.AddDataProtection() .PersistKeysToFileSystem(new DirectoryInfo(/secure/keys)) .SetApplicationName(myapp);SetApplicationName也很關(guān)鍵。同一個機(jī)器上部署多個應(yīng)用時如果應(yīng)用名不同解密時用的是各自的密鑰環(huán)不會串。但如果你把 Cookie 方案名改了或者想把測試環(huán)境和生產(chǎn)環(huán)境的密鑰共用應(yīng)用名不一致就會導(dǎo)致解密失敗。5.3 密碼策略過嚴(yán)導(dǎo)致的用戶體驗問題Identity 默認(rèn)的密碼策略要求長度至少 6 位、必須包含數(shù)字、必須包含非字母數(shù)字字符、必須包含大小寫字母。安全性當(dāng)然沒問題但面對的是普通用戶群體時這個策略會讓注冊轉(zhuǎn)化率直線下降。我通常會按業(yè)務(wù)場景微調(diào)builder.Services.AddIdentityApplicationUser, IdentityRole(options { options.Password.RequiredLength 8; options.Password.RequireDigit true; options.Password.RequireNonAlphanumeric false; options.Password.RequireUppercase true; options.Password.RequireLowercase true; options.Lockout.DefaultLockoutTimeSpan TimeSpan.FromMinutes(5); options.Lockout.MaxFailedAccessAttempts 5; })這里拆開說一下。RequireNonAlphanumeric false意思是允許純字母數(shù)字組合密碼對很多非技術(shù)用戶來說他們很難理解為什么不能設(shè)置一個“只有字母和數(shù)字”的密碼。但保留大小寫和數(shù)字組合安全性依然夠用。鎖定策略默認(rèn)是 5 次失敗鎖 5 分鐘這個對 SaaS 類產(chǎn)品偏短對后臺管理系統(tǒng)偏寬松根據(jù)你的業(yè)務(wù)負(fù)載來定。5.4 登錄狀態(tài)異常丟失的排查思路不少開發(fā)者在實際項目里會遇到“用戶明明登錄了過了兩三分鐘又讓我重新登錄”的情況。這類問題排查時我一般先看三處第一Cookie 的過期時間。默認(rèn)配置下 Cookie 是會話級別的只有 14 天內(nèi)的滑動過期行為。具體來說只要用戶在有效期內(nèi)有操作過期時間就自動延長。如果你配置了較短的ExpireTimeSpan用戶閑置一會就會掉線。這個參數(shù)要按業(yè)務(wù)來調(diào)。第二SecurityStamp機(jī)制。Identity 里有一種“強(qiáng)制注銷所有會話”的設(shè)計當(dāng)用戶改密碼、被管理員禁用、或者角色發(fā)生變化時SecurityStamp會更新。而 Cookie 里的 stamp 和數(shù)據(jù)庫里的 stamp 不一致時下一個請求就會觸發(fā)重新驗證導(dǎo)致登錄狀態(tài)失效。如果你頻繁修改用戶數(shù)據(jù)可能會讓用戶一直在“剛登錄→狀態(tài)失效→再登錄”的循環(huán)里。第三多域名部署。Cookie 是有域限制的如果你應(yīng)用同時跑在www.example.com和admin.example.com下它們之間默認(rèn)不共享 Cookie。需要正確配置Cookie.Domain或者把兩個站點放在同一個父域下。這個坑非常隱蔽因為本機(jī)開發(fā)時完全看不出來。5.5 用戶被鎖定后的提示要友好PasswordSignInAsync的lockoutOnFailure: true參數(shù)打開后如果用戶連續(xù)輸錯密碼賬號會被鎖定。但是默認(rèn)的行為是鎖定期內(nèi)繼續(xù)輸錯仍然提示“用戶名或密碼錯誤”不會明確告訴你賬號鎖定了。這個設(shè)計是出于安全考慮——避免泄露賬號鎖定狀態(tài)給攻擊者。但對真實用戶來說一直提示密碼錯誤會讓人以為是自己記錯了然后反復(fù)嘗試越試越鎖。我的處理方式是在登錄頁面加一個提示鎖定期內(nèi)再次嘗試就給一個明顯的提示比如“賬號已鎖定請 X 分鐘后再試”。畢竟對正常用戶來說明確告知并不會降低多少安全性但體驗提升非常明顯。6. 上線前要做的幾個收尾動作與我的最終建議跑通注冊登錄只是開始真正上線前還要把幾件事做掉。第一郵箱確認(rèn)。我見過不少項目直接省略郵箱確認(rèn)功能。如果你是做面向公眾的產(chǎn)品用戶用假郵箱注冊會帶來很多問題垃圾賬號、找回密碼失敗、營銷觸達(dá)質(zhì)量差。Identity 里郵箱確認(rèn)的實現(xiàn)并不復(fù)雜注冊后生成確認(rèn) Token發(fā)郵件點擊鏈接后ConfirmEmailAsync。默認(rèn)登錄邏輯里還可以配置成“未確認(rèn)郵箱的用戶不能登錄”options.SignIn.RequireConfirmedEmail true;第二密碼重置流程。不要自己寫 Token 生成邏輯。Identity 的GeneratePasswordResetTokenAsync生成的 Token 里內(nèi)置了防猜測和防篡改機(jī)制而且是綁定到用戶安全戳上的。如果你自己搞一個隨機(jī)字符串安全性大概率不如框架現(xiàn)成方案。第三啟用審計日志。用戶登錄成功、失敗、被鎖定這些事件默認(rèn)沒有任何記錄。線上出問題時你能拿到的數(shù)據(jù)非常少。我是用中間件把這些事件接出來寫進(jìn)結(jié)構(gòu)化日志里。后面排查問題時登錄日志幾乎是第一手證據(jù)。最后說一下我個人的經(jīng)驗總結(jié)吧。用 Identity 這幾年我最深的感受是不要貪多把 Cookie 認(rèn)證這一套核心機(jī)制徹底吃透比什么都管用。外部登錄、JWT、雙因素認(rèn)證這些東西都是在一個穩(wěn)固的認(rèn)證基座上加的模塊。你只要搞清楚 Claims 怎么流轉(zhuǎn)、Cookie 票據(jù)什么時候?qū)懭牒托ｒ?、SecurityStamp 的觸發(fā)條件遇到任何奇怪問題都能自己排查不會每次都在社區(qū)里做伸手黨。項目初期我給模擬項目 X 接 Identity 花了兩天后來再給另一個系統(tǒng)接只花了半天。區(qū)別就在于第一遍踩坑之后把每個配置項背后的原理都摸了一遍。這篇東西如果能把你在 Identity 上的試錯成本降低哪怕一半我覺得就沒有白寫。