Back to Details

sa-token-oauth2

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Sa-Token OAuth2.0 服务端

Sa-Token OAuth2.0 Server

基于 
sa-token-doc/oauth2/
全部 17 个文档。基础认证使用 
sa-token
技能。
Based on all 17 documents in 
sa-token-doc/oauth2/
. Basic authentication uses the 
sa-token
skill.

Capability Boundaries

Capability Boundaries

✅ Strong Suits

✅ Core Capabilities

  1. 授权码模式(Authorization Code) — 有后端的Web应用，最常用，安全性最高
  2. 隐式模式(Implicit) — 纯前端应用
  3. 密码模式(Password) — 信任的客户端（自家APP）
  4. 客户端凭证模式(Client Credentials) — 服务间调用，无需用户授权
  5. Scope权限控制 — 自定义Scope+Scope等级划分
  6. OIDC协议 — OpenID Connect身份层
  7. OpenId/UnionId — 用户唯一标识生成与管理
  8. 自定义grant_type — 扩展授权类型
  9. 自定义登录/授权页 — 定制化前端界面
  10. 注解校验Access-Token — @SaCheckAccessToken、@SaCheckClientToken
  1. Authorization Code — Web applications with a backend; the most commonly used and safest mode
  2. Implicit — Pure front-end applications
  3. Password — Trusted clients, such as first-party apps
  4. Client Credentials — Service-to-service calls without user authorization
  5. Scope Permission Control — Custom Scope definitions and tiered Scope levels
  6. OIDC Protocol — An OpenID Connect identity layer
  7. OpenId/UnionId — Generation and management of unique user identifiers
  8. Custom grant_type — Extension of grant types
  9. Custom Login/Authorization Pages — Customized front-end interfaces
  10. Annotation-Based Access-Token Validation — @SaCheckAccessToken and @SaCheckClientToken

⚠️ Requirements

⚠️ Requirements

  1. 需要JDK 8+环境
  2. OAuth2-Server需要可被Client访问的网络
  3. 需实现 SaOAuth2DataLoader 接口提供数据
  1. A JDK 8+ environment is required
  2. The OAuth2-Server must be accessible over the network by Clients
  3. The SaOAuth2DataLoader interface must be implemented to provide data

❌ Out of Scope

❌ Out of Scope

  1. 基础登录/权限认证 → sa-token
  2. SSO单点登录 → sa-token-sso
  3. 微服务鉴权 → sa-token-micro
  1. Basic login/permission authentication → sa-token
  2. SSO authentication → sa-token-sso
  3. Microservice authentication → sa-token-micro

四种授权模式

Four Grant Modes

模式适用场景说明
授权码(Authorization Code)有后端的Web应用最常用，安全性最高
隐式(Implicit)纯前端应用已不推荐使用
密码(Password)信任的客户端自家APP使用
客户端凭证(Client Credentials)服务间调用无需用户授权
ModeUse CaseDescription
Authorization CodeWeb applications with a backendMost commonly used and safest
ImplicitPure front-end applicationsNo longer recommended
PasswordTrusted clientsFor first-party apps
Client CredentialsService-to-service callsNo user authorization required

什么时候用哪种模式

Choosing a Grant Mode

  • 开发开放平台，给第三方开发者使用 → 授权码模式，标准OAuth2流程
  • 自己的前后端分离应用 → 密码模式，简单直接
  • 微服务之间调用API → 客户端凭证模式，无需用户参与
  • 纯前端无后端应用（已不推荐） → 隐式模式
  • Developing an open platform for third-party developers → Authorization Code mode, following the standard OAuth2 flow
  • Your own separated front-end and back-end application → Password mode, which is simple and direct
  • Calling APIs between microservices → Client Credentials mode, with no user participation required
  • Pure front-end application without a backend (no longer recommended) → Implicit mode

工作流

