Sa-TokenSa-Token
主题
首页文档博客
视频
乐之者java(登录认证/权限管理/apiKey等)抓蛙师(23集)朱老师的小课堂(7集)王清江唷 SSO篇(29集)fox说技术(7集)架构驿站(11集)王清江唷(99集)筑梦信仰-joy(20集)达达-Java(26集)晒太阳的盐(22集)[ + 课程提交 ]
案例
Gitee - Awesome-Sa-TokenGitHub - Awesome-Sa-TokenAtomGit - Awesome-Sa-Token
加群需求提交赞助🔥 SSO/OAuth2 商业版
安全推荐
开发者安全 ChecklistAPI 安全 Checklist腾讯代码安全指南Web 安全学习笔记OWASP Cheat Sheet SeriesPayloadsAllTheThings
相关资源
更新日志常见报错推荐公众号在线考试在线提问问卷调查
  • 开始

    • 框架介绍
    • 在 SpringBoot 环境集成
    • 在 WebFlux 环境集成
    • 在 Solon 环境集成
    • 其它环境集成示例
    • 源码运行指南
    • Sa-Token 集成示例大全下载
  • 基础

    • 登录认证
    • 权限认证
    • 踢人下线
    • 注解鉴权
    • 路由拦截鉴权
    • Session会话
    • 框架配置
  • 深入

    • 集成 Redis
    • 前后端分离
    • 自定义 Token 风格
    • Token 提交前缀
    • 同端互斥登录
    • 记住我模式
    • 登录参数 & 注销参数
    • 二级认证
    • 模拟他人 & 身份切换
    • 账号封禁
    • 密码加密
    • 会话查询
    • Http Basic/Digest 认证
    • 全局侦听器
    • 全局过滤器
    • 多账号认证
  • 单点登录

    • 单点登录简述
    • 搭建统一认证中心:SSO-Server
    • SSO-Server 认证中心开放 API 接口
    • SSO模式一 共享Cookie同步会话
    • SSO模式二 URL重定向传播会话
    • SSO模式三 Http请求获取会话
    • 配置域名校验
    • 定制化登录页面
    • 自定义API路由
    • 平台中心跳转模式
    • 匿名 client 接入
    • 单点注销
    • 前后端分离下的整合方案
    • 消息推送机制
    • 用户数据同步 / 迁移
    • NoSdk、ReSdk 模式与非 java 项目
    • SSO 代码 API 参考
    • 常见问题总结
    • Sa-Pro:单点登录商业版
  • OAuth2.0

    • OAuth2.0简述
    • OAuth2-Server搭建
    • OAuth2-Server端开放 API 接口
    • 自定义数据加载器
    • 配置 client 域名校验
    • 自定义 Scope 权限及处理器
    • 为 Scope 划分等级
    • 自定义 grant_type
    • 定制化登录页面与授权页面
    • 自定义 API 路由
    • OAuth2-Server端前后台分离
    • OpenId 与 UnionId
    • 开启 OIDC 协议
    • 使用注解校验 Access-Token
    • OAuth2-与登录会话实现数据互通
    • OAuth2 代码 API 参考
    • 常见问题总结
    • Sa-Max:统一认证商业版
  • 微服务

    • 分布式Session会话
    • 网关统一鉴权
    • 内部服务外网隔离
    • 依赖引入说明
  • 插件

    • AOP注解鉴权
    • 临时 Token 认证
    • Quick-Login快速登录插件
    • Alone独立Redis插件
    • Alone独立Redisson插件
    • 缓存层扩展
    • JSON 序列化扩展
    • 序列化插件扩展包
    • HTTP 请求扩展
    • 和 Thymeleaf 集成
    • 和 Freemarker 集成
    • 注解鉴权 SpEL 表达式
    • 和 jwt 集成
    • 和 Dubbo 集成
    • 和 gRPC 集成
    • API 接口参数签名
    • API Key 接口调用秘钥
    • Sa-Token 插件开发指南
    • 自定义 SaTokenContext 指南
  • API手册

    • StpUtil-鉴权工具类
    • SaSession-会话对象
    • SaTokenDao-数据持久接口
    • SaStrategy-全局策略
    • 全局类、方法
  • 框架设计

    • 仓库目录
    • 数据结构
  • 其它

    • 更新日志
    • 框架生态
    • 框架博客
    • 推荐公众号
    • 加入讨论群
    • Sa-Token 内容合作群
    • 赞助 Sa-Token
    • 需求提交
    • 问卷调查
  • 附录

    • 常见问题排查
    • 框架名词解释
    • Sa-Token功能结构图
    • 全局 Log 输出
    • 异步 & Mock 上下文
    • 未登录场景值详解
    • Token有效期详解
    • Session模型详解
    • 数据读写三大作用域
    • TokenInfo参数详解
    • 异常细分状态码
    • 自定义注解
    • 防火墙
    • 参考:把权限放在缓存里
    • 参考:把路由拦截鉴权动态化
    • 解决反向代理 uri 丢失的问题
    • 解决跨域问题
    • 技术选型:SSO 与 OAuth2 对比
    • 集成 MongoDB 参考一
    • 集成 MongoDB 参考二
    • 从 Shiro、SpringSecurity、JWT 迁移
    • issue 提问模板
    • 为Sa-Token贡献代码
    • Sa-Token开源大事记
    • 团队成员
    • Sa-Token框架掌握度--在线考试







