Skip to main contentSkip to navigation
返回網誌
教學

JWT 整合教學:為你嘅應用程式加入令牌身份驗證

逐步教學:電郵/密碼應用程式入面 JWT 嘅完整生命週期——註冊、登入、令牌儲存、伺服器端驗證、雙重驗證同登出,仲有點用 jwt.io 除錯令牌。

更新於
6 分鐘閱讀

如果你搜尋 JWT 點樣用喺電郵同密碼認證入面,會發現大家一直都喺度問同一堆問題:將憑證放入令牌安唔安全?仲使唔使用 HTTPS?呢個令牌應該由邊個去讀?過咗期會點?答案其實好簡短,不過要真正搞清楚佢哋,已經係成件事嘅大部分工夫。

本教學會用 AuthFlow™ REST API,帶你行一次電郵/密碼應用入面 JSON Web Token 嘅完整生命週期,由首次註冊一直去到登出。令牌格式本身喺 RFC 7519 入面有定義,不過跟住做嘅話,你唔使讀佢。

JWT 係乜嘢,又唔係乜嘢

JWT 係認證嘅結果,而唔係認證嘅替代品。用戶用電郵同密碼證明一次自己係邊個,伺服器跟住會傳返一個已簽署嘅令牌,表示「呢個人已經通過認證」,之後每個請求都會帶住呢個令牌,而唔係密碼。正正因為咁,JWT 先會喺無狀態同分散式系統入面咁有用:任何持有正確密鑰嘅服務都可以驗證令牌,唔使再查一次資料庫。

JWT 由三部分組成:標頭(令牌類型同簽署演算法)、載有用戶聲明嘅載荷,以及簽署。簽署用嚟證明令牌冇被改動過,但係唔會隱藏任何嘢。載荷只係經過 base64 編碼,任何攞到令牌嘅人都睇得到。請將 JWT 當成「可以偵測篡改」而唔係「機密」嘅嘢。

千祈唔好將密碼放入令牌

初學者經常會問:可唔可以將用戶嘅憑證存入 JWT?一般嚟講,你唔需要咁做:令牌本身就係登入所產生嘅短期憑證。如果要識別用戶,就喺 sub 聲明入面放一個識別碼,後端有需要嘅話,再加上角色或者存取級別。密碼、機密同任何你唔想喺瀏覽器入面睇到嘅嘢,都唔好放入去。

HTTPS 係另一回事,所有通訊你都應該用。佢保護客戶端同伺服器之間嘅流量,而 JWT 簽署就保護令牌嘅完整性。兩者都唔可以取代對方。

第 1 步:將 API 金鑰留喺你嘅伺服器

每一次 AuthFlow 呼叫,都係代表你嘅機構、用擁有者控制台入面嘅 API 金鑰發出。呢條金鑰必須放喺你可以控制嘅基礎設施上,例如好似 AUTHFLOW_API_KEY 咁嘅伺服器端環境變數。絕對唔好將佢放入瀏覽器 JavaScript。最簡單又安全嘅設計,就係搭一個細細嘅後端(或者用我哋發佈嘅 ExpressJS 代理),前端同佢溝通,再由佢代為呼叫 /auth。

第 2 步:註冊同登入

喺註冊或者登入之前,你嘅後端要就用戶嘅電郵,向 /auth/fooBar 要求一個短期嘅防濫用令牌。佢會喺 45 秒後過期,所以請喺下一次呼叫之前即刻攞,而且唔好重用。跟住就用 foobar 值、你嘅 api_key、email、符合複雜度規則嘅 password(8 至 32 個字元,包含大寫字母、細寫字母、數字同特殊字元)、fullname,以及設為 true 嘅 disclaimed 去呼叫 /auth/signUp。註冊成功會即刻傳返會話令牌,而電郵同角色重複嘅話就會傳返 409。

登入嘅做法一樣,對住 /auth/login 做。成功嘅話你會收到會話令牌:一個用 RS512 簽署嘅 JWT。RS512 用密鑰對,所以令牌係由你永遠睇唔到嘅私密金鑰簽署,而且唔使分享任何機密都可以驗證。

