Back to Details

sa-token-sso

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Sa-Token SSO 单点登录

Sa-Token SSO Single Sign-On

基于 
sa-token-doc/sso/
全部 18 个文档。基础认证使用 
sa-token
技能。
Based on all 18 documents in 
sa-token-doc/sso/
. Use the 
sa-token
skill for basic authentication.

Capability Boundaries

Capability Boundaries

✅ Strong Suits

✅ Strong Fits

  1. SSO模式一（同域+Cookie） — 同前端域名+同Redis，共享Cookie同步会话
  2. SSO模式二（跨域+重定向） — 不同前端域名+同Redis，URL重定向传播会话
  3. SSO模式三（跨域+Http ticket） — 不同Redis+不同网络，Http请求获取ticket
  4. SSO-Server搭建 — 认证中心统一登录/注销
  5. SSO-Client接入 — 应用系统接入SSO
  6. 单点注销 — 一处注销所有系统同时下线
  7. 前后端分离SSO — H5方案适配SPA应用
  8. 自定义登录页面 — 定制化Server端登录页
  9. 域名校验 — 客户端域名白名单
  10. NoSdk/ReSdk — 非Java项目SSO接入
  1. SSO Mode 1 (same domain + Cookie) — Same front-end domain + same Redis, with shared Cookie session synchronization
  2. SSO Mode 2 (cross-domain + redirect) — Different front-end domains + same Redis, with session propagation through URL redirects
  3. SSO Mode 3 (cross-domain + HTTP ticket) — Different Redis instances + different networks, with tickets obtained through HTTP requests
  4. SSO-Server setup — Unified login/logout through an authentication center
  5. SSO-Client integration — Application system integration with SSO
  6. Single logout — Logging out in one place simultaneously logs the user out of all systems
  7. Front-end/back-end separated SSO — H5 solution for SPA applications
  8. Custom login page — Customized Server-side login page
  9. Domain validation — Client domain allowlist
  10. NoSdk/ReSdk — SSO integration for non-Java projects

⚠️ Requirements

⚠️ Requirements

  1. 模式一和模式二需要所有服务共享同一个Redis
  2. SSO-Server和SSO-Client需要网络互通
  3. 生产环境建议配置 
    secret-key
    加密通信
  1. Modes 1 and 2 require all services to share the same Redis instance
  2. SSO-Server and SSO-Client require network connectivity
  3. Configure 
    secret-key
    for encrypted communication in production

❌ Out of Scope

❌ Out of Scope

  1. 基础登录/权限/注解鉴权 → sa-token
  2. OAuth2.0 服务端 → sa-token-oauth2
  3. 微服务鉴权 → sa-token-micro
  1. Basic login/permissions/annotation-based authorization → sa-token
  2. OAuth2.0 server → sa-token-oauth2
  3. Microservice authentication → sa-token-micro

三种模式对比

Comparison of the Three Modes

模式场景共享Redis认证机制适用
类型1同域名✅Cookie共享同父域下的子系统
类型2不同域名✅URL重定向不同域名但共享Redis
类型3完全隔离❌HTTP ticket不同Redis、不同网络
ModeScenarioShared RedisAuthentication MechanismApplicable To
Type 1Same domain✅Cookie sharingSub-systems under the same parent domain
Type 2Different domains✅URL redirectDifferent domains sharing Redis
Type 3Fully isolated❌HTTP ticketDifferent Redis instances and network environments

什么时候用哪种模式

When to Use Each Mode

  • 同父域名下的多个子系统（如 
    admin.example.com
    、
    shop.example.com
    ）→ 模式一，最简单
  • 不同域名但共享Redis基础设施 → 模式二
  • 完全独立的服务，不同Redis、不同网络环境 → 模式三
  • 不确定选哪个 → 默认选模式三，灵活性最高
  • Multiple sub-systems under the same parent domain (such as 
    admin.example.com
    and 
    shop.example.com
    ) → Mode 1, which is the simplest
  • Different domains sharing Redis infrastructure → Mode 2
  • Fully independent services with different Redis instances and network environments → Mode 3
  • Uncertain which mode to choose → Choose Mode 3 by default, as it offers the greatest flexibility

工作流

Workflow

Step 1. 确认环境 — 引入 
sa-token-sso
依赖，确认Redis连接 Step 2. 选择模式 — 根据系统架构选择模式一/二/三 Step 3. 搭建SSO-Server — 配置认证中心 
/sso/auth
等端点 Step 4. 接入SSO-Client — 各应用系统配置认证地址 Step 5. 配置域名校验 — 设置允许的域名白名单 Step 6. 开启单点注销 — 配置 
is-slo: true
Step 7. 测试验证 — 验证跨系统登录/注销流程
Step 1. Confirm the environment — Add the 
sa-token-sso
dependency and verify the Redis connection Step 2. Select a mode — Choose Mode 1, 2, or 3 based on the system architecture Step 3. Set up SSO-Server — Configure authentication center endpoints such as 
/sso/auth
Step 4. Integrate SSO-Client — Configure the authentication address for each application system Step 5. Configure domain validation — Set the allowed-domain allowlist Step 6. Enable single logout — Configure 
is-slo: true
Step 7. Test and verify — Verify the cross-system login/logout flow

