关于 sa-token-oauth2
面向 Sa-Token 项目的 OAuth 2.0 服务端开发技能，涵盖授权、令牌和 OIDC 配置。适合构建第三方授权及服务间访问流程，需实现 SaOAuth2DataLoader 提供数据。
主要功能
- 01支持四种 OAuth 2.0 授权模式
- 02Scope 权限控制与分级
- 03支持 OIDC 与 OpenId/UnionId
- 04可扩展授权类型和登录页
- 05注解校验 Access-Token
适用场景
- 01为第三方开发者搭建开放平台
- 02为自有应用配置用户授权
- 03配置服务间客户端凭证调用
安装
复制下面的命令，在终端中运行。
npx skills add https:/安装后在 Claude Code 中输入/sa-token-oauth2确认已加载。
包含的文件
除 SKILL.md 外，安装时一起下载的参考资料和脚本。
evaluation-report.htmlagents/openai.yamlexamples/oauth2-demo.mdreferences/oauth2-data-loader.mdoauth2-scope.mdoauth2-server.md详细介绍
来自项目 READMESa-Token OAuth2.0 服务端
基于 sa-token-doc/oauth2/ 全部 17 个文档。基础认证使用 sa-token 技能。
Capability Boundaries
✅ Strong Suits
- 授权码模式(Authorization Code) — 有后端的Web应用，最常用，安全性最高
- 隐式模式(Implicit) — 纯前端应用
- 密码模式(Password) — 信任的客户端（自家APP）
- 客户端凭证模式(Client Credentials) — 服务间调用，无需用户授权
- Scope权限控制 — 自定义Scope+Scope等级划分
- OIDC协议 — OpenID Connect身份层
- OpenId/UnionId — 用户唯一标识生成与管理
- 自定义grant_type — 扩展授权类型
- 自定义登录/授权页 — 定制化前端界面
- 注解校验Access-Token — @SaCheckAccessToken、@SaCheckClientToken
⚠️ Requirements
- 需要JDK 8+环境
- OAuth2-Server需要可被Client访问的网络
- 需实现 SaOAuth2DataLoader 接口提供数据
❌ Out of Scope
- 基础登录/权限认证 → sa-token
- SSO单点登录 → sa-token-sso
- 微服务鉴权 → sa-token-micro
四种授权模式
| 模式 | 适用场景 | 说明 |
|---|---|---|
| 授权码(Authorization Code) | 有后端的Web应用 | 最常用，安全性最高 |
| 隐式(Implicit) | 纯前端应用 | 已不推荐使用 |
| 密码(Password) | 信任的客户端 | 自家APP使用 |
| 客户端凭证(Client Credentials) | 服务间调用 | 无需用户授权 |
什么时候用哪种模式
- 开发开放平台，给第三方开发者使用 → 授权码模式，标准OAuth2流程
- 自己的前后端分离应用 → 密码模式，简单直接
- 微服务之间调用API → 客户端凭证模式，无需用户参与
- 纯前端无后端应用（已不推荐） → 隐式模式
工作流
Step 1. 引入依赖 — 添加 sa-token-oauth2 依赖
Step 2. 实现DataLoader — SaOAuth2DataLoaderImpl 加载客户端和Scope数据
Step 3. 配置Server端点 — 注册 authorize/token/validate/refresh 接口
Step 4. 配置OAuth2参数 — 设置Token有效期、授权模式等
Step 5. 测试授权流程 — 使用授权码模式验证端到端流程
Step 6. 上线前安全加固 — 开启域名校验、配置回调白名单
参考文档
| 主题 | 文件 | 来源 |
|---|---|---|
| Server搭建+DataLoader | references/oauth2-server.md | oauth2-server、oauth2-apidoc |
| DataLoader+域名校验+自定义 | references/oauth2-data-loader.md | data-loader、check-domain |
| Scope权限自定义与分级 | references/oauth2-scope.md | custom-scope、scope-level |
FAQ
Q: OAuth2和SSO有什么区别？ A: OAuth2解决授权问题（第三方应用访问用户数据），SSO解决认证问题（统一登录）。需要第三方授权选OAuth2，仅需统一登录选SSO。也可两者结合使用。
Q: 四种授权模式选哪种？ A: 有后端的Web应用选授权码模式（最安全）。自家APP选密码模式。服务间调用选客户端凭证模式。隐式模式已不推荐。
Q: 如何自定义Scope？
A: 实现 SaOAuth2DataLoader.getScope() 方法，返回 SaScopeObject 对象，可设置scope名称、描述、是否默认选中。
Q: 如何保证OAuth2服务安全？
A: 1) 配置 is-check-domain: true 校验回调域名；2) 配置 allow-url 白名单；3) 生产环境关闭 isAutoMode；4) 使用HTTPS。
Q: 支持刷新Token吗？
A: 支持。refresh-token-timeout 默认30天，调用 /oauth2/refresh 接口刷新。
Q: 前后端分离怎么对接OAuth2？
A: 前端通过URL参数接收code，调用后端 /oauth2/token 接口换取AccessToken，保存到本地存储。
Gotchas
- 必须实现 SaOAuth2DataLoader — Server启动后不会自动加载数据，需要自行实现接口
- allow-url 必须配置 — 不配置回调URL白名单会导致授权失败
- 生产环境关闭 isAutoMode — 自动确认授权模式仅用于开发调试
- AccessToken有效期默认2小时 — 可通过
access-token-timeout配置 - Scope需要在 DataLoader 和 ClientModel 两端配置 — 只配一端不会生效
- 隐式模式不推荐生产使用 — AccessToken直接暴露在URL中，有安全风险
- OIDC需要额外配置 iss 和 idTokenTimeout — 不是默认开启就能用
- 域名校验不通过会返回错误 — 配置
allow-domains时要包含所有合法客户端
Data Privacy
本技能不收集、存储或传输任何用户数据。所有代码示例仅供本地开发参考。