第 3 步:小心保存令牌

後端攞到令牌之後,就要決定放喺邊度。建議使用 HTTP-only Cookie,因為頁面腳本讀唔到,可以減輕跨網站指令碼漏洞所造成嘅損害。無論你揀邊種方式,都要保存會話令牌而唔係臨時令牌,並且確保佢永遠唔會被寫入日誌。

第 4 步:喺每個受保護嘅路由驗證

喺後端處理受保護嘅請求之前,要先檢查令牌。用 sessionToken 同用戶嘅 email 呼叫 /auth/validate;有效嘅令牌會成功,無效或者已過期嘅就會傳返 401。需要當前用戶嘅個人檔案時,就用 /auth/me。每個受保護嘅請求都喺伺服器做呢一步好重要,因為一個你從不驗證嘅已簽署令牌,係保護唔到任何嘢嘅。

過期係設計嘅一部分。令牌過咗期,用戶就要重新登入,而唔係由你嘅應用靜靜雞幫佢延長。請確保你嘅應用可以妥善處理呢個 401,將用戶帶返去登入頁面。

第 5 步:處理雙重認證

如果用戶已啟用 2FA,/auth/login 唔會傳返會話令牌,而係傳返 requires2FA 同 tempToken。你嘅應用跟住要求提供第二重驗證,再透過其中一個 /auth/2fa 驗證端點(TOTP 驗證碼、後備碼或者電郵 OTP)去交換 tempToken。只有呢次交換先會產生真正嘅會話令牌,所以請確保你保存嘅係佢,而絕對唔係 tempToken。

用 jwt.io 除錯令牌

當有嘢唔對路,想最快睇到令牌入面究竟有啲乜,就係用 jwt.io。將令牌貼入佢嘅除錯器,佢就會解碼標頭同載荷,你就可以檢查演算法、sub 聲明同到期時間。通常咁樣已經足夠搵出已過期嘅令牌、錯咗嘅用戶,或者誤存咗嘅 tempToken。

根據以上所有內容,有一點要提醒:令牌就係憑證。請將生產環境入面有效嘅令牌當成敏感資料,除錯時盡量用測試帳戶,並且避免將真實令牌貼入任何你唔信任嘅工具。解碼令牌同驗證令牌唔係同一回事。驗證仍然要喺你嘅伺服器透過 /auth/validate 完成。

第 6 步:登出

要結束會話,就用 sessionToken 同 email 呼叫 /auth/logout,然後喺你存放令牌嘅地方將佢移除。更改密碼嘅做法相似,係透過 /auth/changePassword 進行。沿途記錄認證事件,萬一出事嘅時候就多一條有用嘅線索。

JWT 整合檢查清單

  • API 金鑰只存在於伺服器端設定,絕對唔會出現喺瀏覽器程式碼入面。
  • 每次註冊同登入之前,都會先重新呼叫一次 /auth/fooBar。
  • 令牌載荷入面唔會放任何密碼或機密;用 sub 同角色嚟識別用戶。
  • 會話令牌保存喺 HTTP-only Cookie 或者其他由伺服器控制嘅儲存位置。
  • 每個受保護嘅路由喺做任何嘢之前,都會先透過 /auth/validate 驗證令牌。
  • 令牌過期或者無效(401)嘅時候,會將用戶帶返去登入頁面。
  • 2FA 流程保存嘅係最終嘅會話令牌,而唔係 tempToken。
  • 所有通訊都用 HTTPS,而且令牌永遠唔會寫入日誌。

成個循環就係咁:認證一次,帶住已簽署嘅令牌,喺伺服器驗證,然後等佢自然過期。請閱讀入門指南了解完整嘅端點參考,或者比較下其他平台嘅做法。當令牌睇落有啲古怪,jwt.io 會話你知入面有啲乜。

JWT 整合JWT 電郵密碼身份驗證基於令牌嘅身份驗證jwt.io 除錯器RS512 JWT