SpringBoot 使用 Sa-Token 完成注解鑒權(quán)功能

注解鑒權(quán) —— 優(yōu)雅的將鑒權(quán)與業(yè)務(wù)代碼分離。本篇我們將介紹在 Sa-Token 中如何通過(guò)注解完成權(quán)限校驗(yàn)。

Sa-Token 是一個(gè)輕量級(jí) java 權(quán)限認(rèn)證框架，主要解決登錄認(rèn)證、權(quán)限認(rèn)證、單點(diǎn)登錄、OAuth2、微服務(wù)網(wǎng)關(guān)鑒權(quán) 等一系列權(quán)限相關(guān)問(wèn)題。
Gitee 開(kāi)源地址：https://gitee.com/dromara/sa-token

一、Sa-Token 鑒權(quán)注解一覽

Sa-Token 為我們提供的鑒權(quán)注解包括但不限于以下：

  • @SaCheckLogin: 登錄校驗(yàn) —— 只有登錄之后才能進(jìn)入該方法。
  • @SaCheckRole("admin"): 角色校驗(yàn) —— 必須具有指定角色標(biāo)識(shí)才能進(jìn)入該方法。
  • @SaCheckPermission("user:add"): 權(quán)限校驗(yàn) —— 必須具有指定權(quán)限才能進(jìn)入該方法。
  • @SaCheckSafe: 二級(jí)認(rèn)證校驗(yàn) —— 必須二級(jí)認(rèn)證之后才能進(jìn)入該方法。
  • @SaCheckBasic: HttpBasic校驗(yàn) —— 只有通過(guò) Basic 認(rèn)證后才能進(jìn)入該方法。
  • @SaCheckDisable("comment")：賬號(hào)服務(wù)封禁校驗(yàn) —— 校驗(yàn)當(dāng)前賬號(hào)指定服務(wù)是否被封禁。
  • @SaIgnore：忽略校驗(yàn) —— 表示被修飾的方法或類無(wú)需進(jìn)行注解鑒權(quán)和路由攔截器鑒權(quán)。

首先在項(xiàng)目中引入 Sa-Token 依賴：

<!-- Sa-Token 權(quán)限認(rèn)證 -->
<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 即可。

二、登錄認(rèn)證

Sa-Token 使用全局?jǐn)r截器完成注解鑒權(quán)功能，為了不為項(xiàng)目帶來(lái)不必要的性能負(fù)擔(dān)，攔截器默認(rèn)處于關(guān)閉狀態(tài)

因此，為了使用注解鑒權(quán)，你必須手動(dòng)將 Sa-Token 的全局?jǐn)r截器注冊(cè)到你項(xiàng)目中。

以SpringBoot2.0為例，新建配置類SaTokenConfigure.java

@Configuration
public class SaTokenConfigure implements WebMvcConfigurer {
    // 注冊(cè) Sa-Token 攔截器，打開(kāi)注解式鑒權(quán)功能 
    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        // 注冊(cè) Sa-Token 攔截器，打開(kāi)注解式鑒權(quán)功能 
        registry.addInterceptor(new SaInterceptor()).addPathPatterns("/**");    
    }
}

保證此類被springboot啟動(dòng)類掃描到即可。

新建 LoginController，添加以下代碼：

/**
 * 登錄認(rèn)證注解測(cè)試
 */
@RestController
public class LoginController {

    // 訪問(wèn) home 頁(yè)，登錄后才能訪問(wèn)  ---- http://localhost:8081/home
    @SaCheckLogin
    @RequestMapping("home")
    public SaResult home() {
        return SaResult.ok("訪問(wèn)成功，此處為登錄后才能看到的信息");
    }

    // 登錄接口  ---- http://localhost:8081/doLogin?name=zhang&pwd=123456
    @RequestMapping("doLogin")
    public SaResult doLogin(String name, String pwd) {
        // 此處僅作模擬示例，真實(shí)項(xiàng)目需要從數(shù)據(jù)庫(kù)中查詢數(shù)據(jù)進(jìn)行比對(duì)
        if("zhang".equals(name) && "123456".equals(pwd)) {
            StpUtil.login(10001);
            return SaResult.ok("登錄成功");
        }
        return SaResult.error("登錄失敗");
    }

}

