32 圖 | 手摸手 Spring Cloud Gateway + JWT 實現登錄認證

作者：悟空聊架構 2022-08-15 09:22:12

開發前端

雖然本篇是講實戰內容的，但是里面又涉及了很多原理性內容，比如網關、JWT 的原理。結合實戰講解，相信大家對如何使用 Spring Cloud Gateway + JWT 實現登錄認證有了充分的理解。

通過本文你會掌握以下知識點：

如何用認證服務做登錄認證。
如何生成 JWT 令牌(Token)
如何用 Gateway 對 Token 驗證。
Gateway 如何從 Token 中拿到用戶信息并轉發給業務服務。
業務服務如何從請求中拿到身份信息處理業務邏輯。
如何刷新令牌。

本篇還是基于我的開源項目 PassJava 作為講解。

PassJava 開源地址：https://github.com/Jackson0714/PassJava-Platform

在講解之前有必要澄清下什么是認證、授權、憑證，這三個方面是一個系統中最基礎的安全設計。

認證、授權、憑證

1.1 認證（Authentication）

認證表示你是誰。系統如何正確分辨出操作用戶的真實身份，比如通過輸入用戶名和密碼來辨別身份。

1.2 授權（Authorization）

授權表示你能干什么。系統如何控制一個用戶能看到哪些數據和操作哪些功能，也就是具有哪些權限。

1.3 憑證（Credential）

表示你如何證明你的身份。系統如何保證它與用戶之間的承諾是雙方當時真實意圖的體現，是準確、完整和不可抵賴的。

接下來我們看下使用 JWT 作為憑證完成認證的原理。

認證的原理

在如下的認證時序圖中，有以下幾種角色：

?客戶端：表示 APP 端或 PC 端的前端頁面。
網關：表示 Spring Cloud Gateway 網關服務，這里。
認證服務：用來接收客戶的登錄請求、登出請求、刷新令牌的操作。
業務服務：和系統業務相關的微服務。

認證和校驗身份的流程如下所示：

認證和校驗身份流程

① 用戶登錄：客戶端在登錄頁面輸入用戶名和密碼，提交表單，調用登錄接口。
② 轉發請求：這里會先將登錄請求發送到網關服務 passjava-gateway，網關對于登錄請求會直接轉發到認證服務 passjava-auth。（網關對登錄請求不做 token 校驗，這個可以配置不校驗哪些請求 URL）
③ 認證：認證服務會將請求參數中的用戶名+密碼和數據庫中的用戶進行比對，如果完全匹配，則認證通過。
④ 生成令牌：生成兩個令牌：access_token 和 refresh_token（刷新令牌），刷新令牌我們后面再說，這里其實也可以只用生成一個令牌 access_token。令牌里面會包含用戶的身份信息，如果要做權限管控，還需要在 token 里面包含用戶的權限信息，權限這一塊不在本篇展開，會放到下一篇中進行講解。
⑤ 客戶端緩存 token：客戶端拿到兩個 token 緩存到 cookie 中或者 LocalStorage 中。
⑥ 攜帶 token 發起請求：客戶端下次想調用業務服務時，將 access_token 放到請求的 header 中。
⑦ 網關校驗 token：請求還是先到網關服務，然后由它校驗 access_token 是否合法。如果 access_token 未過期，且能正確解析出來，就說明是合法的 access_token。
⑧ 攜帶用戶身份信息轉發請求：網關將 access_token 中攜帶的用戶的 user_id 放到請求的 header 中，轉發給真正的業務服務。
⑨ 處理業務邏輯：業務服務從 header 中拿到用戶的 user_id，然后處理業務邏輯，處理完后將結果原路返回給客戶端。
接下來我們看下項目的整體架構。

項目整體結構

Github 項目地址：https://github.com/Jackson0714/PassJava-Platform

Gitee 項目地址：https://toscode.gitee.com/jayh2018/PassJava-Platform

認證服務：passjava-auth
網關服務：passjava-gateway
JWT 公共項目：passjava-jwt，認證服務和網關服務都會引用這個公共項目。
業務服務：passjava-member，會員服務作為本次案例的業務服務。
Nacos 注冊配置中心

