簡介Sustainsys.Saml2原稱Kentor.AuthServices是一個面向ASP.NET開發(fā)者的開源身份驗證庫以C#語言實現(xiàn)用來為網(wǎng)站增加SAML2協(xié)議能力使其能夠作為服務(wù)提供方與身份提供方完成單點登錄對接。資源包共含883個文件大小約5.64MB其中以C#源文件和頁面視圖居多同時提供了大量配置文件、頁面樣式與腳本、測試證書以及完整的項目工程文件可用于還原出可運行的示例站點與聯(lián)調(diào)環(huán)境。源碼按三個版本分支組織第一個分支基于舊版標(biāo)識模型兼容傳統(tǒng)模塊與多種框架第二個分支使用新版標(biāo)識模型支持多目標(biāo)框架第三個分支則專為新一代核心框架設(shè)計。對于需要在自己項目中實現(xiàn)SAML2認證、研究服務(wù)提供方與身份提供方交互細節(jié)的開發(fā)者這份材料提供了可直接參考的源碼、配置模板和證書樣例當(dāng)前已有525人學(xué)習(xí)下載同時可借助分支對比來輔助版本遷移與二次開發(fā)。1. 為什么要在 ASP.NET 里專門做一個 SAML2 身份驗證服務(wù)接手過幾次企業(yè)級接入后你會發(fā)現(xiàn)SAML2 身份驗證服務(wù)真正難的從來不是“驗證簽名”和“解析 XML”而是把整個跳轉(zhuǎn)鏈路、信任關(guān)系、會話狀態(tài)串起來。很多團隊第一次接入時想得很簡單把 IdP 給的證書拿來在自己站點里驗一下斷言就完事。結(jié)果一上線就翻車——不是跳不回來就是簽名字節(jié)對不上再不就是登錄成功后用戶信息全是空的。這套東西最反直覺的地方在于它能跑通不代表你理解了它一旦某個參數(shù)兩邊各寫各的你面對的就是一條無法從應(yīng)用日志里直接看出原因的黑匣子鏈。這篇文章要講的是在 ASP.NET 平臺上把 SAML2 服務(wù)提供方SP完整落地的方法覆蓋從協(xié)議拆解、最小可運行實現(xiàn)、核心參數(shù)調(diào)整到線上排錯的全過程。不管你是要接入客戶的統(tǒng)一身份平臺還是打算把自己的系統(tǒng)對接到公司內(nèi)部的單點登錄體系只要涉及“讓 ASP.NET 應(yīng)用聽懂 SAML2 斷言”下面這些內(nèi)容都能直接拿來用?？赐昴隳塥毩⒋畛隹山桓兜纳矸蒡炞C接入層并知道出了問題該看哪里。2. 拆開 SAML2消息、跳轉(zhuǎn)與信任模型這三件事2.1 三類核心消息斷言、協(xié)議消息與綁定方式SAML2 里的有效載荷是“斷言”Assertion一段攜帶用戶身份信息的 XML。斷言內(nèi)部又分三種語句認證語句AuthnStatement聲明“用戶在某時刻通過某方式完成了認證”屬性語句AttributeStatement攜帶郵箱、姓名、角色這類擴展屬性授權(quán)決策語句AuthorizationDecisionStatement聲明“允許該用戶訪問某資源”。對 ASP.NET 開發(fā)者來說平時處理的絕大多數(shù)場景只用到前兩種授權(quán)決策一般交給應(yīng)用自身的策略引擎很少直接從斷言里讀。真正在網(wǎng)絡(luò)上傳輸?shù)牟恢皇菙嘌远前褦嘌浴鞍饋怼钡膮f(xié)議消息。SP 向 IdP 發(fā)起認證時發(fā)送 AuthnRequestIdP 處理完把用戶瀏覽器導(dǎo)回 SP 時攜帶 AuthnResponse。這兩條消息分別解決了“你是誰”和“我證明你確實是誰”。而綁定方式?jīng)Q定了消息怎么走最常見的是 HTTP Redirect 綁定適合發(fā)送 AuthnRequest因為 GET 參數(shù)長度有限卻足夠放進一個沒有大量擴展的請求另一個是 HTTP POST 綁定IdP 回傳斷言時幾乎都用它因為簽名后的 XML 體積大塞進 URL 不現(xiàn)實。在代碼層面你收到的 AuthnResponse 是一段需要驗證的 XML。這里有一個非常關(guān)鍵的建議不要自己寫 XML 解析器。SAML2 的簽名驗證涉及 XML 規(guī)范化Canonicalization、XPath 定位簽名節(jié)點、摘要重算手寫解析在邊緣環(huán)境下有數(shù)不清的兼容問題。我在生產(chǎn)環(huán)境里見過某個團隊手寫了半年最后還是換成了現(xiàn)成的中間件。.NET 生態(tài)里目前活躍度最高、生產(chǎn)驗證最充分的 SAML2 社區(qū)包就那么一個成熟選擇直接引入它把精力放到業(yè)務(wù)適配和排錯上這才是性價比最高的路線。2.2 兩條登錄主線SP 發(fā)起的跳轉(zhuǎn)與 IdP 發(fā)起的跳轉(zhuǎn)SP 發(fā)起的登錄流程是大多數(shù)接入場景的主干。用戶訪問你的 ASP.NET 站點里一個受保護的頁面中間件發(fā)現(xiàn)當(dāng)前會話沒有認證信息于是生成一條 AuthnRequest附上簽名后用 Redirect 綁定把用戶瀏覽器帶到 IdP 的登錄端點。用戶在 IdP 完成密碼、短信或掃碼認證后IdP 在后臺生成斷言把瀏覽器用 POST 表單導(dǎo)回你的 ACSAssertion Consumer Service地址。你的站點收到 POST驗簽、校驗斷言、提取用戶標(biāo)識然后建立本地會話把用戶引導(dǎo)回最初想訪問的那個頁面。IdP 發(fā)起的登錄則完全反過來用戶先登錄公司門戶門戶里展示一排可訪問的系統(tǒng)圖標(biāo)用戶點某個系統(tǒng)的入口IdP 直接在瀏覽器里生成一條 POST 到該系統(tǒng) ACS 地址。你的 SP 沒有發(fā)起過任何請求卻在某個時刻突然收到一條斷言。這帶來一個很隱蔽的問題你無法校驗“InResponseTo”——這條斷言到底是不是響應(yīng)你發(fā)出的上一條請求因為根本不存在上一條請求。所以 IdP 發(fā)起的流程里必須格外依賴簽名驗證和受眾校驗一旦跳過攻擊者可以嘗試重放別人被截獲的斷言。在 ASP.NET 集成里IdP 發(fā)起的流程也是最容易在配置階段被忽略的一環(huán)。很多人測試時只測 SP 發(fā)起上線后客戶從門戶點進來發(fā)現(xiàn)直接 401。常見做法是把兩種情況都列入聯(lián)調(diào)用例并且斷言消費端點要同時容忍有 InResponseTo 和沒有 InResponseTo 的請求但在后者情況下必須做額外的 Audience 和 Recipient 校驗。2.3 信任關(guān)系如何建立證書、metadata 與簽名驗證SAML2 的信任基礎(chǔ)不是“用戶名密碼”而是證書。SP 需要持有 IdP 簽公鑰才能驗證斷言簽名IdP 也同樣需要 SP 的公鑰來驗證 AuthnRequest 簽名。雙方交換公鑰的載體叫 metadata——一份描述 EntityID、ACS 地址、證書、支持綁定方式的標(biāo)準(zhǔn) XML。實際項目中IdP 通常給你一個 metadata 下載地址SP 這邊則把自己 metadata 發(fā)過去登記。驗證簽名時中間件拿 IdP 的公鑰按 XML 簽名標(biāo)準(zhǔn)對斷言里的 DigestValue 重算比對通過后才信任。這個環(huán)節(jié)有個常見的幼稚錯誤以為只要有一對證書就行結(jié)果兩邊各簽各的。實際上SP 自己那對證書用來給 AuthnRequest 簽名IdP 的證書用來驗斷言兩把證書鏈路完全不同。彼此是通過 metadata 里的 KeyDescriptor 標(biāo)簽區(qū)分用途的signing 標(biāo)簽對應(yīng)簽名密鑰encryption 標(biāo)簽對應(yīng)解密密鑰。配置時如果選錯了哪把鑰匙等待你的只有一個結(jié)果——簽名驗證失敗。3. 搭一個能跑通的最小實現(xiàn)從空項目到本地首登3.1 環(huán)境準(zhǔn)備項目模板與證書生成做 SAML2 接入前先準(zhǔn)備好一個空 ASP.NET Core MVC 項目。我一直習(xí)慣從空模板起步因為 SAML2 中間件的注冊邏輯要放在中間件管線的特定位置模板自帶的東西有時候反而礙事。項目創(chuàng)建命令很簡單dotnet new mvc -n SpSample cd SpSample dotnet add package Itfoxtec.Saml2第二行命令拉取的是 .NET 生態(tài)里那個最主流的 SAML2 中間件包。我一般不會在文章里反復(fù)強調(diào)某個包的名字但在 SAML2 這個領(lǐng)域可選項實在太少這個包幾乎是事實標(biāo)準(zhǔn)。它處理了 AuthnRequest 生成、AuthnResponse 解析、簽名驗證、RelayState 管理這些臟活你要做的是把業(yè)務(wù)參數(shù)喂給它。然后生成 SP 自己的簽名證書openssl req -x509 -newkey rsa:2048 -keyout sp-signing.key -out sp-signing.crt -days 365 -nodes -subj /CNsp.sample.local這里生成的證書是 SP 用來簽名 AuthnRequest 的不是 IdP 那個驗證用的證書。注意-nodes參數(shù)表示私鑰不加密生產(chǎn)環(huán)境絕對不能這樣用開發(fā)環(huán)境圖省事可以。證書有效期設(shè)一年因為 SAML2 的 metadata 里會帶上證書有效期IdP 側(cè)如果嚴(yán)格校驗過期證書會導(dǎo)致請求被直接拒絕。3.2 中間件注冊順序與配置SAML2 中間件的注冊順序有講究。它必須放在 UseAuthentication 之前因為它要接管的是“這條請求是不是攜帶了一個可信任的身份斷言”這件事。放在后面注冊會導(dǎo)致請求先被別的中間件處理完了斷言還沒被解析。代碼里這樣注冊builder.Services.AddSaml2(options { options.SPOptions.EntityId new EntityId(urn:sp:sample); options.SPOptions.ReturnUrl new Uri(https://sp.sample.local/saml2/acs); options.SPOptions.SignatureAlgorithm Saml2SignatureAlgorithm.RsaSha256; var signingCert new X509Certificate2(sp-signing.crt, password); options.SPOptions.SigningCertificate signingCert; var idpMetadata new IdpMetadata(new X509Certificate2(idp-signing.crt), new Uri(https://idp.sample.local/realms/main)); options.IdentityProviders.Add(new IdentityProvider(idp, idpMetadata)); }); app.UseSaml2();這段配置里有幾個參數(shù)必須解釋清楚。EntityId是你的 SP 在全聯(lián)邦里的唯一名字IdP 端看到的 SP 標(biāo)識就是它改了這個值而 IdP 沒同步斷言會被判定為來路不明。ReturnUrl是 ACS 地址IdP 會把斷言 POST 到這里它必須和 IdP 側(cè)登記的回調(diào)地址完全一致差一個路徑段都不行。SignatureAlgorithm是簽名算法現(xiàn)在基本不用 SHA1 了但有些老 IdP 只支持 SHA1SP 端配了 SHA256 就會握手失敗。SigningCertificate是第 3.1 節(jié)生成的那把證書。IdentityProviders列表里要注冊每個可信任的 IdP包括它的證書和端點地址這一步很多人會漏掉——只配了 SP 自己的證書沒配 IdP 的信息結(jié)果驗簽時找不到驗簽公鑰。3.3 本地驗證先跑通再談完善配置完成后別急著連真實 IdP先在本地搭一個最小的測試 IdP把鏈路拉通。最省事的方案是寫一個簡單的控制器來扮演 IdP 的 ACS 端點[HttpPost(saml2/acs)] public async TaskIActionResult Acs() { var binding new Saml2PostBinding(); var saml2p new Saml2AuthnResponse(SPOptions, new Saml2AuthnRequest(SPOptions)); binding.Unbind(Request, saml2p); await saml2p.CreateSession(HttpContext, null); return Redirect(/); }Saml2PostBinding負責(zé)從 POST 表單中解析 SAMLResponse 字段Unbind方法把傳輸層的參數(shù)還原成強類型的響應(yīng)對象CreateSession則是在驗證斷言有效后為用戶建立 .NET 認證會話。這段代碼邏輯上就是把“收到一條 POST 斷言”翻譯成“建立一次登錄會話”。在本地聯(lián)調(diào)時我是按三個步驟遞進的先關(guān)掉簽名驗證手工拼一個最簡斷言直接 POST確認解析和會話建立沒問題再打開簽名驗證看驗簽鏈路是否完整最后才跑完整的重定向流程。一步一步來出了問題立刻能定位是哪個環(huán)節(jié)的毛病。4. 四個必調(diào)參數(shù)與它們的邊界EntityID、簽名算法與時鐘偏移4.1 EntityID、ACS 與 metadata三個參數(shù)必須三方對齊SAML2 接入里最折磨人的一類問題是“配置明明沒錯但 IdP 就是報錯”。這類問題九成出在三方對齊上SP 端 EntityID、ACS 地址、IdP metadata 里記錄的同一份信息。你的 EntityID 寫成了urn:sp:sampleIdP 側(cè)錄入的卻是https://sp.sample.local/saml兩邊都能正常完成重定向但 IdP 生成的斷言里 Audience 會是它自己認為的那個 SP 標(biāo)識SP 驗簽時發(fā)現(xiàn) Audience 不是自己直接拒絕。ACS 地址的對齊同樣苛刻。中間件默認會根據(jù)當(dāng)前請求的 Host 頭動態(tài)拼接 ACS 地址如果你的站點跑在反向代理后面外網(wǎng) Host 和內(nèi)部服務(wù)地址不一致生成的 ACS 就會變成內(nèi)網(wǎng)地址IdP 那邊登記的是公網(wǎng)地址兩邊一比對就不匹配。排查這條路的最佳實踐是ASP.NET 服務(wù)前加上app.UseForwardedHeaders()讓中間件感知真實的客戶端 Host。我一般在配置里顯式寫死 ACS 地址而不是讓它動態(tài)生成這樣至少在復(fù)雜網(wǎng)絡(luò)環(huán)境下少一個變量。還有一種幾乎所有人都遇到過的詭異場景客戶說換證書了給了你新公鑰你也把新證書放進配置了結(jié)果驗簽還是失敗。最后發(fā)現(xiàn) IdP 的 metadata 里有新舊兩把證書名目上是“密鑰輪換”但實際請求斷言是用新證書簽的你的代碼卻在舊證書里做匹配。所以配置代碼里要支持證書的滾動查找——驗簽時先用當(dāng)前證書失敗后嘗試用備用證書再驗一次而不是只信任一把。4.2 證書與簽名算法SHA1 還是 SHA256RSA 還是 ECDSA簽名算法協(xié)商是個容易讓人頭大的點。SAML2 標(biāo)準(zhǔn)在 XML 簽名里同時支持 RSA-SHA1、RSA-SHA256、ECDSA-SHA256但并非所有 IdP 都支持全部。大型政企系統(tǒng)里有相當(dāng)一部分老舊 IdP 只支持 RSA-SHA1你的 SP 端如果強制 SHA256IdP 在驗證 AuthnRequest 簽名時會直接報錯。我通常的做法是先看 IdP 的 metadata。metadata 里的SignatureMethod標(biāo)簽會明確列出它支持的算法按這個列表配置 SP 端行為就穩(wěn)穩(wěn)的。如果你拿不到 metadata或者 IdP 文檔語焉不詳直接用 RSA-SHA256 作為默認值遇到握手失敗再降級到 SHA1。另一個容易被忽略的細節(jié)是證書密鑰長度。2048 位當(dāng)前仍是主流有些新部署已經(jīng)上了 4096 位但老 IdP 在驗證簽名時對超大密鑰的處理存在性能問題會直接把請求超時。遇到這種情況別急著改算法先看看 IdP 是否有資源側(cè)的調(diào)優(yōu)參數(shù)。4.3 時鐘偏移、斷言有效期與會話老化SAML2 斷言里有NotBefore和NotOnOrAfter兩個時間戳限定了斷言的有效期。標(biāo)準(zhǔn)里沒有強制規(guī)定有效期長度但主流 IdP 一般默認給五分鐘。這個五分鐘在正常網(wǎng)絡(luò)環(huán)境下完全夠用但有一個前提SP 和 IdP 兩邊服務(wù)器的時鐘必須大致同步?，F(xiàn)實中我踩過一次很深的坑——某個客戶的 IdP 跑在一臺時間漂移了八分鐘的服務(wù)器上SP 端一切正常但斷言里NotBefore比當(dāng)前時間晚了七分鐘SP 端判斷“斷言尚未生效”直接拒絕。解決手段有兩個層面。第一部署層面必須給服務(wù)器配置 NTP 時間同步云服務(wù)器默認做得好自建機房就容易出問題。第二代碼層面在 SAML2 配置里把允許的時鐘偏移量調(diào)大一點通常設(shè) 30 到 60 秒已經(jīng)足夠。不要設(shè)置更大的值有效期存在的意義就是防止重放攻擊無限放寬等于把安全門拆了。還有一個經(jīng)常被忽略的與會話相關(guān)的坑SAML2 斷言的五分鐘有效期和 ASP.NET 本地 Cookie 的過期時間是完全獨立的兩件事。用戶體驗是“用著用著突然跳到 IdP 要求重新登錄”但你查 SAML2 相關(guān)日志全部正常原因是本地 Cookie 過期了而新用戶在跳回時拿到的仍然是一個新的有效會話。排查這種問題時要把 Cookie 過期時間、IdP 會話策略、斷言有效期三者并列對比看哪個先到期。5. 避坑與排查SAML2 接入最常見的五個現(xiàn)場5.1 現(xiàn)象登錄成功后找不到用戶 ID用戶從 IdP 那邊登錄成功了瀏覽器也跳回了你的站點但你發(fā)現(xiàn)會話里拿不到身份標(biāo)識。查 SAML 斷言發(fā)現(xiàn) NameID 是空的或者 NameID 拿到了但郵箱、姓名全是 null。這個問題的根源基本都在屬性映射。SAML2 標(biāo)準(zhǔn)允許 IdP 在斷言里放置任意自定義屬性AttributeStatement標(biāo)簽下的每個Attribute用 Name 屬性區(qū)分。但 .NET 側(cè)的 Claims 機制期望的是一組標(biāo)準(zhǔn) ClaimType比如ClaimTypes.Email里裝的應(yīng)該是郵箱地址。而 IdP 返回的屬性名幾乎都是客戶自定義的可能是user.email也可能是mail還有可能是emailAddress。處理方法是寫一個屬性映射表把這些原始屬性名映射到 .NET Claim 類型options.SPOptions.ClaimsMapping.Add(mail, ClaimTypes.Email); options.SPOptions.ClaimsMapping.Add(employeeNumber, ClaimTypes.NameIdentifier);這段配置的意思是把 IdP 返回的屬性mail映射成 .NET 里的 Email ClaimemployeeNumber映射成用戶標(biāo)識。屬性映射是接入時最繁瑣的工作因為你必須向 IdP 方要一份“返回屬性清單”根本沒有自動發(fā)現(xiàn)機制。另外還要注意屬性是有大小寫的Mail和mail是兩個完全不同的屬性名映射時嚴(yán)格按 IdP 文檔抄不要自作主張規(guī)范化。5.2 現(xiàn)象跳轉(zhuǎn)到 IdP 后提示“請求無效”用戶在瀏覽器里點擊登錄SP 把他重定向到 IdP結(jié)果 IdP 頁面報出“請求無效”或“invalid request”。這類問題通常不是簽名問題而是 AuthnRequest 本身不被 IdP 接受。最常見的原因是 SP 沒有提供 IdP 要求的簽名或者簽名算法不被支持。IdP 側(cè)如果設(shè)置了必須驗簽才處理請求而 SP 端沒有為 AuthnRequest 配置簽名證書請求就會被丟棄。解決方法是回到第 4 章的證書配置確認SPOptions.SigningCertificate正確加載。另一個隱蔽原因AuthnRequest 里帶了Destination屬性它必須和 IdP 實際接收請求的端點 URL 精確一致。如果 IdP 的登錄端點有兩個——一個用于重定向綁定一個用于 POST 綁定——而你的配置寫錯了綁定方式同樣會觸發(fā)這個錯誤。處理邏輯很直白從 IdP 的 metadata 里找到正確的 SingleSignOnService 地址和綁定方式逐項對照。我在聯(lián)調(diào)時會把中間件實際發(fā)出的 AuthnRequest 完整記錄成日志一條一條檢查頭信息十次里有八次問題都是出在這種細節(jié)上。5.3 現(xiàn)象IdP 側(cè)的一切正常但 SP 端一直 401登錄鏈路都走完了IdP 那邊顯示認證成功SP 端收到的卻是 401。檢查 SAML2 日志的時候發(fā)現(xiàn)請求沒有到達斷言處理邏輯直接被 ASP.NET 的認證中間件攔截了。這問題通常不是 SAML2 配置的問題而是你的“匿名訪問”和“需認證資源”沒分清楚。默認情況下ASP.NET 中間件會對所有未認證請求返回 401。解決辦法是檢查那些允許匿名訪問的端點是否帶了[AllowAnonymous]特性同時確認UseSaml2中間件的執(zhí)行順序在UseAuthorization之前。還有一個容易搞混的點SAML2 中間件解析斷言成功后是調(diào)用CreateSession來建立本地認證 Cookie 的。如果你繼承默認配置會話自動建立沒問題但如果你重寫了某個環(huán)節(jié)比如自己在控制器里手動處理 SAMLResponse卻漏掉了CreateSession這一步那么即便驗簽全過請求終態(tài)仍然是沒有認證身份的狀態(tài)。5.4 現(xiàn)象所有配置都對但簽名驗證就是失敗這類問題最考驗?zāi)托囊驗槟愕拇a、配置、乃至 IdP 提供的證書都“看起來沒問題”。簽名驗證失敗的常見原因有三個。第一個是 IdP metadata 里的證書過期了IdP 本身已經(jīng)輪換到新證書但 metadata 沒更新你在代碼里加載的仍是舊證書。第二個是簽名算法匹配問題IdP 用 SHA1 簽名代碼配置卻只認 SHA256兩個在數(shù)學(xué)上完全不同的摘要方法當(dāng)然對不上。第三個是 XML 規(guī)范化問題——SAML2 簽名標(biāo)準(zhǔn)里規(guī)定了 XML 在簽名前要先做 C14N 規(guī)范化不同的 XML 庫對空白字符的處理有細微差異極端情況下同一份斷言在不同框架里算出的摘要會不一致。前面兩種原因好解決分別對應(yīng)證書輪換和算法對齊。第三種原因讓人頭疼一旦遇到我會先用 XML 工具把收到的原始斷言和簽名值完整導(dǎo)出然后對比文檔里的標(biāo)準(zhǔn)簽名流程逐步核查是哪個環(huán)節(jié)的變換出了問題。實際項目中這類問題如果跟框架的 XML 解析器有關(guān)換一種解析庫往往比研究協(xié)議理論更快。5.5 現(xiàn)象本地正常部署到服務(wù)器就失敗開發(fā)環(huán)境一切正常一上測試服務(wù)器就報錯。這種場景最常見的原因是證書路徑和權(quán)限。你在開發(fā)環(huán)境加載證書用的是相對路徑.crt文件部署后工作目錄變了證書找不到或者運行進程的用戶沒有讀取證書文件的權(quán)限導(dǎo)致加載失敗。定位這樣的問題第一件事是看進程啟動日志證書加載異常會在應(yīng)用啟動時直接拋異常。另一個部署相關(guān)的大坑是 HTTPS。SAML2 要求 ACS 地址必須通過 HTTPS 訪問否則斷言在傳輸過程中可能被篡改。局域網(wǎng)測試環(huán)境經(jīng)常有人用 HTTP本地能跑通是因為 SP 和 IdP 互相之間沒有做傳輸層安全強制但真實場景中 IdP 會很誠實地拒絕非 HTTPS 的斷言消費地址。部署時先確認反向代理層的 TLS 配置正確并確保ForwardedHeaders中間件把X-Forwarded-Proto正確傳遞到應(yīng)用層不然即使 HTTPS 實際是通的應(yīng)用里看到的請求協(xié)議仍是 HTTP各種校驗依然會拒絕你。6. 把它做成能交付的東西給 ACS 端點加日志、多租戶支持與 SLO6.1 為 ACS 端點做結(jié)構(gòu)化日志接入排錯時最怕黑匣子用戶說登錄不了但你沒留下任何可分析的信息。SAML2 的排錯數(shù)據(jù)全藏在斷言和協(xié)議消息里所以我的習(xí)慣是在 ACS 端點里增加結(jié)構(gòu)化日志把 EntityID、NameID、斷言 ID、受眾、簽名算法、驗證結(jié)果全部記錄下來。日志字段設(shè)計上至少要有請求全局 ID、SP EntityID、IdP 的 SSO 地址、返回的 RelayState 以及唯一的 trace 標(biāo)識。這套日志在線上追查“某用戶登錄失敗”時能夠把一次完整登錄鏈路從入口到退出拉平看不需要再靠猜。6.2 用配置文件驅(qū)動多租戶支持如果你做的不是單個系統(tǒng)的接入而是要給多個客戶或內(nèi)部多個部門提供服務(wù)那每個租戶對應(yīng)一套 IdP 配置。改造的核心是把IdentityProviders列表改成從配置源加載租戶通過子域名或 URL 前綴區(qū)分中間件根據(jù)當(dāng)前請求的 Host 決定用哪一套證書去驗簽。這里有個細節(jié)多租戶模式下EntityID 也要按租戶區(qū)分不然所有租戶共享同一個 SP 身份IdP 端會混淆。實現(xiàn)了這一點之后新增一個租戶就不需要重新部署代碼只需要往數(shù)據(jù)庫里插入一條配置記錄。6.3 實現(xiàn)由 SP 主動退出到 IdP 的 SLO單點登錄做好了退出登錄也要做好。SAML2 單點退出SLO的實現(xiàn)方式是 SP 主動向 IdP 的SingleLogoutService端點發(fā)送 LogoutRequestIdP 清除全局會話后通知其他所有接入系統(tǒng)。我踩過最深的坑是在Logout控制器里忘了清除本地會話結(jié)果是用戶點了退出IdP 那邊全退干凈了回到本地頁面卻發(fā)現(xiàn)還能訪問受保護資源。正確做法是先從 IdP 注銷再調(diào)HttpContext.SignOutAsync清掉本地 Cookie順序反了會出現(xiàn)本地會話已清但 IdP 端還留著會話的情況。線上項目里我還養(yǎng)成一個習(xí)慣無論多簡單的接入都先確認 IdP 端的持久化會話策略。有些 IdP 默認空閑會話二十分鐘就失效SP 端卻希望保持一個星期這個時間差會導(dǎo)致用戶以為登錄狀態(tài)還在實際上跳轉(zhuǎn)過去又被要求重新輸密碼。能讓雙方策略盡量對齊就盡量對齊對不齊時把 SP 本地 Cookie 過期時間設(shè)置得比 IdP 短一些雖然犧牲了一點體驗但至少用戶知道什么時候該重新認證。SAML2 接入這件事做一次覺得全是細節(jié)做三次就會發(fā)現(xiàn)套路清楚得很。每次排錯我都堅持一個笨辦法把原始請求報文、簽名值、證書指紋全部導(dǎo)出存檔對著協(xié)議標(biāo)準(zhǔn)逐項排查不靠猜測。希望你也能從這個方向入手少走一些我走過的彎路。希望幫到你。本文還有配套的精品資源點擊獲取