戰(zhàn)：基于 RFC 9068 短時(shí) JWT 的 API 認(rèn)證接入指南)
Forem 委派 API 訪問實(shí)戰(zhàn)基于 RFC 9068 短時(shí) JWT 的 API 認(rèn)證接入指南【免費(fèi)下載鏈接】foremFor empowering community 項(xiàng)目地址: https://gitcode.com/gh_mirrors/fo/forem本文圍繞 Forem 倉庫的官方文檔 docs/delegated_access.md 展開系統(tǒng)講解如何讓 Forem 的 V1 API 接受來自單一可信委派服務(wù)的短時(shí) RFC 9068 訪問令牌access-token JWT作為 API Key 之外的另一條認(rèn)證通道。讀者將掌握完整的部署配置項(xiàng)、令牌與 JWKS 契約、緩存與密鑰輪換機(jī)制以及結(jié)合 app/services/delegated_access/ 源碼的底層驗(yàn)證原理可直接據(jù)此在自建 Forem 實(shí)例上安全接入委派認(rèn)證。什么是委派 API 訪問Forem 的 API 默認(rèn)通過api-key請(qǐng)求頭進(jìn)行認(rèn)證見 app/controllers/api/v1/api_controller.rb 中的authenticate_with_api_key。委派訪問Delegated Access提供了一條互補(bǔ)路徑Forem 可以接受一個(gè)受信任委派服務(wù)簽發(fā)的、短生命周期的 RFC 9068 access-token JWT。需要特別明確兩個(gè)邊界它只是認(rèn)證方式的補(bǔ)充不改變賬戶關(guān)聯(lián)account linking也不影響瀏覽器登錄browser sign-in授權(quán)決策仍由委派服務(wù)自身負(fù)責(zé)Forem不會(huì)把控制器動(dòng)作映射到scope也不會(huì)重新解釋哪些 OAuth 客戶端可以使用某個(gè)授權(quán)。委派服務(wù)必須在授權(quán)范圍內(nèi)才簽發(fā)令牌。從源碼結(jié)構(gòu)看委派訪問由三部分組成組件文件職責(zé)配置解析app/services/delegated_access/configuration.rb讀取并校驗(yàn)環(huán)境變量構(gòu)造 Verifier令牌/JWKS 校驗(yàn)app/services/delegated_access/verifier.rb解析 token、加載并緩存 JWKS、校驗(yàn)簽名與聲明JWKS 拉取app/services/delegated_access/jwks_client.rb從配置的 HTTPS 端點(diǎn)獲取 JWKS 文檔接入點(diǎn)位于 app/controllers/api/v1/api_controller.rb 的authenticate_with_delegated_access錯(cuò)誤類型定義在 app/services/delegated_access/errors.rb。部署配置必填項(xiàng)開啟委派訪問在啟用前必須一次性設(shè)置以下全部環(huán)境變量否則 configuration.rb 的required校驗(yàn)會(huì)直接拋出ArgumentErrorDELEGATED_ACCESS_ENABLEDtrue DELEGATED_ACCESS_ISSUERhttps://api.example.com DELEGATED_ACCESS_AUDIENCEhttps://community.example.com DELEGATED_ACCESS_IDENTITY_PROVIDERexternal-provider DELEGATED_ACCESS_OWNER_CLAIMhttps://api.example.com/claims/dev_user_id DELEGATED_ACCESS_JWKS_URIhttps://api.example.com/.well-known/jwks.json各配置項(xiàng)的語義與源碼級(jí)約束DELEGATED_ACCESS_ENABLED取值必須是字面量true或false否則啟動(dòng)即報(bào)錯(cuò)。只有在true時(shí)API 才會(huì)解釋Authorization: Bearer ...頭DELEGATED_ACCESS_ISSUER / AUDIENCE令牌iss/aud聲明的精確匹配值屬于部署級(jí)的信任設(shè)置DELEGATED_ACCESS_IDENTITY_PROVIDER用于在Identity表中按provider字段定位用戶見下文認(rèn)證流程DELEGATED_ACCESS_OWNER_CLAIM指定哪個(gè) claim 攜帶 Forem 用戶 IDDELEGATED_ACCESS_JWKS_URIJWKS 端點(diǎn)地址path_required: true要求帶非根路徑。文檔強(qiáng)調(diào)issuer、audience、identity provider、owner claim、JWKS URI 都是精確的部署信任設(shè)置JWKS URI 與 issuer必須是 HTTPS且絕不會(huì)從令牌聲明或請(qǐng)求頭中選取。Forem 不要求復(fù)制公鑰 PEM、不校驗(yàn)活躍的kid是否預(yù)注冊(cè)也不需要 OAuth client ID。源碼中還隱含了更細(xì)的校驗(yàn)規(guī)則configuration.rbHTTPS 校驗(yàn)要求uri.is_a?(URI::HTTPS)、host 非空、無 userinfo、無 query、無 fragmentDELEGATED_ACCESS_OWNER_CLAIM必須是帶路徑的 HTTPS URI且不能是 RFC 9068 注冊(cè)聲明iss sub aud exp nbf iat jti client_id scope nonce sid以防止與標(biāo)準(zhǔn)聲明沖突must be collision-resistant?？蛇x項(xiàng)安全上界保守默認(rèn)值DELEGATED_ACCESS_JWKS_MAX_AGE_SECONDS300 DELEGATED_ACCESS_MAX_TOKEN_LIFETIME_SECONDS60DELEGATED_ACCESS_JWKS_MAX_AGE_SECONDS每個(gè) Puma worker進(jìn)程內(nèi)JWKS 密鑰緩存的生存期默認(rèn) 300 秒。緩存過期后每個(gè)進(jìn)程只有第一個(gè)請(qǐng)求負(fù)責(zé)刷新并發(fā)請(qǐng)求會(huì)在寬限期內(nèi)繼續(xù)使用剛過期的條目超出寬限期后如果拉取失敗則絕不再使用過期條目DELEGATED_ACCESS_MAX_TOKEN_LIFETIME_SECONDS令牌允許的最大生命周期exp - iat默認(rèn) 60 秒強(qiáng)制令牌短時(shí)有效。這兩個(gè)變量在 configuration.rb 中通過positive_integer解析必須是正整數(shù)否則拋DELEGATED_ACCESS_JWKS_MAX_AGE_SECONDS must be a positive integer類錯(cuò)誤隨后被傳入Verifier的jwks_cache_lifetime與maximum_token_lifetime。初始化機(jī)制委派訪問配置通過 config/initializers/delegated_access.rb 掛載在to_prepare回調(diào)中執(zhí)行DelegatedAccess::Configuration.from_env.freeze存放到Rails.application.config.x.delegated_access。該配置對(duì)象是凍結(jié)的開發(fā)環(huán)境下代碼重載時(shí)會(huì)重新構(gòu)建。之所以放在to_prepare里是為了讓 Zeitwerk 正常解析自動(dòng)加載的DelegatedAccess常量而不是手寫 require。未啟用時(shí)的行為只要DELEGATED_ACCESS_ENABLED不是trueAPI 就會(huì)完全忽略Authorization頭行為與引入此功能之前完全一致——即使客戶端同時(shí)攜帶api-key與Authorization也不會(huì)受影響。令牌與密鑰契約該契約遵循 RFC 9068尤其是其中面向資源服務(wù)器的檢查顯式的 access-token 類型、issuer、audience、簽名與過期時(shí)間。Forem 在此基礎(chǔ)上進(jìn)一步收窄了允許的形式簽名算法僅限RS256typ必須是atjwt頭部必須攜帶非空kid必須包含受限的sub、exp、iat、nbf、jti以及配置的 owner claim會(huì)話用途聲明sid與nonce會(huì)被拒絕完整的 RFC 9068 聲明集含client_id、scope由委派服務(wù)負(fù)責(zé)簽發(fā)但Forem 不使用這兩個(gè)聲明做授權(quán)。在實(shí)現(xiàn)上verifier.rb 的verify流程分兩段不校驗(yàn)簽名的解碼先做令牌與頭部的形式校驗(yàn)validate_token!、validate_header!確認(rèn)header.keys.sort HEADER_MEMBERS即恰好是alg、kid、typ三個(gè)成員且alg RS256、typ atjwt、kid是長度不超過 128 字節(jié)的非空字符串嚴(yán)格校驗(yàn)簽名解碼通過JWT.decode(..., algorithms: [RS256], jwks: method(:load_jwks), iss:, aud:, required_claims: ..., verify_expiration/not_before/iat: true, leeway: 5)完成簽名驗(yàn)證、issuer/audience 精確匹配、時(shí)間聲明校驗(yàn)leeway為 5 秒時(shí)鐘偏差CLOCK_SKEW_SECONDS。聲明的二次校驗(yàn)validate_claims見 verifier.rb包括aud必須與配置精確相等存在nonce或sid即拒絕sub、jti必須是長度受限的非空字符串默認(rèn)上限 256 字節(jié)iat、nbf、exp必須是整數(shù)且exp - iat為正且不超過maximum_token_lifetimenbf不得晚于expowner claim 必須是\A[1-9]\d{0,18}\z格式的正整數(shù)字符串且不超過有符號(hào) 64 位整數(shù)上限9_223_372_036_854_775_807解析后作為Claims.owner_id。JWKS 端點(diǎn)要求配置的 JWKS 端點(diǎn)必須返回頂層含keys數(shù)組的 JSON且滿足至少一個(gè)唯一的 RSA 公鑰簽名密鑰標(biāo)記use: sig、alg: RS256模長≥ 2048 位其他公鑰會(huì)被忽略任何私鑰 RSA 參數(shù)d p q dp dq qi oth都會(huì)使整個(gè)響應(yīng)失效。對(duì)應(yīng)源碼在 verifier.rbvalidated_signing_keys依次校驗(yàn)keys存在、數(shù)量不超過MAX_KEYS 32、每個(gè)成員是對(duì)象、不含私鑰參數(shù)、kid不重復(fù)eligible_key?進(jìn)一步要求 RSA 公鑰、模長 ≥ 2048 且指數(shù)e為不小于 3 的奇數(shù)。拉取端 jwks_client.rb 也有硬性約束連接與讀取超時(shí)各 2 秒、響應(yīng)體上限 64 KB、要求 HTTP 200 且content-type為application/json或application/jwk-setjson并以application/jwk-setjson, application/json作為 Accept 頭。認(rèn)證流程從 Bearer 頭到當(dāng)前用戶當(dāng)委派訪問啟用且請(qǐng)求攜帶Authorization: Bearer token時(shí)api_controller.rb 的authenticate_with_delegated_access執(zhí)行以下鏈路讀取Rails.application.config.x.delegated_access若未啟用則直接返回delegated_bearer_token解析Authorization頭必須匹配Bearerscheme令牌非空且不含逗號(hào)否則拋InvalidTokenconfig.verifier.verify(token)完成全部令牌與簽名校驗(yàn)返回Claims(subject:, owner_id:)用Identity.includes(:user).where(provider: config.identity_provider, uid: claims.subject, user_id: claims.owner_id).sole在provideruid委派服務(wù)的 subjectuser_idowner claim 解析出的用戶 ID三個(gè)維度上精確定位用戶若用戶被標(biāo)記為 spam / suspended 或未注冊(cè)同樣拋InvalidToken校驗(yàn)通過后設(shè)置user authenticated_user user后續(xù) Pundit 授權(quán)與普通登錄用戶一致。在authenticate_with_api_keyapi_controller.rb中委派認(rèn)證優(yōu)先級(jí)高于 API Key先嘗試委派令牌失敗/缺失再回退到api-key請(qǐng)求頭。注意這個(gè)回退只在沒有有效委派令牌時(shí)發(fā)生一旦請(qǐng)求出示了 Bearer 令牌錯(cuò)誤處理就是嚴(yán)格的見下節(jié)。失敗、緩存與密鑰輪換錯(cuò)誤語義401 Unauthorized畸形令牌、聲明或簽名無效、未知kid。對(duì)應(yīng)rescue_from DelegatedAccess::Errors::InvalidTokenapi_controller.rb返回{error:unauthorized,status:401}503 Service Unavailable僅當(dāng)沒有可用緩存條目且信任端點(diǎn)不可用或返回?zé)o效內(nèi)容時(shí)觸發(fā)rescue_from DelegatedAccess::Errors::Unavailableapi_controller.rb返回{error:delegated access unavailable,status:503}。文檔明確在啟用委派訪問期間這兩種情況都不會(huì)從已出示的 Bearer 令牌回退到 API Key 認(rèn)證。緩存與防放大緩存邏輯在 verifier.rb 的load_jwks使用cache.fetchexpires_in: jwks_cache_lifetime并設(shè)置了race_condition_ttl: JWKS_REFRESH_GRACE_SECONDS10 秒實(shí)現(xiàn)每進(jìn)程單請(qǐng)求刷新、其余請(qǐng)求繼續(xù)用剛過期條目的節(jié)流策略。遙測(cè)通過ForemStatsClient.increment(delegated_access.verification, tags: [outcome:...]記錄refresh、cache_hit、accepted、rejected、unavailable_jwks等結(jié)果。防放大機(jī)制未知kid不會(huì)使緩存失效也不會(huì)觸發(fā)對(duì) issuer 的請(qǐng)求從而防止攻擊者用隨機(jī) ID 刷爆 JWKS 端點(diǎn)流量。密鑰輪換與應(yīng)急失效文檔給出的輪換步驟先同時(shí)發(fā)布舊密鑰與繼任密鑰等待至少一個(gè)配置的緩存生命周期DELEGATED_ACCESS_JWKS_MAX_AGE_SECONDS之后才開始用繼任密鑰簽名。若懷疑密鑰泄露操作員可在Rails console中立即使進(jìn)程內(nèi)密鑰緩存失效Rails.application.config.x.delegated_access.invalidate_cache!該命令映射到 configuration.rb 的invalidate_cache!最終調(diào)用 verifier.rb 刪除緩存鍵:delegated_access_jwks。注意必須在每個(gè) Forem 應(yīng)用進(jìn)程中分別執(zhí)行或直接重啟全部應(yīng)用進(jìn)程執(zhí)行前應(yīng)先把被泄露的公鑰從 issuer 的 JWKS 中移除緩存只包含經(jīng)過校驗(yàn)的公鑰材料且不是持久化的重啟即清空。安全邊界小結(jié)綜合文檔與源碼可以歸納出以下硬性邊界對(duì)應(yīng)常量定義在 verifier.rb約束值來源令牌最大字節(jié)數(shù)16,38416 KBMAX_TOKEN_BYTESJWKS 最大密鑰數(shù)32MAX_KEYSkid最大字節(jié)數(shù)128MAX_KID_BYTES字符串聲明最大字節(jié)數(shù)256MAX_STRING_CLAIM_BYTES時(shí)鐘偏差5 秒CLOCK_SKEW_SECONDS刷新寬限期10 秒JWKS_REFRESH_GRACE_SECONDSRSA 模長下限2048 位eligible_key?緩存生命周期 / 令牌最大壽命300s / 60s默認(rèn)Configuration默認(rèn)值這些數(shù)值共同保證令牌短命、輸入有界、JWKS 文檔小且只含公鑰、簽名強(qiáng)度有下限從輸入面到信任面都做了收斂。委派服務(wù)需要為每個(gè)授權(quán)請(qǐng)求簽發(fā)完整且正確的 RFC 9068 聲明集并自行承擔(dān)授權(quán)判斷——Forem 只做認(rèn)證與用戶映射。測(cè)試與驗(yàn)證倉庫在 spec/services/delegated_access/ 下提供了三個(gè)核心測(cè)試文件可作為接入時(shí)的參考基線verifier_spec.rb覆蓋令牌頭部校驗(yàn)、聲明校驗(yàn)、生命周期校驗(yàn)、JWKS 解析與緩存刷新、未知kid行為等configuration_spec.rb覆蓋環(huán)境變量必填、HTTPS 校驗(yàn)、owner claim 沖突檢查、正整數(shù)邊界jwks_client_spec.rb覆蓋 HTTP 狀態(tài)、Content-Type、響應(yīng)體大小上限與超時(shí)處理。端到端層面authenticate_with_delegated_access的 401/503 映射可見于 app/controllers/api/v1/api_controller.rb相關(guān)請(qǐng)求級(jí)行為可在 spec/requests/api/v1/users_spec.rb 等 API 測(cè)試中進(jìn)一步驗(yàn)證。簡言之委派訪問為 Forem 提供了一條短時(shí)、精確、可輪換、可應(yīng)急失效的機(jī)器對(duì)機(jī)器認(rèn)證通道只要委派服務(wù)嚴(yán)格按本文契約簽發(fā)令牌、正確配置 JWKS 并遵循輪換節(jié)奏即可安全地讓受信任服務(wù)以指定用戶身份調(diào)用 Forem API而不必分發(fā)長期有效的 API Key。【免費(fèi)下載鏈接】foremFor empowering community 項(xiàng)目地址: https://gitcode.com/gh_mirrors/fo/forem創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考 Forem 委派 API 訪問實(shí)戰(zhàn)：基于 RFC 9068 短時(shí) JWT 的 API 認(rèn)證接入指南
Forem 委派 API 訪問實(shí)戰(zhàn)基于 RFC 9068 短時(shí) JWT 的 API 認(rèn)證接入指南【免費(fèi)下載鏈接】foremFor empowering community 項(xiàng)目地址: https://gitcode.com/gh_mirrors/fo/forem本文圍繞 Forem 倉庫的官方文檔 docs/delegated_access.md 展開系統(tǒng)講解如何讓 Forem 的 V1 API 接受來自單一可信委派服務(wù)的短時(shí) RFC 9068 訪問令牌access-token JWT作為 API Key 之外的另一條認(rèn)證通道。讀者將掌握完整的部署配置項(xiàng)、令牌與 JWKS 契約、緩存與密鑰輪換機(jī)制以及結(jié)合 app/services/delegated_access/ 源碼的底層驗(yàn)證原理可直接據(jù)此在自建 Forem 實(shí)例上安全接入委派認(rèn)證。什么是委派 API 訪問Forem 的 API 默認(rèn)通過api-key請(qǐng)求頭進(jìn)行認(rèn)證見 app/controllers/api/v1/api_controller.rb 中的authenticate_with_api_key。委派訪問Delegated Access提供了一條互補(bǔ)路徑Forem 可以接受一個(gè)受信任委派服務(wù)簽發(fā)的、短生命周期的 RFC 9068 access-token JWT。需要特別明確兩個(gè)邊界它只是認(rèn)證方式的補(bǔ)充不改變賬戶關(guān)聯(lián)account linking也不影響瀏覽器登錄browser sign-in授權(quán)決策仍由委派服務(wù)自身負(fù)責(zé)Forem不會(huì)把控制器動(dòng)作映射到scope也不會(huì)重新解釋哪些 OAuth 客戶端可以使用某個(gè)授權(quán)。委派服務(wù)必須在授權(quán)范圍內(nèi)才簽發(fā)令牌。從源碼結(jié)構(gòu)看委派訪問由三部分組成組件文件職責(zé)配置解析app/services/delegated_access/configuration.rb讀取并校驗(yàn)環(huán)境變量構(gòu)造 Verifier令牌/JWKS 校驗(yàn)app/services/delegated_access/verifier.rb解析 token、加載并緩存 JWKS、校驗(yàn)簽名與聲明JWKS 拉取app/services/delegated_access/jwks_client.rb從配置的 HTTPS 端點(diǎn)獲取 JWKS 文檔接入點(diǎn)位于 app/controllers/api/v1/api_controller.rb 的authenticate_with_delegated_access錯(cuò)誤類型定義在 app/services/delegated_access/errors.rb。部署配置必填項(xiàng)開啟委派訪問在啟用前必須一次性設(shè)置以下全部環(huán)境變量否則 configuration.rb 的required校驗(yàn)會(huì)直接拋出ArgumentErrorDELEGATED_ACCESS_ENABLEDtrue DELEGATED_ACCESS_ISSUERhttps://api.example.com DELEGATED_ACCESS_AUDIENCEhttps://community.example.com DELEGATED_ACCESS_IDENTITY_PROVIDERexternal-provider DELEGATED_ACCESS_OWNER_CLAIMhttps://api.example.com/claims/dev_user_id DELEGATED_ACCESS_JWKS_URIhttps://api.example.com/.well-known/jwks.json各配置項(xiàng)的語義與源碼級(jí)約束DELEGATED_ACCESS_ENABLED取值必須是字面量true或false否則啟動(dòng)即報(bào)錯(cuò)。只有在true時(shí)API 才會(huì)解釋Authorization: Bearer ...頭DELEGATED_ACCESS_ISSUER / AUDIENCE令牌iss/aud聲明的精確匹配值屬于部署級(jí)的信任設(shè)置DELEGATED_ACCESS_IDENTITY_PROVIDER用于在Identity表中按provider字段定位用戶見下文認(rèn)證流程DELEGATED_ACCESS_OWNER_CLAIM指定哪個(gè) claim 攜帶 Forem 用戶 IDDELEGATED_ACCESS_JWKS_URIJWKS 端點(diǎn)地址path_required: true要求帶非根路徑。文檔強(qiáng)調(diào)issuer、audience、identity provider、owner claim、JWKS URI 都是精確的部署信任設(shè)置JWKS URI 與 issuer必須是 HTTPS且絕不會(huì)從令牌聲明或請(qǐng)求頭中選取。Forem 不要求復(fù)制公鑰 PEM、不校驗(yàn)活躍的kid是否預(yù)注冊(cè)也不需要 OAuth client ID。源碼中還隱含了更細(xì)的校驗(yàn)規(guī)則configuration.rbHTTPS 校驗(yàn)要求uri.is_a?(URI::HTTPS)、host 非空、無 userinfo、無 query、無 fragmentDELEGATED_ACCESS_OWNER_CLAIM必須是帶路徑的 HTTPS URI且不能是 RFC 9068 注冊(cè)聲明iss sub aud exp nbf iat jti client_id scope nonce sid以防止與標(biāo)準(zhǔn)聲明沖突must be collision-resistant?？蛇x項(xiàng)安全上界保守默認(rèn)值DELEGATED_ACCESS_JWKS_MAX_AGE_SECONDS300 DELEGATED_ACCESS_MAX_TOKEN_LIFETIME_SECONDS60DELEGATED_ACCESS_JWKS_MAX_AGE_SECONDS每個(gè) Puma worker進(jìn)程內(nèi)JWKS 密鑰緩存的生存期默認(rèn) 300 秒。緩存過期后每個(gè)進(jìn)程只有第一個(gè)請(qǐng)求負(fù)責(zé)刷新并發(fā)請(qǐng)求會(huì)在寬限期內(nèi)繼續(xù)使用剛過期的條目超出寬限期后如果拉取失敗則絕不再使用過期條目DELEGATED_ACCESS_MAX_TOKEN_LIFETIME_SECONDS令牌允許的最大生命周期exp - iat默認(rèn) 60 秒強(qiáng)制令牌短時(shí)有效。這兩個(gè)變量在 configuration.rb 中通過positive_integer解析必須是正整數(shù)否則拋DELEGATED_ACCESS_JWKS_MAX_AGE_SECONDS must be a positive integer類錯(cuò)誤隨后被傳入Verifier的jwks_cache_lifetime與maximum_token_lifetime。初始化機(jī)制委派訪問配置通過 config/initializers/delegated_access.rb 掛載在to_prepare回調(diào)中執(zhí)行DelegatedAccess::Configuration.from_env.freeze存放到Rails.application.config.x.delegated_access。該配置對(duì)象是凍結(jié)的開發(fā)環(huán)境下代碼重載時(shí)會(huì)重新構(gòu)建。之所以放在to_prepare里是為了讓 Zeitwerk 正常解析自動(dòng)加載的DelegatedAccess常量而不是手寫 require。未啟用時(shí)的行為只要DELEGATED_ACCESS_ENABLED不是trueAPI 就會(huì)完全忽略Authorization頭行為與引入此功能之前完全一致——即使客戶端同時(shí)攜帶api-key與Authorization也不會(huì)受影響。令牌與密鑰契約該契約遵循 RFC 9068尤其是其中面向資源服務(wù)器的檢查顯式的 access-token 類型、issuer、audience、簽名與過期時(shí)間。Forem 在此基礎(chǔ)上進(jìn)一步收窄了允許的形式簽名算法僅限RS256typ必須是atjwt頭部必須攜帶非空kid必須包含受限的sub、exp、iat、nbf、jti以及配置的 owner claim會(huì)話用途聲明sid與nonce會(huì)被拒絕完整的 RFC 9068 聲明集含client_id、scope由委派服務(wù)負(fù)責(zé)簽發(fā)但Forem 不使用這兩個(gè)聲明做授權(quán)。在實(shí)現(xiàn)上verifier.rb 的verify流程分兩段不校驗(yàn)簽名的解碼先做令牌與頭部的形式校驗(yàn)validate_token!、validate_header!確認(rèn)header.keys.sort HEADER_MEMBERS即恰好是alg、kid、typ三個(gè)成員且alg RS256、typ atjwt、kid是長度不超過 128 字節(jié)的非空字符串嚴(yán)格校驗(yàn)簽名解碼通過JWT.decode(..., algorithms: [RS256], jwks: method(:load_jwks), iss:, aud:, required_claims: ..., verify_expiration/not_before/iat: true, leeway: 5)完成簽名驗(yàn)證、issuer/audience 精確匹配、時(shí)間聲明校驗(yàn)leeway為 5 秒時(shí)鐘偏差CLOCK_SKEW_SECONDS。聲明的二次校驗(yàn)validate_claims見 verifier.rb包括aud必須與配置精確相等存在nonce或sid即拒絕sub、jti必須是長度受限的非空字符串默認(rèn)上限 256 字節(jié)iat、nbf、exp必須是整數(shù)且exp - iat為正且不超過maximum_token_lifetimenbf不得晚于expowner claim 必須是\A[1-9]\d{0,18}\z格式的正整數(shù)字符串且不超過有符號(hào) 64 位整數(shù)上限9_223_372_036_854_775_807解析后作為Claims.owner_id。JWKS 端點(diǎn)要求配置的 JWKS 端點(diǎn)必須返回頂層含keys數(shù)組的 JSON且滿足至少一個(gè)唯一的 RSA 公鑰簽名密鑰標(biāo)記use: sig、alg: RS256模長≥ 2048 位其他公鑰會(huì)被忽略任何私鑰 RSA 參數(shù)d p q dp dq qi oth都會(huì)使整個(gè)響應(yīng)失效。對(duì)應(yīng)源碼在 verifier.rbvalidated_signing_keys依次校驗(yàn)keys存在、數(shù)量不超過MAX_KEYS 32、每個(gè)成員是對(duì)象、不含私鑰參數(shù)、kid不重復(fù)eligible_key?進(jìn)一步要求 RSA 公鑰、模長 ≥ 2048 且指數(shù)e為不小于 3 的奇數(shù)。拉取端 jwks_client.rb 也有硬性約束連接與讀取超時(shí)各 2 秒、響應(yīng)體上限 64 KB、要求 HTTP 200 且content-type為application/json或application/jwk-setjson并以application/jwk-setjson, application/json作為 Accept 頭。認(rèn)證流程從 Bearer 頭到當(dāng)前用戶當(dāng)委派訪問啟用且請(qǐng)求攜帶Authorization: Bearer token時(shí)api_controller.rb 的authenticate_with_delegated_access執(zhí)行以下鏈路讀取Rails.application.config.x.delegated_access若未啟用則直接返回delegated_bearer_token解析Authorization頭必須匹配Bearerscheme令牌非空且不含逗號(hào)否則拋InvalidTokenconfig.verifier.verify(token)完成全部令牌與簽名校驗(yàn)返回Claims(subject:, owner_id:)用Identity.includes(:user).where(provider: config.identity_provider, uid: claims.subject, user_id: claims.owner_id).sole在provideruid委派服務(wù)的 subjectuser_idowner claim 解析出的用戶 ID三個(gè)維度上精確定位用戶若用戶被標(biāo)記為 spam / suspended 或未注冊(cè)同樣拋InvalidToken校驗(yàn)通過后設(shè)置user authenticated_user user后續(xù) Pundit 授權(quán)與普通登錄用戶一致。在authenticate_with_api_keyapi_controller.rb中委派認(rèn)證優(yōu)先級(jí)高于 API Key先嘗試委派令牌失敗/缺失再回退到api-key請(qǐng)求頭。注意這個(gè)回退只在沒有有效委派令牌時(shí)發(fā)生一旦請(qǐng)求出示了 Bearer 令牌錯(cuò)誤處理就是嚴(yán)格的見下節(jié)。失敗、緩存與密鑰輪換錯(cuò)誤語義401 Unauthorized畸形令牌、聲明或簽名無效、未知kid。對(duì)應(yīng)rescue_from DelegatedAccess::Errors::InvalidTokenapi_controller.rb返回{error:unauthorized,status:401}503 Service Unavailable僅當(dāng)沒有可用緩存條目且信任端點(diǎn)不可用或返回?zé)o效內(nèi)容時(shí)觸發(fā)rescue_from DelegatedAccess::Errors::Unavailableapi_controller.rb返回{error:delegated access unavailable,status:503}。文檔明確在啟用委派訪問期間這兩種情況都不會(huì)從已出示的 Bearer 令牌回退到 API Key 認(rèn)證。緩存與防放大緩存邏輯在 verifier.rb 的load_jwks使用cache.fetchexpires_in: jwks_cache_lifetime并設(shè)置了race_condition_ttl: JWKS_REFRESH_GRACE_SECONDS10 秒實(shí)現(xiàn)每進(jìn)程單請(qǐng)求刷新、其余請(qǐng)求繼續(xù)用剛過期條目的節(jié)流策略。遙測(cè)通過ForemStatsClient.increment(delegated_access.verification, tags: [outcome:...]記錄refresh、cache_hit、accepted、rejected、unavailable_jwks等結(jié)果。防放大機(jī)制未知kid不會(huì)使緩存失效也不會(huì)觸發(fā)對(duì) issuer 的請(qǐng)求從而防止攻擊者用隨機(jī) ID 刷爆 JWKS 端點(diǎn)流量。密鑰輪換與應(yīng)急失效文檔給出的輪換步驟先同時(shí)發(fā)布舊密鑰與繼任密鑰等待至少一個(gè)配置的緩存生命周期DELEGATED_ACCESS_JWKS_MAX_AGE_SECONDS之后才開始用繼任密鑰簽名。若懷疑密鑰泄露操作員可在Rails console中立即使進(jìn)程內(nèi)密鑰緩存失效Rails.application.config.x.delegated_access.invalidate_cache!該命令映射到 configuration.rb 的invalidate_cache!最終調(diào)用 verifier.rb 刪除緩存鍵:delegated_access_jwks。注意必須在每個(gè) Forem 應(yīng)用進(jìn)程中分別執(zhí)行或直接重啟全部應(yīng)用進(jìn)程執(zhí)行前應(yīng)先把被泄露的公鑰從 issuer 的 JWKS 中移除緩存只包含經(jīng)過校驗(yàn)的公鑰材料且不是持久化的重啟即清空。安全邊界小結(jié)綜合文檔與源碼可以歸納出以下硬性邊界對(duì)應(yīng)常量定義在 verifier.rb約束值來源令牌最大字節(jié)數(shù)16,38416 KBMAX_TOKEN_BYTESJWKS 最大密鑰數(shù)32MAX_KEYSkid最大字節(jié)數(shù)128MAX_KID_BYTES字符串聲明最大字節(jié)數(shù)256MAX_STRING_CLAIM_BYTES時(shí)鐘偏差5 秒CLOCK_SKEW_SECONDS刷新寬限期10 秒JWKS_REFRESH_GRACE_SECONDSRSA 模長下限2048 位eligible_key?緩存生命周期 / 令牌最大壽命300s / 60s默認(rèn)Configuration默認(rèn)值這些數(shù)值共同保證令牌短命、輸入有界、JWKS 文檔小且只含公鑰、簽名強(qiáng)度有下限從輸入面到信任面都做了收斂。委派服務(wù)需要為每個(gè)授權(quán)請(qǐng)求簽發(fā)完整且正確的 RFC 9068 聲明集并自行承擔(dān)授權(quán)判斷——Forem 只做認(rèn)證與用戶映射。測(cè)試與驗(yàn)證倉庫在 spec/services/delegated_access/ 下提供了三個(gè)核心測(cè)試文件可作為接入時(shí)的參考基線verifier_spec.rb覆蓋令牌頭部校驗(yàn)、聲明校驗(yàn)、生命周期校驗(yàn)、JWKS 解析與緩存刷新、未知kid行為等configuration_spec.rb覆蓋環(huán)境變量必填、HTTPS 校驗(yàn)、owner claim 沖突檢查、正整數(shù)邊界jwks_client_spec.rb覆蓋 HTTP 狀態(tài)、Content-Type、響應(yīng)體大小上限與超時(shí)處理。端到端層面authenticate_with_delegated_access的 401/503 映射可見于 app/controllers/api/v1/api_controller.rb相關(guān)請(qǐng)求級(jí)行為可在 spec/requests/api/v1/users_spec.rb 等 API 測(cè)試中進(jìn)一步驗(yàn)證。簡言之委派訪問為 Forem 提供了一條短時(shí)、精確、可輪換、可應(yīng)急失效的機(jī)器對(duì)機(jī)器認(rèn)證通道只要委派服務(wù)嚴(yán)格按本文契約簽發(fā)令牌、正確配置 JWKS 并遵循輪換節(jié)奏即可安全地讓受信任服務(wù)以指定用戶身份調(diào)用 Forem API而不必分發(fā)長期有效的 API Key。【免費(fèi)下載鏈接】foremFor empowering community 項(xiàng)目地址: https://gitcode.com/gh_mirrors/fo/forem創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考