sa-token-oauth2

Original：🇨🇳 Chinese

Translated

Sa-Token OAuth2.0 server-side skill. Covers four grant modes: Authorization Code, Implicit, Password, and Client Credentials. Includes complete OAuth2-Server setup, the SaOAuth2DataLoader data loader, custom and tiered Scope permissions, the OIDC protocol, OpenId/UnionId, custom grant_type, custom login and authorization pages, annotation-based Access-Token validation, login session interoperability, Scope level control, and custom API routes. Use this skill when building an OAuth2.0 authentication server, developing an open platform, or implementing third-party application authorization. For basic login authentication, use the sa-token skill first.

2installs

Sourcefull-stack-skills/java-skills

Added on2026-10-18

NPX Install

npx skill4agent add full-stack-skills/java-skills sa-token-oauth2

SKILL.md Content (Chinese)

View Translation Comparison →

Sa-Token OAuth2.0 Server

Based on all 17 documents in

sa-token-doc/oauth2/

. Basic authentication uses the

sa-token

skill.

Capability Boundaries

✅ Core Capabilities

Authorization Code — Web applications with a backend; the most commonly used and safest mode
Implicit — Pure front-end applications
Password — Trusted clients, such as first-party apps
Client Credentials — Service-to-service calls without user authorization
Scope Permission Control — Custom Scope definitions and tiered Scope levels
OIDC Protocol — An OpenID Connect identity layer
OpenId/UnionId — Generation and management of unique user identifiers
Custom grant_type — Extension of grant types
Custom Login/Authorization Pages — Customized front-end interfaces
Annotation-Based Access-Token Validation — @SaCheckAccessToken and @SaCheckClientToken

⚠️ Requirements

A JDK 8+ environment is required
The OAuth2-Server must be accessible over the network by Clients
The SaOAuth2DataLoader interface must be implemented to provide data

❌ Out of Scope

Basic login/permission authentication → sa-token
SSO authentication → sa-token-sso
Microservice authentication → sa-token-micro

Four Grant Modes

Mode	Use Case	Description
Authorization Code	Web applications with a backend	Most commonly used and safest
Implicit	Pure front-end applications	No longer recommended
Password	Trusted clients	For first-party apps
Client Credentials	Service-to-service calls	No user authorization required

Choosing a Grant Mode

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. 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

Topic	File	Source
Server setup + DataLoader	references/oauth2-server.md	oauth2-server, oauth2-apidoc
DataLoader + domain validation + customization	references/oauth2-data-loader.md	data-loader, check-domain
Custom Scope permissions and levels	references/oauth2-scope.md	custom-scope, scope-level

FAQ

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

SaOAuth2DataLoader must be implemented — The Server does not load data automatically after startup, so the interface must be implemented manually
allow-url must be configured — Authorization will fail if the callback URL allowlist is not configured
Disable isAutoMode in production — Automatic authorization confirmation is intended only for development and debugging
The AccessToken validity period defaults to 2 hours — It can be configured through
```
access-token-timeout
```
Scope must be configured on both the DataLoader and ClientModel sides — Configuring only one side will not take effect
Implicit mode is not recommended for production — The AccessToken is exposed directly in the URL, creating a security risk
OIDC requires additional configuration of iss and idTokenTimeout — Merely enabling it by default is not sufficient
A domain validation failure returns an error — When configuring
```
allow-domains
```
, include every legitimate client

Data Privacy

This skill does not collect, store, or transmit any user data. All code examples are provided solely for local development reference.