mirror of
https://gitee.com/dromara/sa-token.git
synced 2025-04-05 17:37:53 +08:00
完善文档
This commit is contained in:
click33
parent
4a9a5e4580
commit
7419846eb3
@ -29,8 +29,7 @@
|
||||
- [会话治理](/up/search-session)
|
||||
- [全局侦听器](/up/global-listener)
|
||||
- [全局过滤器](/up/global-filter)
|
||||
- [多账户认证](/up/many-account)
|
||||
<!-- - [微服务](/senior/dcs) -->
|
||||
- [多账号认证](/up/many-account)
|
||||
|
||||
- **单点登录**
|
||||
- [单点登录简述](/sso/readme)
|
||||
|
||||
@ -31,6 +31,9 @@ SaOAuth2Util.refreshAccessToken(refreshToken);
|
||||
// 构建 Client-Token
|
||||
SaOAuth2Util.generateClientToken(clientId, scope);
|
||||
|
||||
// 校验 Client-Token 是否含有指定 Scope
|
||||
SaOAuth2Util.checkClientTokenScope(clientToken, scopes);
|
||||
|
||||
// 回收 Access-Token
|
||||
SaOAuth2Util.revokeAccessToken(accessToken);
|
||||
|
||||
|
||||
@ -1,11 +1,11 @@
|
||||
# 多账户认证
|
||||
# 多账号认证
|
||||
---
|
||||
|
||||
### 1、需求场景
|
||||
有的时候，我们会在一个项目中设计两套账号体系，比如一个电商系统的 `user表` 和 `admin表`，
|
||||
在这种场景下，如果两套账号我们都使用 `StpUtil` 类的API进行登录鉴权，那么势必会发生逻辑冲突。
|
||||
|
||||
在Sa-Token中，这个问题的模型叫做：多账户体系认证。
|
||||
在Sa-Token中，这个问题的模型叫做：多账号体系认证。
|
||||
|
||||
要解决这个问题，我们必须有一个合理的机制将这两套账号的授权给区分开，让它们互不干扰才行。
|
||||
|
||||
|
||||
@ -82,13 +82,13 @@ PS：两者的区别在于：**`模式1会覆盖yml中的配置，模式2会与y
|
||||
| activityTimeout | long | -1 | Token 临时有效期 （指定时间内无操作就视为token过期） 单位: 秒, 默认-1 代表不限制 （例如可以设置为1800代表30分钟内无操作就过期） [参考：token有效期详解](/fun/token-timeout) |
|
||||
| isConcurrent | Boolean | true | 是否允许同一账号并发登录 （为 true 时允许一起登录，为 false 时新登录挤掉旧登录） |
|
||||
| isShare | Boolean | true | 在多人登录同一账号时，是否共用一个token （为 true 时所有登录共用一个 token, 为 false 时每次登录新建一个 token） |
|
||||
| maxLoginCount | int | 12 | 同一账号最大登录数量，-1代表不限 （只有在 `isConcurrent=true`, `isShare=false` 时此配置才有效），[详解](/use/config?id=maxlogincount) |
|
||||
| maxLoginCount | int | 12 | 同一账号最大登录数量，-1代表不限 （只有在 `isConcurrent=true`, `isShare=false` 时此配置才有效），[详解](/use/config?id=配置项详解：maxlogincount) |
|
||||
| isReadBody | Boolean | true | 是否尝试从 请求体 里读取 Token |
|
||||
| isReadHead | Boolean | true | 是否尝试从 header 里读取 Token |
|
||||
| isReadCookie | Boolean | true | 是否尝试从 cookie 里读取 Token，此值为 false 后，`StpUtil.login(id)` 登录时也不会再往前端注入Cookie |
|
||||
| tokenStyle | String | uuid | token风格， [参考：自定义Token风格](/up/token-style) |
|
||||
| dataRefreshPeriod | int | 30 | 默认数据持久组件实现类中，每次清理过期数据间隔的时间 （单位: 秒） ，默认值30秒，设置为-1代表不启动定时清理 |
|
||||
| tokenSessionCheckLogin | Boolean | true | 获取 `Token-Session` 时是否必须登录 （如果配置为true，会在每次获取 `Token-Session` 时校验是否登录），[详解](/use/config?id=tokenSessionCheckLogin) |
|
||||
| tokenSessionCheckLogin | Boolean | true | 获取 `Token-Session` 时是否必须登录 （如果配置为true，会在每次获取 `Token-Session` 时校验是否登录），[详解](/use/config?id=配置项详解：tokenSessionCheckLogin) |
|
||||
| autoRenew | Boolean | true | 是否打开自动续签 （如果此值为true, 框架会在每次直接或间接调用 `getLoginId()` 时进行一次过期检查与续签操作），[参考：token有效期详解](/fun/token-timeout) |
|
||||
| tokenPrefix | String | null | token前缀，例如填写 `Bearer` 实际传参 `satoken: Bearer xxxx-xxxx-xxxx-xxxx` [参考：自定义Token前缀](/up/token-prefix) |
|
||||
| isPrint | Boolean | true | 是否在初始化配置时打印版本字符画 |
|
||||
@ -121,7 +121,7 @@ Server 端：
|
||||
| ticketTimeout | long | 300 | ticket 有效期 （单位: 秒） |
|
||||
| allowUrl | String | * | 所有允许的授权回调地址，多个用逗号隔开（不在此列表中的URL将禁止下放ticket），参考：[SSO整合：配置域名校验](/sso/sso-check-domain) |
|
||||
| isSlo | Boolean | false | 是否打开单点注销功能 |
|
||||
| isHttp | Boolean | false | 是否打开模式三（此值为 true 时将使用 http 请求：校验ticket值、单点注销、获取userinfo），参考：[详解](/use/config?id=isHttp) |
|
||||
| isHttp | Boolean | false | 是否打开模式三（此值为 true 时将使用 http 请求：校验 ticket 值、单点注销、获取 userinfo），参考：[详解](/use/config?id=配置项详解：isHttp) |
|
||||
| secretkey | String | null | 调用秘钥 （用于SSO模式三单点注销的接口通信身份校验） |
|
||||
|
||||
|
||||
@ -131,12 +131,14 @@ Client 端：
|
||||
| :-------- | :-------- | :-------- | :-------- |
|
||||
| authUrl | String | null | 配置 Server 端单点登录授权地址 |
|
||||
| isSlo | Boolean | false | 是否打开单点注销功能 |
|
||||
| isHttp | Boolean | false | 是否打开模式三（此值为 true 时将使用 http 请求：校验ticket值、单点注销、获取userinfo），参考：[详解](/use/config?id=isHttp) |
|
||||
| checkTicketUrl| String | null | 配置 Server 端的 ticket 校验地址 |
|
||||
| userinfoUrl | String | null | 配置 Server 端查询 userinfo 地址 |
|
||||
| isHttp | Boolean | false | 是否打开模式三（此值为 true 时将使用 http 请求：校验 ticket 值、单点注销、获取 userinfo），参考：[详解](/use/config?id=配置项详解：isHttp) |
|
||||
| checkTicketUrl| String | null | 配置 Server 端的 `ticket` 校验地址 |
|
||||
| userinfoUrl | String | null | 配置 Server 端查询 `userinfo` 地址 |
|
||||
| sloUrl | String | null | 配置 Server 端单点注销地址 |
|
||||
| ssoLogoutCall | String | null | 配置当前 Client 端的单点注销回调URL （为空时自动获取） |
|
||||
| secretkey | String | null | 接口调用秘钥 （用于SSO模式三单点注销的接口通信身份校验） |
|
||||
| serverUrl | String | null | 配置 Server 端主机总地址，拼接在 `authUrl`、`checkTicketUrl`、`userinfoUrl`、`sloUrl` 属性前面，用以简化各种 url 配置，[详解](/use/config?id=配置项详解：serverUrl) |
|
||||
|
||||
|
||||
配置示例：
|
||||
``` yml
|
||||
@ -188,7 +190,7 @@ sa-token:
|
||||
| isImplicit | Boolean | false | 单独配置此 Client 是否打开模式：隐藏式（`Implicit`） |
|
||||
| isPassword | Boolean | false | 单独配置此 Client 是否打开模式：密码式（`Password`） |
|
||||
| isClient | Boolean | false | 单独配置此 Client 是否打开模式：凭证式（`Client Credentials`） |
|
||||
| isAutoMode | Boolean | true | 是否自动判断此 Client 开放的授权模式。 参考：[详解](/use/config?id=isAutoMode) |
|
||||
| isAutoMode | Boolean | true | 是否自动判断此 Client 开放的授权模式。 参考：[详解](/use/config?id=配置项详解：isAutoMode) |
|
||||
| isNewRefresh | Boolean | 取全局配置 | 单独配置此Client：是否在每次 `Refresh-Token` 刷新 `Access-Token` 时，产生一个新的 Refresh-Token [ 默认取全局配置 ] |
|
||||
| accessTokenTimeout | long | 取全局配置 | 单独配置此Client：`Access-Token` 保存的时间（单位：秒） [默认取全局配置] |
|
||||
| refreshTokenTimeout | long | 取全局配置 | 单独配置此Client：`Refresh-Token` 保存的时间（单位：秒） [默认取全局配置] |
|
||||
@ -201,7 +203,7 @@ sa-token:
|
||||
|
||||
对部分配置项做一下详解
|
||||
|
||||
#### maxLoginCount
|
||||
#### 配置项详解：maxLoginCount
|
||||
|
||||
配置含义：同一账号最大登录数量。
|
||||
|
||||
@ -214,7 +216,7 @@ sa-token:
|
||||
假设一个账号的登录数量超过 `maxLoginCount` 后，将会主动注销第一个登录的会话（先进先出），以此保证队列中的有效会话数量始终 `<= maxLoginCount` 值。
|
||||
|
||||
|
||||
#### tokenSessionCheckLogin
|
||||
#### 配置项详解：tokenSessionCheckLogin
|
||||
配置含义：获取 `Token-Session` 时是否必须登录 （如果配置为true，会在每次获取 `Token-Session` 时校验是否登录）。
|
||||
|
||||
在调用 `StpUtil.login(id)` 登录后，
|
||||
@ -236,7 +238,7 @@ sa-token:
|
||||
但是 —— 有的场景下我们又确实需要在登录之前就使用 Token-Session 对象，这时候就把配置项 `tokenSessionCheckLogin` 值改为 `false` 即可。
|
||||
|
||||
|
||||
#### isAutoMode
|
||||
#### 配置项详解：isAutoMode
|
||||
|
||||
配置含义：是否自动判断此 Client 开放的授权模式。
|
||||
|
||||
@ -244,7 +246,7 @@ sa-token:
|
||||
- 此值为 false 时：四种模式（`isCode、isImplicit、isPassword、isClient`）是否生效，依靠局部配置+全局配置（两个都为 true 时才打开）
|
||||
|
||||
|
||||
#### isHttp
|
||||
#### 配置项详解：isHttp
|
||||
|
||||
配置含义：是否打开单点登录模式三。
|
||||
|
||||
@ -252,3 +254,48 @@ sa-token:
|
||||
- 此配置项为 true 时，代表使用SSO模式三：使用 Http 请求校验 ticket 值、使用 Http 请求做到单点注销、使用 Http 请求同步 Userinfo 数据。
|
||||
|
||||
|
||||
#### 配置项详解：serverUrl
|
||||
|
||||
配置含义：配置 Server 端主机总地址，拼接在 authUrl、checkTicketUrl、userinfoUrl、sloUrl 属性前面，用以简化各种 url 配置。
|
||||
|
||||
在开发 SSO 模块时，我们需要在 sso-client 配置认证中心的各种地址，特别是在模式三下，一般代码会变成这样：
|
||||
|
||||
``` java
|
||||
sa-token:
|
||||
sso:
|
||||
# SSO-Server端 统一认证地址
|
||||
auth-url: http://sa-sso-server.com:9000/sso/auth
|
||||
# 使用Http请求校验ticket
|
||||
is-http: true
|
||||
# SSO-Server端 ticket校验地址
|
||||
check-ticket-url: http://sa-sso-server.com:9000/sso/checkTicket
|
||||
# 单点注销地址
|
||||
slo-url: http://sa-sso-server.com:9000/sso/logout
|
||||
# 接口调用秘钥
|
||||
secretkey: kQwIOrYvnXmSDkwEiFngrKidMcdrgKor
|
||||
# SSO-Server端 查询userinfo地址
|
||||
userinfo-url: http://sa-sso-server.com:9000/sso/userinfo
|
||||
```
|
||||
|
||||
一堆 xxx-url 配置比较繁琐，且含有大量重复字符，现在我们可以将其简化为：
|
||||
``` java
|
||||
sa-token:
|
||||
sso:
|
||||
server-url: http://sa-sso-server.com:9000
|
||||
is-http: true
|
||||
secretkey: kQwIOrYvnXmSDkwEiFngrKidMcdrgKor
|
||||
```
|
||||
|
||||
只要你配置了 `server-url` 地址，Sa-Token 就可以自动拼接出其它四个地址：
|
||||
|
||||
**例1，使用 server-url 简化：**
|
||||
- 你配置的 server-url 值是：`http://sa-sso-server.com:9000`。
|
||||
- 框架拼接出的 auth-url 值就是：`http://sa-sso-server.com:9000/sso/auth`，其它三个 url 配置项同理。
|
||||
|
||||
**例2，使用 server-url + auth-url 简化：**
|
||||
- 你配置的 server-url 值是：`http://sa-sso-server.com:9000`，auth-url 是：`/sso/auth2`。
|
||||
- 框架拼接出的 auth-url 值就是：`http://sa-sso-server.com:9000/sso/auth2`，其它三个 url 配置项同理。
|
||||
|
||||
**例3，auth-url 地址以 http 字符开头：**
|
||||
- 你配置的 server-url 值是：`http://sa-sso-server.com:9000`，auth-url 是：`http://my-site.com/sso/auth2`。
|
||||
- 此时框架只以 auth-url 值为准，得到的 auth-url 值是：`http://my-site.com/sso/auth2`，其它三个 url 配置项同理。
|
||||
|
||||
@ -63,7 +63,7 @@ public SaResult doLogin(String name, String pwd) {
|
||||
如果你对 Cookie 功能还不太了解，也不用担心，我们会在之后的 [ 前后端分离 ] 章节中详细的阐述 Cookie 功能，现在你只需要了解最基本的两点：
|
||||
|
||||
- Cookie 可以从后端控制往浏览器中写入 Token 值。
|
||||
- Cookie 会在每次请求时自动提交 Token 值。
|
||||
- Cookie 会在前端每次发起请求时自动提交 Token 值。
|
||||
|
||||
因此，在 Cookie 功能的加持下，我们可以仅靠 `StpUtil.login(id)` 一句代码就完成登录认证。
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user