啟動(dòng)項(xiàng)目，首次訪問(wèn)資源接口：

http://localhost:8081/home

返回如下：

{
    "code": 500,
    "msg": "未能讀取到有效Token",
    "data": null
}

會(huì)話尚未登錄，因此無(wú)法訪問(wèn)資源。

現(xiàn)在我們?cè)偃ピL問(wèn)一下登錄接口：

http://localhost:8081/doLogin?name=zhang&pwd=123456

返回如下：

{
    "code": 200,
    "msg": "登錄成功",
    "data": null
}

登錄成功，我們?cè)偃ピL問(wèn)資源接口：

http://localhost:8081/home

返回如下：

{
    "code": 200,
    "msg": "訪問(wèn)成功，此處為登錄后才能看到的信息",
    "data": null
}

通過(guò)登錄認(rèn)證校驗(yàn)，成功獲取到信息！

三、權(quán)限認(rèn)證 & 角色認(rèn)證

首先我們需要實(shí)現(xiàn) StpInterface 接口，告訴框架指定賬號(hào)擁有哪些權(quán)限碼。

/**
 * 自定義權(quán)限認(rèn)證接口擴(kuò)展，Sa-Token 將從此實(shí)現(xiàn)類獲取每個(gè)賬號(hào)擁有的權(quán)限碼 
 * 
 * @author kong
 * @since 2022-10-13
 */
@Component  // 打開(kāi)此注解，保證此類被springboot掃描，即可完成sa-token的自定義權(quán)限驗(yàn)證擴(kuò)展 
public class StpInterfaceImpl implements StpInterface {

    /**
     * 返回一個(gè)賬號(hào)所擁有的權(quán)限碼集合 
     */
    @Override
    public List<String> getPermissionList(Object loginId, String loginType) {
        // 本list僅做模擬，實(shí)際項(xiàng)目中要根據(jù)具體業(yè)務(wù)邏輯來(lái)查詢權(quán)限
        List<String> list = new ArrayList<String>();    
        list.add("101");
        list.add("user.add");
        list.add("user.update");
        list.add("user.get");
        // list.add("user.delete");
        list.add("art.*");
        return list;
    }

    /**
     * 返回一個(gè)賬號(hào)所擁有的角色標(biāo)識(shí)集合 
     */
    @Override
    public List<String> getRoleList(Object loginId, String loginType) {
        // 本list僅做模擬，實(shí)際項(xiàng)目中要根據(jù)具體業(yè)務(wù)邏輯來(lái)查詢角色
        List<String> list = new ArrayList<String>();    
        list.add("admin");
        list.add("super-admin");
        return list;
    }

}

使用以下兩個(gè)注解完成校驗(yàn)：

  • @SaCheckPermission("user.add")：校驗(yàn)當(dāng)前會(huì)話是否具有某個(gè)權(quán)限。
  • @SaCheckRole("super-admin")：校驗(yàn)當(dāng)前會(huì)話是否具有某個(gè)角色。
/**
 * Sa-Token 注解鑒權(quán)示例 
 * 
 * @author kong
 * @since 2022-10-13
 */
@RestController
@RequestMapping("/at-check/")
public class AtCheckController {

    /*
     * 前提1：首先調(diào)用登錄接口進(jìn)行登錄
     *      ---- http://localhost:8081/doLogin?name=zhang&pwd=123456
     * 
     * 前提2：項(xiàng)目在配置類中注冊(cè)攔截器 SaInterceptor ，此攔截器將打開(kāi)注解鑒權(quán)功能 
     * 
     * 前提3：項(xiàng)目實(shí)現(xiàn)了 StpInterface 接口，此接口會(huì)告訴框架指定賬號(hào)擁有哪些權(quán)限碼
     * 
     * 然后我們就可以使用以下示例中的代碼進(jìn)行注解鑒權(quán)了 
     */
    
    // 權(quán)限校驗(yàn)   ---- http://localhost:8081/at-check/checkPermission
    //      只有具有 user.add 權(quán)限的賬號(hào)才可以進(jìn)入方法 
    @SaCheckPermission("user.add")
    @RequestMapping("checkPermission")
    public SaResult checkPermission() {
        // ... 
        return SaResult.ok();
    }

