前後端分離架構下使用 Sa-Token 完成登入認證

一、架構分析

目前絕大多數系統都已經採用 「前後端分離」 架構來設計了，傳統的Session模式鑑權也不再適合這種架構（或者需要額外寫很多的程式碼來專門適配）。

Sa-Token 是一個 java 輕量級許可權認證框架，專為前後端分離架構打造，主要解決登入認證、許可權認證、單點登入、OAuth2、微服務閘道器鑑權 等一系列許可權相關問題。

Gitee 開源地址：https://gitee.com/dromara/sa-token

本文將介紹在 Springboot 架構下的前後端分離專案，如何使用 Sa-Token 方便的完成登入認證。

首先在專案中引入 Sa-Token 依賴：

<!-- Sa-Token 許可權認證 -->
<dependency>
    <groupId>cn.dev33</groupId>
    <artifactId>sa-token-spring-boot-starter</artifactId>
    <version>1.34.0</version>
</dependency>

注：如果你使用的是 SpringBoot 3.x，只需要將 sa-token-spring-boot-starter 修改為 sa-token-spring-boot3-starter 即可。

二、無 Cookie 模式

無 Cookie 模式：特指不支援 Cookie 功能的終端，通俗來講就是我們常說的 —— 前後端分離模式。

常規 Web 端鑑權方法，一般由 Cookie模式 完成，而 Cookie 有兩個特性：

1. 可由後端控制寫入。
2. 每次請求自動提交。

這就使得我們在前端程式碼中，無需任何特殊操作，就能完成鑑權的全部流程（因為整個流程都是後端控制完成的）

而在app、小程式等前後端分離場景中，一般是沒有 Cookie 這一功能的，此時大多數人都會一臉懵逼，咋進行鑑權啊？

見招拆招，其實答案很簡單：

• 不能後端控制寫入了，就前端自己寫入。（難點在後端如何將 Token 傳遞到前端）
• 每次請求不能自動提交了，那就手動提交。（難點在前端如何將 Token 傳遞到後端，同時後端將其讀取出來）

三、後端將 token 返回到前端

1. 首先呼叫 StpUtil.login(id) 進行登入。
2. 呼叫 StpUtil.getTokenInfo() 返回當前對談的 token 詳細引數。
   • 此方法返回一個物件，其有兩個關鍵屬性：tokenName和tokenValue（token 的名稱和 token 的值）。
   • 將此物件傳遞到前臺，讓前端人員將這兩個值儲存到本地。

程式碼範例：

// 登入介面
@RequestMapping("doLogin")
public SaResult doLogin() {
	// 第1步，先登入上 
	StpUtil.login(10001);
	// 第2步，獲取 Token  相關引數 
	SaTokenInfo tokenInfo = StpUtil.getTokenInfo();
	// 第3步，返回給前端 
	return SaResult.data(tokenInfo);
}

四、前端將 token 提交到後端

1. 無論是app還是小程式，其傳遞方式都大同小異。
2. 那就是，將 token 塞到請求header裡 ，格式為：{tokenName: tokenValue}。
3. 以經典跨端框架 uni-app 為例：

方式1，簡單粗暴

// 1、首先在登入時，將 tokenValue 儲存在本地，例如：
uni.setStorageSync('tokenValue', tokenValue);

// 2、在發起ajax請求的地方，獲取這個值，並塞到header裡 
uni.request({
	url: 'https://www.example.com/request', // 僅為範例，並非真實介面地址。
	header: {
		"content-type": "application/x-www-form-urlencoded",
		"satoken": uni.getStorageSync('tokenValue')		// 關鍵程式碼, 注意引數名字是 satoken 
	},
	success: (res) => {
		console.log(res.data);	
	}
});

方式2，更加靈活

// 1、首先在登入時，將tokenName和tokenValue一起儲存在本地，例如：
uni.setStorageSync('tokenName', tokenName); 
uni.setStorageSync('tokenValue', tokenValue); 

// 2、在發起ajax的地方，獲取這兩個值, 並組織到head裡 
var tokenName = uni.getStorageSync('tokenName');	// 從本地快取讀取tokenName值
var tokenValue = uni.getStorageSync('tokenValue');	// 從本地快取讀取tokenValue值
var header = {
	"content-type": "application/x-www-form-urlencoded"
};
if (tokenName != undefined && tokenName != '') {
	header[tokenName] = tokenValue;
}

// 3、後續在發起請求時將 header 物件塞到請求頭部 
uni.request({
	url: 'https://www.example.com/request', // 僅為範例，並非真實介面地址。
	header: header,
	success: (res) => {
		console.log(res.data);	
	}
});

4. 只要按照如此方法將token值傳遞到後端，Sa-Token 就能像傳統PC端一樣自動讀取到 token 值，進行鑑權。
5. 你可能會有疑問，難道我每個ajax都要寫這麼一坨？豈不是麻煩死了？
   • 你當然不能每個 ajax 都寫這麼一坨，因為這種重複性程式碼都是要封裝在一個函數裡統一呼叫的。

其它解決方案：

如果你對 Cookie 非常瞭解，那你就會明白，所謂 Cookie ，本質上就是一個特殊的header引數而已，
而既然它只是一個 header 引數，我們就能手動模擬實現它，從而完成鑑權操作。

這其實是對無Cookie模式的另一種解決方案，有興趣的同學可以百度瞭解一下，在此暫不贅述。

五、程式碼對比

為了更加直觀的顯示出 前後端一體架構 和 前後端分離架構 的差異，此處再提供一個範例：

