mirror of
https://gitee.com/dromara/sa-token.git
synced 2025-08-23 22:11:29 +08:00
优化文档：登录认证、权限认证
This commit is contained in:
click33
parent
6e1df178a3
commit
fcd2ca7f8d
@ -3,8 +3,8 @@
|
||||
- **开始**
|
||||
- [介绍](/)
|
||||
- [引入](/start/download)
|
||||
- [在SpringBoot环境集成](/start/example)
|
||||
- [在WebFlux环境集成](/start/webflux-example)
|
||||
- [在 SpringBoot 环境集成](/start/example)
|
||||
- [在 WebFlux 环境集成](/start/webflux-example)
|
||||
|
||||
- **基础**
|
||||
- [登录认证](/use/login-auth)
|
||||
|
||||
@ -195,7 +195,7 @@ implementation 'cn.dev33:sa-token-core:${sa.top.version}'
|
||||
## jar包下载
|
||||
[点击下载：sa-token-1.6.0.jar](https://oss.dev33.cn/sa-token/sa-token-1.6.0.jar)
|
||||
|
||||
(注意：当前仅提供`v1.6.0`版本jar包下载，更多版本请前往maven中央仓库获取，[直达链接](https://search.maven.org/search?q=sa-token))
|
||||
注：当前仅提供 `v1.6.0` 版本jar包下载，更多版本请前往 maven 中央仓库获取，[直达链接](https://search.maven.org/search?q=sa-token)
|
||||
|
||||
|
||||
|
||||
|
||||
@ -2,8 +2,7 @@
|
||||
|
||||
本篇带你从零开始集成 Sa-Token，从而快速熟悉框架的使用姿势。
|
||||
|
||||
整合示例地址： [/sa-token-demo/sa-token-demo-springboot](https://gitee.com/dromara/sa-token/tree/master/sa-token-demo/sa-token-demo-springboot)，
|
||||
如遇到难点可结合示例源码进行学习测试。
|
||||
整合示例在官方仓库的`/sa-token-demo/sa-token-demo-springboot`文件夹下，如遇到难点可结合源码进行学习测试。
|
||||
|
||||
---
|
||||
|
||||
|
||||
@ -1,16 +1,16 @@
|
||||
# Spring WebFlux 集成 Sa-Token 示例
|
||||
|
||||
**Reactor** 是一种非阻塞的响应式模型，本篇将以 **WebFlux** 为例，展示 Sa-Token 与 Reactor 响应式模型框架相整合的示例，
|
||||
**你可以用同样方式去对接其它Reactor模型框架（Netty、ShenYu、SpringCloud Gateway等）**
|
||||
**你可以用同样方式去对接其它 Reactor 模型框架（Netty、ShenYu、SpringCloud Gateway等）**
|
||||
|
||||
整合示例在官方仓库的`/sa-token-demo/sa-token-demo-webflux`文件夹下，如遇到难点可结合源码进行测试学习
|
||||
|
||||
!> WebFlux常用于微服务网关架构中，如果您的应用基于单体架构且非 Reactor 模型，可以先跳过本章
|
||||
!> WebFlux 常用于微服务网关架构中，如果您的应用基于单体架构且非 Reactor 模型，可以先跳过本章
|
||||
|
||||
---
|
||||
|
||||
### 1、创建项目
|
||||
在IDE中新建一个SpringBoot项目，例如：`sa-token-demo-webflux`（不会的同学请自行百度或者参考github示例）
|
||||
在 IDE 中新建一个 SpringBoot 项目，例如：`sa-token-demo-webflux`
|
||||
|
||||
|
||||
### 2、添加依赖
|
||||
@ -40,7 +40,7 @@ public class SaTokenDemoApplication {
|
||||
```
|
||||
|
||||
### 4、创建全局过滤器
|
||||
新建`SaTokenConfigure.java`，注册Sa-Token的全局过滤器
|
||||
新建`SaTokenConfigure.java`，注册 Sa-Token 的全局过滤器
|
||||
``` java
|
||||
/**
|
||||
* [Sa-Token 权限认证] 全局配置类
|
||||
@ -71,7 +71,7 @@ public class SaTokenConfigure {
|
||||
}
|
||||
}
|
||||
```
|
||||
?> 你只需要按照此格式复制代码即可，有关过滤器的详细用法，会在之后的章节详细介绍
|
||||
你只需要按照此格式复制代码即可，有关过滤器的详细用法，会在之后的章节详细介绍。
|
||||
|
||||
|
||||
### 5、创建测试Controller
|
||||
@ -108,7 +108,7 @@ public class UserController {
|
||||
|
||||
|
||||
|
||||
**注意事项**
|
||||
**注意事项：**
|
||||
|
||||
更多使用示例请参考官方仓库demo
|
||||
|
||||
|
||||
@ -2,36 +2,31 @@
|
||||
---
|
||||
|
||||
|
||||
### 核心思想
|
||||
### 设计思路
|
||||
|
||||
所谓权限认证，认证的核心就是一个账号是否拥有一个权限码 <br/>
|
||||
有，就让你通过。没有？那么禁止访问!
|
||||
所谓权限认证，核心逻辑就是判断一个账号是否拥有指定权限：<br/>
|
||||
- 有，就让你通过。
|
||||
- 没有？那么禁止访问！
|
||||
|
||||
再往底了说，就是每个账号都会拥有一个权限码集合，我来校验这个集合中是否包含指定的权限码 <br/>
|
||||
例如：当前账号拥有权限码集合：`["user-add", "user-delete", "user-get"]`，这时候我来校验权限 `"user-update"`，则其结果就是：**验证失败，禁止访问** <br/>
|
||||
深入到底层数据中，就是每个账号都会拥有一个权限码集合，框架来校验这个集合中是否包含指定的权限码。
|
||||
|
||||
例如：当前账号拥有权限码集合 `["user-add", "user-delete", "user-get"]`，这时候我来校验权限 `"user-update"`，则其结果就是：**验证失败，禁止访问**。 <br/>
|
||||
|
||||
|
||||
<button class="show-img" img-src="https://oss.dev33.cn/sa-token/doc/g/g3--jur-auth.gif">加载动态演示图</button>
|
||||
|
||||
|
||||
所以现在问题的核心就是:
|
||||
1. 如何获取一个账号所拥有的的权限码集合
|
||||
2. 本次操作需要验证的权限码是哪个
|
||||
所以现在问题的核心就是：
|
||||
1. 如何获取一个账号所拥有的的权限码集合？
|
||||
2. 本次操作需要验证的权限码是哪个？
|
||||
|
||||
### 获取当前账号权限码集合
|
||||
因为每个项目的需求不同，其权限设计也千变万化，因此【获取当前账号权限码集合】这一操作不可能内置到框架中，
|
||||
所以 Sa-Token 将此操作以接口的方式暴露给你，以方便的你根据自己的业务逻辑进行重写
|
||||
因为每个项目的需求不同，其权限设计也千变万化，因此 [ 获取当前账号权限码集合 ] 这一操作不可能内置到框架中，
|
||||
所以 Sa-Token 将此操作以接口的方式暴露给你，以方便你根据自己的业务逻辑进行重写。
|
||||
|
||||
你需要做的就是新建一个类，实现`StpInterface`接口，例如以下代码：
|
||||
你需要做的就是新建一个类，实现 `StpInterface`接口，例如以下代码：
|
||||
|
||||
``` java
|
||||
package com.pj.satoken;
|
||||
|
||||
import java.util.ArrayList;
|
||||
import java.util.List;
|
||||
import org.springframework.stereotype.Component;
|
||||
import cn.dev33.satoken.stp.StpInterface;
|
||||
|
||||
/**
|
||||
* 自定义权限验证接口扩展
|
||||
*/
|
||||
@ -69,6 +64,10 @@ public class StpInterfaceImpl implements StpInterface {
|
||||
}
|
||||
```
|
||||
|
||||
**参数解释：**
|
||||
- loginId：账号id，即你在调用 `StpUtil.login(id)` 时写入的标识值。
|
||||
- loginType：账号体系标识，此处可以暂时忽略，在 [ 多账户认证 ] 章节下会对这个概念做详细的解释。
|
||||
|
||||
可参考代码：[码云：StpInterfaceImpl.java](https://gitee.com/dromara/sa-token/blob/master/sa-token-demo/sa-token-demo-springboot/src/main/java/com/pj/satoken/StpInterfaceImpl.java)
|
||||
|
||||
|
||||
@ -76,7 +75,10 @@ public class StpInterfaceImpl implements StpInterface {
|
||||
### 权限认证
|
||||
然后就可以用以下api来鉴权了
|
||||
|
||||
``` java
|
||||
``` java
|
||||
// 获取：当前账号所拥有的权限集合
|
||||
StpUtil.getPermissionList();
|
||||
|
||||
// 判断：当前账号是否含有指定权限, 返回true或false
|
||||
StpUtil.hasPermission("user-update");
|
||||
|
||||
@ -87,7 +89,7 @@ StpUtil.checkPermission("user-update");
|
||||
StpUtil.checkPermissionAnd("user-update", "user-delete");
|
||||
|
||||
// 校验：当前账号是否含有指定权限 [指定多个，只要其一验证通过即可]
|
||||
StpUtil.checkPermissionOr("user-update", "user-delete");
|
||||
StpUtil.checkPermissionOr("user-update", "user-delete");
|
||||
```
|
||||
|
||||
扩展：`NotPermissionException` 对象可通过 `getLoginType()` 方法获取具体是哪个 `StpLogic` 抛出的异常
|
||||
@ -97,6 +99,9 @@ StpUtil.checkPermissionOr("user-update", "user-delete");
|
||||
在Sa-Token中，角色和权限可以独立验证
|
||||
|
||||
``` java
|
||||
// 获取：当前账号所拥有的角色集合
|
||||
StpUtil.getRoleList();
|
||||
|
||||
// 判断：当前账号是否拥有指定角色, 返回true或false
|
||||
StpUtil.hasRole("super-admin");
|
||||
|
||||
@ -115,13 +120,27 @@ StpUtil.checkRoleOr("super-admin", "shop-admin");
|
||||
|
||||
|
||||
### 拦截全局异常
|
||||
有同学要问，鉴权失败，抛出异常，然后呢？要把异常显示给用户看吗？**当然不可以！** <br>
|
||||
有同学要问，鉴权失败，抛出异常，然后呢？要把异常显示给用户看吗？**当然不可以！**
|
||||
|
||||
你可以创建一个全局异常拦截器，统一返回给前端的格式，参考：
|
||||
[码云：GlobalException.java](https://gitee.com/dromara/sa-token/blob/master/sa-token-demo/sa-token-demo-springboot/src/main/java/com/pj/current/GlobalException.java)
|
||||
|
||||
``` java
|
||||
@RestControllerAdvice
|
||||
public class GlobalExceptionHandler {
|
||||
// 全局异常拦截
|
||||
@ExceptionHandler
|
||||
public SaResult handlerException(Exception e) {
|
||||
e.printStackTrace();
|
||||
return SaResult.error(e.getMessage());
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
可参考：[码云：GlobalException.java](https://gitee.com/dromara/sa-token/blob/master/sa-token-demo/sa-token-demo-springboot/src/main/java/com/pj/current/GlobalException.java)
|
||||
|
||||
|
||||
### 权限通配符
|
||||
Sa-Token允许你根据通配符指定泛权限，例如当一个账号拥有`user*`的权限时，`user-add`、`user-delete`、`user-update`都将匹配通过
|
||||
Sa-Token允许你根据通配符指定**泛权限**，例如当一个账号拥有`user*`的权限时，`user-add`、`user-delete`、`user-update`都将匹配通过
|
||||
|
||||
``` java
|
||||
// 当拥有 user* 权限时
|
||||
@ -140,26 +159,26 @@ StpUtil.hasPermission("index.css"); // false
|
||||
StpUtil.hasPermission("index.html"); // false
|
||||
```
|
||||
|
||||
上帝权限：当一个账号拥有 `"*"` 权限时，他可以验证通过任何权限码 (角色认证同理)
|
||||
!> 上帝权限：当一个账号拥有 `"*"` 权限时，他可以验证通过任何权限码 （角色认证同理）
|
||||
|
||||
|
||||
### 如何把权限精确到按钮级？
|
||||
权限精确到按钮级的意思就是指：**权限范围可以控制到页面上的每一个按钮是否显示**
|
||||
权限精确到按钮级的意思就是指：**权限范围可以控制到页面上的每一个按钮是否显示**。
|
||||
|
||||
思路：如此精确的范围控制只依赖后端已经难以完成，此时需要前端进行一定的逻辑判断
|
||||
思路：如此精确的范围控制只依赖后端已经难以完成，此时需要前端进行一定的逻辑判断。
|
||||
|
||||
如果是前后端一体项目，可以参考：[Thymeleaf 标签方言](/plugin/thymeleaf-extend)，如果是前后端分离项目，则：
|
||||
|
||||
1. 在登录时，把当前账号拥有的所有权限码一次性返回给前端
|
||||
2. 前端将权限码集合保存在`localStorage`或其它全局状态管理对象中
|
||||
3. 在需要权限控制的按钮上，使用js进行逻辑判断，例如在`vue`框架中我们可以使用如下写法：
|
||||
1. 在登录时，把当前账号拥有的所有权限码一次性返回给前端。
|
||||
2. 前端将权限码集合保存在`localStorage`或其它全局状态管理对象中。
|
||||
3. 在需要权限控制的按钮上，使用 js 进行逻辑判断，例如在`Vue`框架中我们可以使用如下写法：
|
||||
``` js
|
||||
<button v-if="arr.indexOf('user:delete') > -1">删除按钮</button>
|
||||
```
|
||||
其中：`arr`是当前用户拥有的权限码数组，`user:delete`是显示按钮需要拥有的权限码，`删除按钮`是用户拥有权限码才可以看到的内容
|
||||
其中：`arr`是当前用户拥有的权限码数组，`user:delete`是显示按钮需要拥有的权限码，`删除按钮`是用户拥有权限码才可以看到的内容。
|
||||
|
||||
|
||||
注意：以上写法只为提供一个参考示例，不同框架有不同写法，开发者可根据项目技术栈灵活封装进行调用
|
||||
注意：以上写法只为提供一个参考示例，不同框架有不同写法，大家可根据项目技术栈灵活封装进行调用。
|
||||
|
||||
|
||||
### 前端有了鉴权后端还需要鉴权吗？
|
||||
|
||||
@ -2,23 +2,74 @@
|
||||
---
|
||||
|
||||
|
||||
### 核心思想
|
||||
### 设计思路
|
||||
|
||||
所谓登录认证，说白了就是限制某些API接口必须登录后才能访问（例：查询我的账号资料） <br>
|
||||
那么如何判断一个会话是否登录？框架会在登录成功后给你做个标记，每次登录认证时校验这个标记，有标记者视为已登录，无标记者视为未登录！
|
||||
对于一些登录之后才能访问的接口（例如：查询我的账号资料），我们通常的做法是增加一层接口校验：
|
||||
|
||||
- 如果校验通过，则：正常返回数据。
|
||||
- 如果校验未通过，则：抛出异常，告知其需要先进行登录。
|
||||
|
||||
那么，判断会话是否登录的依据是什么？我们先来简单分析一下登录访问流程：
|
||||
|
||||
1. 用户提交 `name` + `password` 参数，调用登录接口。
|
||||
2. 登录成功，返回这个用户的 Token 会话凭证。
|
||||
3. 用户后续的每次请求，都携带上这个 Token。
|
||||
4. 服务器根据 Token 判断此会话是否登录成功。
|
||||
|
||||
所谓登录认证，指的就是服务器校验账号密码，为用户颁发 Token 会话凭证的过程，这个 Token 也是我们后续通过接口校验的关键所在。
|
||||
|
||||
|
||||
<button class="show-img" img-src="https://oss.dev33.cn/sa-token/doc/g/g3--login-auth.gif">加载动态演示图</button>
|
||||
|
||||
|
||||
### 登录与注销
|
||||
根据以上思路，我们很容易想到以下api：
|
||||
根据以上思路，我们需要一个会话登录的函数：
|
||||
|
||||
``` java
|
||||
// 标记当前会话登录的账号id
|
||||
// 建议的参数类型：long | int | String， 不可以传入复杂类型，如：User、Admin等等
|
||||
// 会话登录：参数填写要登录的账号id，建议的数据类型：long | int | String， 不可以传入复杂类型，如：User、Admin 等等
|
||||
StpUtil.login(Object id);
|
||||
```
|
||||
|
||||
只此一句代码，便可以使会话登录成功，实际上，Sa-Token 在背后做了大量的工作，包括但不限于：
|
||||
|
||||
1. 检查此账号是否已被封禁
|
||||
2. 检查此账号是否之前已有登录
|
||||
3. 为账号生成 `Token` 凭证与 `Session` 会话
|
||||
4. 通知全局侦听器，xx 账号登录成功
|
||||
5. 将 `Token` 注入到请求上下文
|
||||
6. 等等其它工作……
|
||||
|
||||
你暂时不需要完整的了解整个登录过程，你只需要记住关键一点：`Sa-Token 为这个账号创建了一个Token凭证，且通过 Cookie 上下文返回给了前端`。
|
||||
|
||||
所以一般情况下，我们的登录接口代码，会大致类似如下：
|
||||
|
||||
``` java
|
||||
// 会话登录接口
|
||||
@RequestMapping("doLogin")
|
||||
public SaResult doLogin(String name, String pwd) {
|
||||
// 第一步：比对前端提交的账号名称、密码
|
||||
if("zhang".equals(name) && "123456".equals(pwd)) {
|
||||
// 第二步：根据账号id，进行登录
|
||||
StpUtil.login(10001);
|
||||
return SaResult.ok("登录成功");
|
||||
}
|
||||
return SaResult.error("登录失败");
|
||||
}
|
||||
```
|
||||
|
||||
如果你对以上代码阅读没有压力，你可能会注意到略显奇怪的一点：此处仅仅做了会话登录，但并没有主动向前端返回 Token 信息。
|
||||
是因为不需要吗？严格来讲是需要的，只不过 `StpUtil.login(id)` 方法利用了 Cookie 自动注入的特性，省略了你手写返回 Token 的代码。
|
||||
|
||||
如果你对 Cookie 功能还不太了解，也不用担心，我们会在之后的 [ 前后端分离 ] 章节中详细的阐述 Cookie 功能，现在你只需要了解最基本的两点：
|
||||
|
||||
- Cookie 可以从后端控制往浏览器中写入 Token 值。
|
||||
- Cookie 会在每次请求时自动提交 Token 值。
|
||||
|
||||
因此，在 Cookie 功能的加持下，我们可以仅靠 `StpUtil.login(id)` 一句代码就完成登录认证。
|
||||
|
||||
除了登录方法，我们还需要：
|
||||
|
||||
``` java
|
||||
// 当前会话注销登录
|
||||
StpUtil.logout();
|
||||
|
||||
@ -26,12 +77,11 @@ StpUtil.logout();
|
||||
StpUtil.isLogin();
|
||||
|
||||
// 检验当前会话是否已经登录, 如果未登录，则抛出异常：`NotLoginException`
|
||||
StpUtil.checkLogin()
|
||||
StpUtil.checkLogin();
|
||||
```
|
||||
|
||||
##### `NotLoginException`异常对象扩展：
|
||||
1. 通过 `getLoginType()` 方法获取具体是哪个 `StpLogic` 抛出的异常 <br>
|
||||
2. 通过 `getType()` 方法获取具体的场景值，详细参考章节：[未登录场景值](/fun/not-login-scene)
|
||||
异常 `NotLoginException` 代表当前会话暂未登录，可能的原因有很多：
|
||||
前端没有提交 Token、前端提交的 Token 是无效的、前端提交的 Token 已经过期 …… 等等，可参照此篇：[未登录场景值](/fun/not-login-scene)，了解如何获取未登录的场景值。
|
||||
|
||||
|
||||
### 会话查询
|
||||
@ -54,29 +104,32 @@ StpUtil.getLoginId(T defaultValue);
|
||||
```
|
||||
|
||||
|
||||
### 其它API
|
||||
### Token 查询
|
||||
``` java
|
||||
// 获取指定token对应的账号id，如果未登录，则返回 null
|
||||
StpUtil.getLoginIdByToken(String tokenValue);
|
||||
// 获取当前会话的token值
|
||||
StpUtil.getTokenValue();
|
||||
|
||||
// 获取当前`StpLogic`的token名称
|
||||
StpUtil.getTokenName();
|
||||
|
||||
// 获取当前会话的token值
|
||||
StpUtil.getTokenValue();
|
||||
// 获取指定token对应的账号id，如果未登录，则返回 null
|
||||
StpUtil.getLoginIdByToken(String tokenValue);
|
||||
|
||||
// 获取当前会话剩余有效期（单位：s，返回-1代表永久有效）
|
||||
StpUtil.getTokenTimeout();
|
||||
|
||||
// 获取当前会话的token信息参数
|
||||
StpUtil.getTokenInfo();
|
||||
```
|
||||
|
||||
有关`TokenInfo`参数详解，请参考：[TokenInfo参数详解](/fun/token-info)
|
||||
|
||||
|
||||
### 来个小测试，加深一下理解
|
||||
新建 `LoginController`，复制以下代码
|
||||
``` java
|
||||
/**
|
||||
* 登录测试
|
||||
* @author kong
|
||||
*
|
||||
*/
|
||||
@RestController
|
||||
@RequestMapping("/acc/")
|
||||
@ -115,7 +168,5 @@ public class LoginController {
|
||||
}
|
||||
```
|
||||
|
||||
> 有关`TokenInfo`参数详解，请参考：[TokenInfo参数详解](/fun/token-info)
|
||||
|
||||
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user