    // 角色校驗(yàn)   ---- http://localhost:8081/at-check/checkRole
    //      只有具有 super-admin 角色的賬號(hào)才可以進(jìn)入方法 
    @SaCheckRole("super-admin")
    @RequestMapping("checkRole")
    public SaResult checkRole() {
        // ... 
        return SaResult.ok();
    }
    
}

可根據(jù)代碼注釋提供的鏈接進(jìn)行測(cè)試訪問(wèn)。

四、設(shè)定校驗(yàn)?zāi)Ｊ?/h3>

@SaCheckRole與@SaCheckPermission注解可設(shè)置校驗(yàn)?zāi)Ｊ?，例如?/p> 

// 注解式鑒權(quán)：只要具有其中一個(gè)權(quán)限即可通過(guò)校驗(yàn) 
@RequestMapping("atJurOr")
@SaCheckPermission(value = {"user-add", "user-all", "user-delete"}, mode = SaMode.OR)       
public SaResult atJurOr() {
    return SaResult.data("用戶信息");
}

mode有兩種取值：

  • SaMode.AND, 標(biāo)注一組權(quán)限，會(huì)話必須全部具有才可通過(guò)校驗(yàn)。
  • SaMode.OR, 標(biāo)注一組權(quán)限，會(huì)話只要具有其一即可通過(guò)校驗(yàn)。

五、角色權(quán)限雙重 “or校驗(yàn)”

假設(shè)有以下業(yè)務(wù)場(chǎng)景：一個(gè)接口在具有權(quán)限 user.add 或角色 admin 時(shí)可以調(diào)通。怎么寫(xiě)？

// 角色權(quán)限雙重 “or校驗(yàn)”：具備指定權(quán)限或者指定角色即可通過(guò)校驗(yàn)
@RequestMapping("userAdd")
@SaCheckPermission(value = "user.add", orRole = "admin")        
public SaResult userAdd() {
    return SaResult.data("用戶信息");
}

orRole 字段代表權(quán)限認(rèn)證未通過(guò)時(shí)的次要選擇，兩者只要其一認(rèn)證成功即可通過(guò)校驗(yàn)，其有三種寫(xiě)法：

  • 寫(xiě)法一：orRole = "admin"，代表需要擁有角色 admin 。
  • 寫(xiě)法二：orRole = {"admin", "manager", "staff"}，代表具有三個(gè)角色其一即可。
  • 寫(xiě)法三：orRole = {"admin, manager, staff"}，代表必須同時(shí)具有三個(gè)角色。

六、二級(jí)認(rèn)證

@RestController
@RequestMapping("/at/")
public class AtController {

    // 在當(dāng)前會(huì)話完成二級(jí)認(rèn)證  ---- http://localhost:8081/at/openSafe 
    @RequestMapping("openSafe")
    public SaResult openSafe() {
        StpUtil.openSafe(200); // 打開(kāi)二級(jí)認(rèn)證，有效期為200秒
        return SaResult.ok();
    }
    
    // 通過(guò)二級(jí)認(rèn)證后，才可以進(jìn)入  ---- http://localhost:8081/at/checkSafe 
    @SaCheckSafe
    @RequestMapping("checkSafe")
    public SaResult checkSafe() {
        return SaResult.ok();
    }

}

必須先經(jīng)過(guò) StpUtil.openSafe(1200) 打開(kāi)二級(jí)認(rèn)證（參數(shù)為指定認(rèn)證有效期，單位：秒），才可以通過(guò) @SaCheckSafe 的檢查。

七、HttpBasic認(rèn)證：

@RestController
@RequestMapping("/at/")
public class AtController {

    // 通過(guò)Basic認(rèn)證后才可以進(jìn)入  ---- http://localhost:8081/at/checkBasic 
    @SaCheckBasic(account = "sa:123456")
    @RequestMapping("checkBasic")
    public SaResult checkBasic() {
        return SaResult.ok();
    }
    
}

