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