Workflow

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. 上线前安全加固 — 开启域名校验、配置回调白名单
Step 1. Add the dependency — Add the 
sa-token-oauth2
dependency Step 2. Implement the DataLoader — Use 
SaOAuth2DataLoaderImpl
to load client and Scope data Step 3. Configure server endpoints — Register the authorize/token/validate/refresh endpoints Step 4. Configure OAuth2 parameters — Set token validity periods, grant modes, and other options Step 5. Test the authorization flow — Use Authorization Code mode to verify the end-to-end flow Step 6. Harden security before deployment — Enable domain validation and configure a callback allowlist

参考文档

Reference Documentation

主题文件来源
Server搭建+DataLoaderreferences/oauth2-server.mdoauth2-server、oauth2-apidoc
DataLoader+域名校验+自定义references/oauth2-data-loader.mddata-loader、check-domain
Scope权限自定义与分级references/oauth2-scope.mdcustom-scope、scope-level
TopicFileSource
Server setup + DataLoaderreferences/oauth2-server.mdoauth2-server, oauth2-apidoc
DataLoader + domain validation + customizationreferences/oauth2-data-loader.mddata-loader, check-domain
Custom Scope permissions and levelsreferences/oauth2-scope.mdcustom-scope, scope-level

FAQ

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，保存到本地存储。
Q: What is the difference between OAuth2 and SSO? A: OAuth2 solves authorization issues by allowing third-party applications to access user data, while SSO solves authentication issues through unified login. Choose OAuth2 when third-party authorization is required, and SSO when only unified login is needed. They can also be used together.
Q: Which of the four grant modes should I use? A: Use Authorization Code mode for web applications with a backend because it is the safest. Use Password mode for your own app. Use Client Credentials mode for service-to-service calls. Implicit mode is no longer recommended.
Q: How do I customize Scope? A: Implement the 
SaOAuth2DataLoader.getScope()
method and return a 
SaScopeObject
. You can configure the Scope name, description, and whether it is selected by default.
Q: How do I secure the OAuth2 service? A: 1) Set 
is-check-domain: true
to validate callback domains; 2) configure an 
allow-url
allowlist; 3) disable 
isAutoMode
in production; 4) use HTTPS.
Q: Is token refresh supported? A: Yes. 
refresh-token-timeout
defaults to 30 days. Call the 
/oauth2/refresh
endpoint to refresh the token.
Q: How do I integrate OAuth2 with a separated front end and back end? A: The front end receives the code through URL parameters and calls the back-end 
/oauth2/token
endpoint to exchange it for an AccessToken, which is then stored in local storage.

Gotchas

Gotchas

  1. 必须实现 SaOAuth2DataLoader — Server启动后不会自动加载数据，需要自行实现接口
  2. allow-url 必须配置 — 不配置回调URL白名单会导致授权失败
  3. 生产环境关闭 isAutoMode — 自动确认授权模式仅用于开发调试
  4. AccessToken有效期默认2小时 — 可通过 
    access-token-timeout
    配置
  5. Scope需要在 DataLoader 和 ClientModel 两端配置 — 只配一端不会生效
  6. 隐式模式不推荐生产使用 — AccessToken直接暴露在URL中，有安全风险
  7. OIDC需要额外配置 iss 和 idTokenTimeout — 不是默认开启就能用
  8. 域名校验不通过会返回错误 — 配置 
    allow-domains
    时要包含所有合法客户端
  1. SaOAuth2DataLoader must be implemented — The Server does not load data automatically after startup, so the interface must be implemented manually
  2. allow-url must be configured — Authorization will fail if the callback URL allowlist is not configured
  3. Disable isAutoMode in production — Automatic authorization confirmation is intended only for development and debugging
  4. The AccessToken validity period defaults to 2 hours — It can be configured through 
    access-token-timeout
  5. Scope must be configured on both the DataLoader and ClientModel sides — Configuring only one side will not take effect
  6. Implicit mode is not recommended for production — The AccessToken is exposed directly in the URL, creating a security risk
  7. OIDC requires additional configuration of iss and idTokenTimeout — Merely enabling it by default is not sufficient
  8. A domain validation failure returns an error — When configuring 
    allow-domains
    , include every legitimate client

Data Privacy

Data Privacy

本技能不收集、存储或传输任何用户数据。所有代码示例仅供本地开发参考。
This skill does not collect, store, or transmit any user data. All code examples are provided solely for local development reference.