當(dāng)我們?cè)L問(wèn)這個(gè)接口時(shí)，瀏覽器會(huì)強(qiáng)制彈出一個(gè)表單：

1.png

當(dāng)我們輸入賬號(hào)密碼后 （sa / 123456），才可以繼續(xù)訪問(wèn)數(shù)據(jù)：

2.png

八、服務(wù)禁用性校驗(yàn)

@RestController
@RequestMapping("/at/")
public class AtController {

    // 只有當(dāng)前服務(wù)沒(méi)有禁用 comment 服務(wù)時(shí)，才能夠進(jìn)入方法  ---- http://localhost:8081/at/comment 
    @SaCheckDisable("comment")
    @RequestMapping("comment")
    public SaResult comment() {
        return SaResult.ok();
    }

}

@SaCheckDisable 注解的作用是檢測(cè)當(dāng)前賬號(hào)是否被禁用了指定服務(wù)，如果已被禁用則無(wú)法進(jìn)入指定方法，
在之后的章節(jié)我們會(huì)詳細(xì)講述服務(wù)禁用的相關(guān)代碼，此處先稍作了解即可。

九、忽略認(rèn)證

使用 @SaIgnore 可表示一個(gè)接口忽略認(rèn)證：

@SaCheckLogin
@RestController
public class TestController {
    
    // ... 其它方法 
    
    // 此接口加上了 @SaIgnore 可以游客訪問(wèn) 
    @SaIgnore
    @RequestMapping("getList")
    public SaResult getList() {
        // ... 
        return SaResult.ok(); 
    }
}

如上代碼表示：TestController 中的所有方法都需要登錄后才可以訪問(wèn)，但是 getList 接口可以匿名游客訪問(wèn)。

  • @SaIgnore 修飾方法時(shí)代表這個(gè)方法可以被游客訪問(wèn)，修飾類時(shí)代表這個(gè)類中的所有接口都可以游客訪問(wèn)。
  • @SaIgnore 具有最高優(yōu)先級(jí)，當(dāng) @SaIgnore 和其它鑒權(quán)注解一起出現(xiàn)時(shí)，其它鑒權(quán)注解都將被忽略。
  • @SaIgnore 同樣可以忽略掉 Sa-Token 攔截器中的路由鑒權(quán)，在下面的 [路由攔截鑒權(quán)] 章節(jié)中我們會(huì)講到。

十、在業(yè)務(wù)邏輯層使用注解鑒權(quán)

疑問(wèn)：我能否將注解寫(xiě)在其它架構(gòu)層呢，比如業(yè)務(wù)邏輯層？

使用攔截器模式，只能在Controller層進(jìn)行注解鑒權(quán)，如需在任意層級(jí)使用注解鑒權(quán)，可使用 AOP注解鑒權(quán) 插件。

<!-- Sa-Token 整合 SpringAOP 實(shí)現(xiàn)注解鑒權(quán) -->
<dependency>
    <groupId>cn.dev33</groupId>
    <artifactId>sa-token-spring-aop</artifactId>
    <version>1.34.0</version>
</dependency>

集成此插件后，便可以在任意層使用 Sa-Token 的注解鑒權(quán)了（例如業(yè)務(wù)邏輯層），不過(guò)需要注意的是：

  • 攔截器模式和AOP模式不可同時(shí)集成，否則會(huì)在 Controller 層發(fā)生一個(gè)注解校驗(yàn)兩次的bug。

參考資料

?著作權(quán)歸作者所有,轉(zhuǎn)載或內(nèi)容合作請(qǐng)聯(lián)系作者
【社區(qū)內(nèi)容提示】社區(qū)部分內(nèi)容疑似由AI輔助生成，瀏覽時(shí)請(qǐng)結(jié)合常識(shí)與多方信息審慎甄別。
平臺(tái)聲明：文章內(nèi)容（如有圖片或視頻亦包括在內(nèi)）由作者上傳并發(fā)布，文章內(nèi)容僅代表作者本人觀點(diǎn)，簡(jiǎn)書(shū)系信息發(fā)布平臺(tái)，僅提供信息存儲(chǔ)服務(wù)。

相關(guān)閱讀更多精彩內(nèi)容

友情鏈接更多精彩內(nèi)容