----- 到底线了 -----

×

一个项目搞定:同域、跨域、共享Redis、跨Redis、前后端一体、前后端分离、纯 js、vue2、vue3、非 Sa-Token 项目、非 java 项目等架构下的 SSO 认证需求。

一次购买,永久授权。全源码交付,不含密 Jar。提供售后技术支持。

异常细分状态码 ​


获取异常细分状态码 ​

Sa-Token 中的基础异常类是 SaTokenException,在此基础上,又针对一些特定场景划分出诸如 NotLoginException、NotPermissionException 等。

但是框架中异常抛出点远远多于异常种类的划分,比如在 SSO 插件中,[ redirect 重定向地址无效 ] 和 [ ticket 参数值无效 ] 都会导致 SSO 授权的失败, 但是它们抛出的异常都是 SaSsoException,如果你需要对这两种异常情形做出不同的处理,仅仅判断异常的 ClassType 显然不够。

为了解决上述需求,Sa-Token 对每个异常抛出点都会指定一个特定的 code 值,就像这样:

java
if(SaFoxUtil.isUrl(url) == false) {
	throw new SaSsoException("无效redirect:" + url).setCode(SaSsoErrorCode.CODE_30001);	
}
1
2
3

就像是打上一个特定的标记,不同异常情形标记的 code 码值也会不同,这就为你精细化异常处理提供了前提。

要在捕获异常时获取这个 code 码也非常简单:

java
@RestControllerAdvice
public class GlobalExceptionHandler {
	@ExceptionHandler(SaTokenException.class)
	public SaResult handlerSaTokenException(SaTokenException e) {
		
		// 根据不同异常细分状态码返回不同的提示 
		if(e.getCode() == 30001) {
			return SaResult.error("redirect 重定向 url 是一个无效地址");
		}
		if(e.getCode() == 30002) {
			return SaResult.error("redirect 重定向 url 不在 allowUrl 允许的范围内");
		}
		if(e.getCode() == 30004) {
			return SaResult.error("提供的 ticket 是无效的");
		}
		// 更多 code 码判断 ... 
		
		// 默认的提示 
		return SaResult.error("服务器繁忙,请稍后重试...");
	}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

SaToken 中的所有异常都是继承于 SaTokenException 的,也就是说,所有异常你都可以通过 e.getCode() 的方式获取对应的异常细分状态码。

异常细分状态码-参照表 ​

sa-token-code 核心包 ​

code码值含义
-1代表这个异常在抛出时未指定异常细分状态码
10001未能获取有效的上下文处理器
10002未能获取有效的上下文
10003JSON 转换器未实现
10011未能从全局 StpLogic 集合中找到对应 type 的 StpLogic
10021指定的配置文件加载失败
10022配置文件属性无法正常读取
10031重置的侦听器集合不可以为空
10032注册的侦听器不可以为空
10301提供的 Same-Token 是无效的
10311表示未能通过 Http Basic 认证校验
10321提供的 HttpMethod 是无效的
11001未能读取到有效Token
11002登录时的账号id值为空
11003更改 Token 指向的 账号Id 时,账号Id值为空
11011未能读取到有效Token
11012Token无效
11013Token已过期
11014Token已被顶下线
11015Token已被踢下线
11016Token已被冻结
11031在未集成 sa-token-jwt 插件时调用 getExtra() 抛出异常
11041缺少指定的角色
11051缺少指定的权限
11061当前账号未通过服务封禁校验
11062提供要解禁的账号无效
11063提供要解禁的服务无效
11064提供要解禁的等级无效
11071二级认证校验未通过
12001请求中缺少指定的参数
12002构建 Cookie 时缺少 name 参数
12003构建 Cookie 时缺少 value 参数
12101Base64 编码异常
12102Base64 解码异常
12103URL 编码异常
12104URL 解码异常
12111md5 加密异常
12112sha1 加密异常
12113sha256 加密异常
12114AES 加密异常
12115AES 解密异常
12116RSA 公钥加密异常
12117RSA 私钥加密异常
12118RSA 公钥解密异常
12119RSA 私钥解密异常
12201参与参数签名的秘钥不可为空
12202给定的签名无效
12203timestamp 超出允许的范围

sa-token-servlet ​

code码值含义
20001转发失败
20002重定向失败

sa-token-spring-boot-starter ​

code码值含义
20101企图在非 Web 上下文获取 Request、Response 等对象
20103对象转 JSON 字符串失败
20104JSON 字符串转 Map 失败
20105默认的 Filter 异常处理函数

sa-token-reactor-spring-boot-starter ​

code码值含义
20203对象转 JSON 字符串失败
20204JSON 字符串转 Map 失败
20205默认的 Filter 异常处理函数

sa-token-solon-plugin ​

code码值含义
20301默认的拦截器异常处理函数
20302默认的 Filter 异常处理函数

sa-token-sso 单点登录相关: ​

code码值含义
30001redirect 重定向 url 是一个无效地址
30002redirect 重定向 url 不在 allowUrl 允许的范围内
30003接口调用方提供的 secretkey 秘钥无效
30004提供的 ticket 是无效的
30005在模式三下,sso-client 调用 sso-server 端 校验ticket接口 时,得到的响应是校验失败
30006在模式三下,sso-client 调用 sso-server 端 单点注销接口 时,得到的响应是注销失败
30007http 请求调用 提供的 timestamp 与当前时间的差距超出允许的范围
30008http 请求调用 提供的 sign 无效
30009本地系统没有配置 secretkey 字段
30010本地系统没有配置 http 请求处理器(参考 HTTP 请求扩展)
30011该 ticket 不属于当前 client

sa-token-oauth2 相关: ​

code码值含义
30101client_id 不可为空
30102scope 不可为空
30103redirect_uri 不可为空
30104LoginId 不可为空
30105无效 client_id
30106无效 access_token
30107无效 client_token
30108Access-Token 不具备指定的 Scope
30109Client-Token 不具备指定的 Scope
30110无效 code 码
30111无效 Refresh-Token
30112请求的 Scope 暂未签约
30113无效 redirect_url
30114非法 redirect_url
30115无效 client_secret
30120redirect_uri 不一致
30122client_id 不一致
30125无效 response_type
30126无效 grant_type
30127无效 state
30141系统暂未开放的授权模式
30142应用暂未开放的授权模式
30151无效的请求 Method
30191其它异常

sa-token-jwt 插件相关: ​

code码值含义
30201对 jwt 字符串解析失败
30202此 jwt 的签名无效
30203此 jwt 的 loginType 字段不符合预期
30204此 jwt 已超时
30205没有配置jwt秘钥
30206登录时提供的账号id为空
30207extraData 包含 jwt 保留字段

sa-token-temp-jwt 插件相关: ​

code码值含义
30301jwt 模式没有提供秘钥
30302jwt 模式不可以删除 Token
30303Token已超时

注意

部分插件因异常抛出点较少,暂未做状态码细分处理









发现错误? 您可以在 Gitee 或 GitHub 或 AtomGit 帮助我们完善此页文档! 或 加入讨论群 交流反馈。

我们坚信,即使再复杂的技术,也可以用清晰、干练、易懂的文字描述出它的具体细节,如果你在阅读文档时有难以理解的章节,那一定是我们还没有优化好它, 请向我们 反馈 你的困惑之处,我们将持续优化文档。


鲁ICP备18046274号-5|公安备案鲁公网安备37011202002956号
目录

本页无章节

推荐关闭
Sa-Token 商业版:轻松搭建 SSO 单点登录、OAuth2.0 统一认证、API Key 认证。全源码交付、可二开。
加入 Sa-Token 框架交流群

离线版文档历史所有版本文档Demo 示例大全下载

如果 Sa-Token 帮助到了你,希望你可以向同事、朋友推荐了解本框架,这对我们非常重要,感谢支持!

加油,工程师!