PassJava-Platform 框架

認證服務：passjava-auth

passjava-auth 服務

核心類就是 JwtAuthController 類，里面有登錄接口和刷新令牌的接口。

網關服務：passjava-gateway

passjava-gateway 服務

核心類就是 JwtAuthCheckFilter 全局過濾器。

如果不需要在服務端保存刷新令牌，可以不需要 redis 配置。

JWT 公共項目

passjava-jwt 服務

核心類就是 PassJavaJWTTokenUtil 工具類。認證服務引入 JWT 項目后用來生成 token，網關服務引入 JWT 項目后用來校驗 token 合法性。

業務服務

這里我選擇了會員微服務作為本次演示的業務微服務。

它從網關轉發的請求 Header 中拿到 userId，根據 userId 查詢 member 信息。

passjava-member 服務

核心文件是 MemberController 類、MemberEntity實體類、MemberService服務類、MemberDao 類和 mapper 文件。

啟動的服務

Nacos 注冊配置中心

首先啟動 Nacos 服務。和 PassJava 項目配套使用的 Nacos 工具已經上傳到網盤，下載后直接運行啟動腳本就可以將 Nacos 在本地啟動。

啟動教程：

www.passjava.cn/#/01.項目簡介/7.本地部署項目Mac版

網關、會員、認證服務

啟動以下三個微服務，分別為網關、會員、認證服務。

檢查下 nacos 注冊中心上是否注冊了這三個服務：可以看到確實有上面的三個微服務。

如何做登錄認證

登錄認證就是校驗下用戶提交的賬戶名和密碼與本地數據庫中的是否完全匹配，如果匹配，就認證通過。就是下方這個流程的 1、2、3 步。

第一步：提交用戶名和密碼

這里用 Postman 工具模擬前端發起登錄請求，請求的 URL 如下：

http://localhost:8060/api/auth/login

請求是向網關服務 passjava-gateway 發起的，所以可以看到上面的 URL 中 localhost 和 8060 是網關的 host 和 port。

然后 API 地址為 /api/auth/login，這個地址經過網關的路由匹配后會轉發到 passjava-auth 服務的登錄 API。

http://localhost:10001/auth/login

關于網關轉發的原理可以參考這篇：深入理解 Spring Cloud Gateway 的原理

請求參數如下：

{
    "userId": "wukong",
    "password": "123456"
}

賬號和密碼都是密文的，轉發到認證服務后，會根據 userId 查詢出系統用戶，然后將 password 參數加密后對比系統用戶的密碼。

所以為了讓用戶登錄成功，還需要在數據庫插入一條系統用戶，用戶 id 為 wukong，密碼是對 123456 加密后的密碼。

在線加密工具地址：

https://www.bejson.com/encrypt/bcrpyt_encode/

第二步：轉發登錄請求

轉發登錄請求是網關服務做的，所以我們來看下做了哪些事情。

在 Gateway 項目的 application-routers.yml 中配置路由規則：