package com.pj.cases.up;

import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import cn.dev33.satoken.stp.SaTokenInfo;
import cn.dev33.satoken.stp.StpUtil;
import cn.dev33.satoken.util.SaResult;

/**
 * Sa-Token 前後端分離模式範例 
 * 
 * @author kong
 * @since 2022-10-17 
 */
@RestController
@RequestMapping("/NotCookie/")
public class NotCookieController {

	// 前後端一體模式的登入樣例    ---- http://localhost:8081/NotCookie/doLogin?name=zhang&pwd=123456
	@RequestMapping("doLogin")
	public SaResult doLogin(String name, String pwd) {
		if("zhang".equals(name) && "123456".equals(pwd)) {
			// 對談登入 
			StpUtil.login(10001);
		    return SaResult.ok();
		}
		return SaResult.error("登入失敗");
	}
	
	// 前後端分離模式的登入樣例    ---- http://localhost:8081/NotCookie/doLogin2?name=zhang&pwd=123456
	@RequestMapping("doLogin2")
	public SaResult doLogin2(String name, String pwd) {
		
		if("zhang".equals(name) && "123456".equals(pwd)) {
			
			// 對談登入 
			StpUtil.login(10001);
			
			// 與常規登入不同點之處：這裡需要把 Token 資訊從響應體中返回到前端 
			SaTokenInfo tokenInfo = StpUtil.getTokenInfo();
		    return SaResult.data(tokenInfo);
		}
		return SaResult.error("登入失敗");
	}
	
}

• 介面一：Token 將在 Cookie 上下文返回到前端，並由瀏覽器每次請求時自動提交，這種模式適合前後端一體的架構。
• 介面二：Token 將在響應 body 裡返回到前端，並由前端手動儲存，並手動在每次請求時提交，這種模式適合前後端分離的架構。

六、自定義 Token 提交的字首

在某些系統中，前端提交token時會在前面加個固定的字首，例如：

{
	"satoken": "Bearer xxxx-xxxx-xxxx-xxxx"
}

此時後端如果不做任何特殊處理，框架將會把Bearer 視為token的一部分，無法正常讀取token資訊，導致鑑權失敗。

為此，我們需要在yml中新增如下設定：

sa-token: 
	# token字首
	token-prefix: Bearer

此時 Sa-Token 便可在讀取 Token 時裁剪掉 Bearer，成功獲取xxxx-xxxx-xxxx-xxxx。

注意點：

1. Token字首 與 Token值 之間必須有一個空格。
2. 一旦設定了 Token字首，則前端提交 Token 時，必須帶有字首，否則會導致框架無法讀取 Token。
3. 由於Cookie中無法儲存空格字元，也就意味設定 Token 字首後，Cookie 鑑權方式將會失效，此時只能將 Token 提交到header裡進行傳輸。

七、自定義 Token 風格

Sa-Token預設的token生成策略是uuid風格，其模樣類似於：623368f0-ae5e-4475-a53f-93e4225f16ae。

如果你對這種風格不太感冒，還可以將token生成設定為其他風格。

怎麼設定呢？只需要在yml組態檔裡設定 sa-token.token-style=風格型別 即可，其有多種取值：

// 1. token-style=uuid    —— uuid風格 (預設風格)
"623368f0-ae5e-4475-a53f-93e4225f16ae"

// 2. token-style=simple-uuid    —— 同上，uuid風格, 只不過去掉了中劃線
"6fd4221395024b5f87edd34bc3258ee8"

// 3. token-style=random-32    —— 隨機32位元字串
"qEjyPsEA1Bkc9dr8YP6okFr5umCZNR6W"

// 4. token-style=random-64    —— 隨機64位元字串
"v4ueNLEpPwMtmOPMBtOOeIQsvP8z9gkMgIVibTUVjkrNrlfra5CGwQkViDjO8jcc"

// 5. token-style=random-128    —— 隨機128位元字串
"nojYPmcEtrFEaN0Otpssa8I8jpk8FO53UcMZkCP9qyoHaDbKS6dxoRPky9c6QlftQ0pdzxRGXsKZmUSrPeZBOD6kJFfmfgiRyUmYWcj4WU4SSP2ilakWN1HYnIuX0Olj"

// 6. token-style=tik    —— tik風格
"gr_SwoIN0MC1ewxHX_vfCW3BothWDZMMtx__"

八、自定義 Token 生成策略

如果你覺著以上風格都不是你喜歡的型別，那麼你還可以自定義token生成策略，來客製化化token生成風格。

怎麼做呢？只需要重寫 SaStrategy 策略類的 createToken 演演算法即可：

參考步驟如下：

1、在SaTokenConfigure設定類中新增程式碼：

@Configuration
public class SaTokenConfigure {
    /**
     * 重寫 Sa-Token 框架內部演演算法策略 
     */
    @Autowired
    public void rewriteSaStrategy() {
    	// 重寫 Token 生成策略 
    	SaStrategy.me.createToken = (loginId, loginType) -> {
    		return SaFoxUtil.getRandomString(60);	// 隨機60位元長度字串
    	};
    }
}

2、再次呼叫 StpUtil.login(10001)方法進行登入，觀察其生成的token樣式:

gfuPSwZsnUhwgz08GTCH4wOgasWtc3odP4HLwXJ7NDGOximTvT4OlW19zeLH

---

參考資料

• Sa-Token 檔案：https://sa-token.cc
• Gitee 倉庫地址：https://gitee.com/dromara/sa-token
• GitHub 倉庫地址：https://github.com/dromara/sa-token