参考文档

Reference Documentation

主题文件来源
SSO-Server搭建+三种模式references/sso-server.mdsso-server、sso-type1、sso-type2、sso-type3
SSO-Client接入+注销+FAQreferences/sso-client.mdreadme、signout、sso-questions
前后端分离SSO(H5)references/sso-h5.mdsso-h5
TopicFileSource
SSO-Server setup + three modesreferences/sso-server.mdsso-server, sso-type1, sso-type2, sso-type3
SSO-Client integration + logout + FAQreferences/sso-client.mdreadme, signout, sso-questions
Front-end/back-end separated SSO (H5)references/sso-h5.mdsso-h5

FAQ

FAQ

Q: SSO和OAuth2.0的区别是什么？ A: SSO解决多系统统一登录问题（一个账号登录所有系统）。OAuth2.0解决第三方授权问题（允许第三方应用访问用户数据）。简单场景选SSO，开放平台场景选OAuth2.0。
Q: 三种SSO模式如何选择？ A: 同域名用模式一（最简单），跨域但共享Redis用模式二，完全隔离的环境用模式三。不确定时选模式三。
Q: SSO-Server和SSO-Client必须用同一语言吗？ A: 模式一和模式二需要（依赖共享Redis的Java SDK），模式三不限语言（通过HTTP交互）。
Q: 如何保证ticket的安全性？ A: 1) 配置 
secret-key
加密通信；2) ticket有效期默认5分钟，较短；3) 配置 
is-check-sign: true
校验签名。
Q: SSO支持前后端分离项目吗？ A: 支持。有专门的H5方案，前端SPA应用通过URL参数传递ticket，后端提供接口换取登录态。
Q: 单点注销是怎么工作的？ A: 用户在SSO-Server注销时，Server会向所有已注册的Client发送注销通知，各Client清除本地会话。
Q: What is the difference between SSO and OAuth2.0? A: SSO solves unified login across multiple systems, allowing one account to log into all systems. OAuth2.0 solves third-party authorization by allowing third-party applications to access user data. Choose SSO for simple scenarios and OAuth2.0 for open platform scenarios.
Q: How should the three SSO modes be selected? A: Use Mode 1 for the same domain because it is the simplest, Mode 2 for cross-domain environments sharing Redis, and Mode 3 for fully isolated environments. If uncertain, choose Mode 3.
Q: Must SSO-Server and SSO-Client use the same language? A: Modes 1 and 2 require the same language because they depend on a Java SDK with shared Redis. Mode 3 is language-agnostic because interaction occurs through HTTP.
Q: How can ticket security be ensured? A: 1) Configure 
secret-key
for encrypted communication; 2) The default ticket validity period is 5 minutes, which is relatively short; 3) Configure 
is-check-sign: true
to validate signatures.
Q: Does SSO support front-end/back-end separated projects? A: Yes. A dedicated H5 solution is available. Front-end SPA applications pass the ticket through URL parameters, while the back end provides an endpoint to exchange it for a login state.
Q: How does single logout work? A: When a user logs out through SSO-Server, the Server sends logout notifications to all registered Clients, and each Client clears its local session.

Gotchas

Gotchas

  1. 模式三需要配置 ticket-url — 不能遗漏 
    ticket-url
    配置，否则Client无法向Server校验ticket
  2. secret-key 生产环境必须配置 — 调试时可设 
    is-check-sign: false
    ，生产务必开启
  3. 域名校验白名单 — 未配置 
    allow-domains
    时所有域名均可接入，生产环境需限制
  4. 单点注销需双向配置 — Server端 
    is-slo: true
    + Client端 
    reg-logout-call: true
  5. 前后端分离下URL中ticket参数需要前端主动处理 — 后端不会自动重定向
  6. 模式一依赖Cookie同域 — 子域名必须在同一父域名下（如 
    .example.com
    ）
  7. Same-Token与SSO不要混淆 — Same-Token用于微服务内部鉴权，SSO用于用户登录态共享
  1. Mode 3 requires the 
    ticket-url
    configuration     — Do not omit 
    ticket-url
    , or the Client will not be able to validate the ticket with the Server
  2. secret-key
    must be configured in production     — 
    is-check-sign: false
    may be used during debugging, but it must be enabled in production
  3. Domain validation allowlist — If 
    allow-domains
    is not configured, any domain may connect; restrict it in production
  4. Single logout requires configuration on both sides — Server-side 
    is-slo: true
    + Client-side 
    reg-logout-call: true
  5. In front-end/back-end separated architectures, the front end must actively handle the ticket parameter in the URL — The back end will not redirect automatically
  6. Mode 1 depends on same-domain Cookies — Subdomains must use the same parent domain, such as 
    .example.com
  7. Do not confuse Same-Token with SSO — Same-Token is used for internal microservice authentication, while SSO is used to share user login states

Data Privacy

Data Privacy

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