spring:
  cloud:
    gateway:
      routes:
        - id: route_auth # 認證微服務路由規則
          uri: lb://passjava-auth # 負載均衡，將請求轉發到注冊中心注冊的 passjava-auth 服務
          predicates: # 斷言
            - Path=/api/auth/** # 如果前端請求路徑包含 api/auth，則應用這條路由規則
          filters: #過濾器
            - RewritePath=/api/(?<segment>.*),/$\{segment} # 將跳轉路徑中包含的api替換成空

在 application.properties 引入 application-routers.yml

spring:
  profiles:
    include: routers, jwt

第三步：驗證用戶賬號和密碼

這一步是認證服務的登錄 API 里面做的。在 AuthController 中定義 login 接口，核心步驟就是查找系統用戶和比對密碼。

登錄 API

用戶名和密碼匹配成功后，就會生成 JWT 令牌。

如何生成令牌

生成令牌就是通過工具類 PassJavaJwtTokenUtil 生成 JWT Token，也就是流程圖中的第四步。

流程圖-生成 JWT 令牌

生成令牌的核心代碼如下：

生成 JWT 的核心代碼

使用這個工具類的前提是我們需要先引入 jjwt 依賴。這個在 passjava-jwt 項目的 pom 文件中引入。

引入 jjwt 依賴

用 Postman 工具調用后，可以看到生成的令牌如下：

生成令牌

用 base64 解碼后，可以看到 token 中的 PAYLOAD 里面包含了用戶 id 和用戶名。

生成 JWT 的加密密鑰一般都是寫到配置文件中。這里我是配置在 passjava-jwt 項目的 application-jwt.yml 配置文件中的。

JWT 配置項

然后認證服務就會將 JWT 令牌返回給客戶端了。當客戶端想要查詢這個 userId 對應的會員信息時，就可以在請求的 Header 中帶上 JWT 令牌。

如何攜帶 JWT 發送請求

客戶端（瀏覽器或 APP）拿到 JWT 后，可以將 JWT 存放在瀏覽器的 Cookie 或 LocalStorage（本地存儲）或者內存中。

發送請求時在請求 Header 的 Authorization 字段中設置 JWT，這個字段其實可以自定義，但是我建議用 Authorization，因為這是一種業界標準。

另外告訴大家一個小技巧，在 Postman 工具中有個地方專門配置 Authorization，然后自動加到 Header 中，不用自己手動加 Header。

還有一個點需要注意，這里配置的 Authorization 的認證類型為 Bearer Token。它表示令牌可以是任意字符串格式的令牌。然后會在 Authorization 字段中加上一個前綴 Bearer。所以我們在網關服務解析 Header 中的 Authorization 時，需要去掉這個前綴 Bearer，代碼如下所示：

去掉 Bearer 前綴

網關如何驗證 JWT 和轉發請求

網關驗證 Token和轉發請求

網關接收到前端發起的業務請求后，會先驗證請求的 Header 中是否攜帶 Authorization 字段，以及里面的 Token 是否合法。然后解析 Token 中的 userId 和 username，放到 header 中再進行轉發，也就是流程圖中的第七步和第八步。

網關是通過多個??過濾器 Filter??對請求進行串行攔截處理的，所以我們可以自定義一個全局過濾器，對所有請求進行校驗，當然對于一些特殊請求比如登錄請求就不需要校驗了，因為調用登錄請求的時候還沒有生成 Token。

網關的全局過濾器 JwtAuthCheckFilter 的核心代碼如下所示：

網關的全局過濾器 JwtAuthCheckFilter

會員服務處理業務邏輯

會員服務接收到網關轉發的請求后，就從 Header 中拿到用戶身份信息，然后通過 userId 獲取會員信息。

注意：有的時候業務邏輯并不需要身份信息，更多的時候是需要檢驗用戶的操作權限是否足夠。其實 Token 里面也是可以攜帶權限信息的，不過這是下一篇講解授權的部分。

獲取 userId 的方式其實可以通過加一個??攔截器??，由攔截器將 Header 中的 userId 和 username 放到線程中，后續的 controller，service，dao 類都可以從線程里面拿到 userId 和 username，不用通過傳參的方式。

獲取 userId 的方式：

方式一：從 request 的 Header 中拿到 userId。代碼簡單，但是如果其他地方也要用到 userId，則需要通過方法傳參的方式傳遞 userId。
方式二：從線程變量里面拿到 userId。代碼復雜，使用簡單。好處是所有地方統一從一個地方獲取。

Request 中獲取 userId 方式

代碼示例如下：

下面介紹如何使用攔截器方式將 userId 存入線程變量的方式。

攔截器方式

在 passjava-common 模塊中新增一個攔截器，獲取請求頭中的身份信息，加入到線程變量中。文件名為 HeaderInterceptor。

將攔截器注冊到 WebMvcConfigurer。文件名為 WebMvcConfig.java。

配置文件中需要定義一個配置項：

文件名；org.springframework.boot.autoconfigure.AutoConfiguration.imports
配置項：com.jackson0714.passjava.common.config.WebMvcConfig

然后 passjava-member 服務引入這個攔截器配置。

@Import({WebMvcConfig.class})

通過上面兩種方式中的任意一種拿到 userId 后，通過 userId 查詢會員的詳情。這里需要注意的是這個 user 既是系統用戶也是系統中的會員。關于查詢會員的數據庫操作就不在此展開了。

執行結果如下圖所示：

如何刷新令牌

還有一個內容是關于如何刷新令牌的。當認證服務返回給客戶端的 JWT 也就是 access_token 過期后，客戶端是通過發送登錄請求重新拿到 access_token 嗎？

這種重新登錄的操作如果很頻繁（因 JWT 過期時間較短），對于用戶來說體驗就很差了。客戶端需要跳轉到登錄頁面，讓用戶重新提交用戶名和密碼，即使客戶端有記住用戶名和密碼，但是這種跳轉到登錄頁的操作會大幅度降低用戶的體驗，甚至導致用戶不想再用第二次。

有沒有一種比較優雅的方式讓客戶端重新拿到 access_token 或者說延長 access_token 有效期呢？

我們知道 JWT 生成后是不能篡改里面的內容，即使是 JWT 的有效期也不行。所以延長 access_token 有效期的做法并不適合，而且如果長期保持一個 access_token 有效，也是不安全的。

那就只能重新生成 access_token 了。方案其實挺簡單，客戶端拿之前生成的 JWT 調用后端一個接口，然后后端校驗這個 JWT 是否合法，如果是合法的就重新生成一個新的返回給客戶端。客戶端自行替換掉之前本地保存的 access_token 就可以了。

生成 access_token 和 refresh_token

這里有一個巧妙的設計，就是生成 JWT 時，返回了兩個 JWT token，一個 access_token，一個 refresh_token，這兩個 token 其實都可以用來刷新 token，但是我們把 refresh_token 設置的過期時間稍微長一點，比如兩倍于 access_token，當 access_token 過期后，refresh_token 如果還沒有過期，就可以利用兩者的過期時間差進行重新生成令牌的操作，也就是刷新令牌，這里的刷新指的是客戶端重置本地保存的令牌，以后都用新的令牌。

饑餓模式和懶模式

當然，在 access_token 過期之前，客戶端提前刷新令牌也是可以的，我稱這種提前刷新的模式為??饑餓模式???（單例模式中也有這種叫法），而過期后再刷新令牌的模式我稱之為??懶模式??。兩種模式都可以用，前者需要客戶端定期檢查過期時間，增加了復雜性；后者則會出現短暫的請求失敗的情況，得拿到新的令牌后才會成功。

刷新令牌的操作完全是通過客戶端自己控制的，而且客戶端也不僅限于瀏覽器，還有可能是第三方服務。

一次性

通常情況下，我們會將刷新令牌 refresh_token 設置為只能用一次，來保證刷新令牌的安全性。而這種就需要服務端來緩存刷新令牌了，當用過一次后，就從緩存里面主動剔除掉。但這樣就違背了 JWT 無狀態的特性，這個完全看業務需求來決定是否使用這種緩存方式。

如下圖所示，生成令牌時我將刷新令牌緩存到了 Redis 里面。當我用 refresh_token 調用刷新 API 時，會主動剔除掉這個 key，下次再用相同的 refresh_token 刷新令牌時，因 Redis 中不存在這個 key，就會提示刷新刷新失敗了。

緩存令牌

留兩個小問題：

有沒有辦法讓 access_token 主動失效？
場景題：如何保證同一個用戶只能登錄一臺設備？

總結

雖然本篇是講實戰內容的，但是里面又涉及了很多原理性內容，比如網關、JWT 的原理。

結合實戰講解，相信大家對如何使用 Spring Cloud Gateway + JWT 實現登錄認證有了充分的理解。

本篇只講解了認證和憑證，授權部分還沒有觸及，所以這也是下篇要講解的內容，來追更吧~

最后再說一句，別白嫖，點贊轉發下哦~

責任編輯：武曉燕來源：悟空聊架構

JWT 認證系統