Sa-Token SSO Single Sign-On
Based on all 18 documents in
. Use the
skill for basic authentication.
Capability Boundaries
✅ Strong Fits
- SSO Mode 1 (same domain + Cookie) — Same front-end domain + same Redis, with shared Cookie session synchronization
- SSO Mode 2 (cross-domain + redirect) — Different front-end domains + same Redis, with session propagation through URL redirects
- SSO Mode 3 (cross-domain + HTTP ticket) — Different Redis instances + different networks, with tickets obtained through HTTP requests
- SSO-Server setup — Unified login/logout through an authentication center
- SSO-Client integration — Application system integration with SSO
- Single logout — Logging out in one place simultaneously logs the user out of all systems
- Front-end/back-end separated SSO — H5 solution for SPA applications
- Custom login page — Customized Server-side login page
- Domain validation — Client domain allowlist
- NoSdk/ReSdk — SSO integration for non-Java projects
⚠️ Requirements
- Modes 1 and 2 require all services to share the same Redis instance
- SSO-Server and SSO-Client require network connectivity
- Configure for encrypted communication in production
❌ Out of Scope
- Basic login/permissions/annotation-based authorization → sa-token
- OAuth2.0 server → sa-token-oauth2
- Microservice authentication → sa-token-micro
Comparison of the Three Modes
| Mode | Scenario | Shared Redis | Authentication Mechanism | Applicable To |
|---|
| Type 1 | Same domain | ✅ | Cookie sharing | Sub-systems under the same parent domain |
| Type 2 | Different domains | ✅ | URL redirect | Different domains sharing Redis |
| Type 3 | Fully isolated | ❌ | HTTP ticket | Different Redis instances and network environments |
When to Use Each Mode
- Multiple sub-systems under the same parent domain (such as and ) → 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.
Confirm the environment — Add the
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
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
Step 7.
Test and verify — Verify the cross-system login/logout flow
Reference Documentation
FAQ
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
for encrypted communication; 2) The default ticket validity period is 5 minutes, which is relatively short; 3) Configure
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
- Mode 3 requires the configuration — Do not omit , or the Client will not be able to validate the ticket with the Server
- must be configured in production — may be used during debugging, but it must be enabled in production
- Domain validation allowlist — If is not configured, any domain may connect; restrict it in production
- Single logout requires configuration on both sides — Server-side + Client-side
- 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
- Mode 1 depends on same-domain Cookies — Subdomains must use the same parent domain, such as
- 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
This skill does not collect, store, or transmit any user data. All code examples are provided solely as references for local development.