SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillssa-token-advanced

sa-token-advanced

Security & auditing

View repository

Updated 10-15 21:48

About this skill

Sa-Token Advanced Security Features

Based on sa-token-doc/up/In-Depth + fun/Advanced + arch/Architecture Documentation.

Applicable Scenarios

Activate this skill when the user needs the following scenarios:

  • Secondary Verification for Sensitive Operations — Operations such as deleting a repository/changing a password require identity confirmation again
  • Account Violation Penalties — Ban by service dimension (mute only without restricting purchases), penalize by violation level
  • Backend User Impersonation — Customer service personnel need to temporarily operate as a user
  • Multiple Account Systems — The system simultaneously contains two independent account tables, User and Admin
  • Global Event Logging — Record operation logs for all users' login/logout/kickout/ban, etc.
  • Password Encrypted Storage — Secure storage and verification of user passwords

Workflow

Step 1. Determine requirements — Choose specific features such as secondary authentication/banning/multi-account/listeners, etc. Step 2. Write code — Implement the corresponding functionality according to the API documentation Step 3. Configuration and registration — Register listeners, configure filters, define multiple account systems Step 4. Test and verify — Verify that the functional behavior meets expectations

Capability Boundaries

✅ Strong Suits

  1. Secondary Authentication — openSafe()/checkSafe()/@SaCheckSafe Secondary verification for sensitive operations
  2. Account Banning — Full ban/category ban (comment/order/shop)/tiered ban (level)
  3. Identity Switching — switchTo()/endSwitch() Impersonate other accounts
  4. Multi-Account Authentication — StpUserUtil mode + StpKit facade mode, multiple account systems
  5. Global Listeners — SaTokenListener interface (10+ events such as login/logout/kickout/ban, etc.)
  6. Global Filters — SaServletFilter + SaReactorFilter, unified security header settings
  7. Password Encryption — 5 algorithms: MD5/SHA/AES/RSA/BCrypt + TOTP verification code
  8. Session Query — SaTerminalInfo terminal list + searchTokenValue/TokenSession/Session
  9. Http Basic/Digest — @SaCheckHttpBasic / @SaCheckHttpDigest
  10. Firewall — IP blacklist and whitelist + request rate limiting
  11. Custom Annotations — Composite annotations/custom authorization annotations

⚠️ Requirements

  1. All features are based on sa-token-core, and some features can only be used after logging in
  2. Global listeners need to be registered with the Spring container (@Component or manual registration)
  3. Multi-account authentication requires defining the account system name yourself

❌ Out of Scope

  1. Basic login/permissions/annotation-based authorization → sa-token
  2. SSO single sign-on → sa-token-sso
  3. OAuth2.0 server → sa-token-oauth2
  4. Microservice authentication → sa-token-micro

Reference Documentation

Topic File Source
Secondary Authentication (safe-auth) references/safe-auth.md GitHub
Account Banning (category + tiered) references/disable.md GitHub
Identity Switching (mock-person) references/mock-person.md GitHub
Multi-account authentication references/many-account.md GitHub
Password encryption + HttpBasic references/password-basic.md GitHub
Global listener + Global filter references/listener-filter.md GitHub

Core API Quick Reference

// === 二级认证 ===
StpUtil.openSafe("update-password");         // 开启(默认120秒)
StpUtil.checkSafe("update-password");         // 校验
@SaCheckSafe("update-password")               // 注解

// === 账号封禁 ===
StpUtil.disable(10001, "comment", 200);       // 分类封禁
StpUtil.disableLevel(10001, "comment", 2, 200); // 阶梯封禁
StpUtil.untieDisable(10001, "comment");       // 解封
@SaCheckDisable("comment")                     // 注解

// === 身份切换 ===
StpUtil.switchTo(10001);                       // 切换到其他账号
StpUtil.switchTo(10001, () -> { ... });        // Lambda作用域切换

// === 多账号 ===
StpUserUtil.login(10001);                     // User体系
StpKit.admin.login(10001);                    // StpKit门面

// === 密码加密 ===
SaSecureUtil.md5("123456");
SaSecureUtil.aesEncrypt(key, "data");
SaSecureUtil.rsaEncryptByPublic(publicKey, text);
SaTotpUtil.generateCode("secret");
SaSecureUtil.bCryptPasswordEncoder("123456");

// === 全局侦听器 ===
SaTokenEventCenter.registerListener(listener);
@Component class MyListener extends SaTokenListenerForSimple { ... }

// === 会话查询 ===
StpUtil.searchTokenValue(keyword, start, size, sort);
StpUtil.searchSessionId(keyword, start, size, sort);

FAQ

Q: What is the difference between secondary authentication and regular login? A: Regular login is the first identity verification. Secondary authentication is a second verification of sensitive operations (such as changing passwords, deleting repositories) on top of an already logged-in session. The two are independent.

Q: How are the three levels of account banning used? A: For simple violations, use full ban. For service-dimension violations, use categorized ban (such as muting only without banning purchases). For graded penalties, use stepped ban (such as level1 for a first violation, level3 for multiple violations).

Q: What is the difference between StpUserUtil and StpKit? A: StpUserUtil is the built-in User account system. The StpKit facade pattern can customize any number of account systems (such as User, Admin, Teacher), making it more flexible.

Q: What events can the global listener listen to? A: Login, logout, kick offline, be forced offline, ban, unban, secondary authentication enable/disable, Session creation/destruction, Token renewal, 11 events in total.

Q: How to choose between SaServletFilter and SaInterceptor? A: Choose SaServletFilter if you need to filter static resources or set security response headers. Choose SaInterceptor if you only need Controller-layer authentication. The two can be used at the same time.

Q: How to customize an authentication annotation? A: Implement SaAnnotationStrategy custom annotation processor, you can refer to the custom_annotation package in the official demo.

Gotchas

  1. StpInterface can implement isDisabled() custom ban logic — by default, bans are in memory and lost on restart
  2. Multi-account systems can be specified in annotations via the type attribute — such as @SaCheckLogin(type = "user")
  3. For global listeners, it is recommended to use SaTokenListenerForSimple to simplify implementation — only override the methods you need
  4. The default validity period of secondary authentication is 120 seconds — can be adjusted according to business needs
  5. For stepped bans, the larger the level value, the more severe the ban — checkDisableLevel(3) means only block when level≥3
  6. switchTo's Lambda approach is safer than manually calling endSwitch — you will not forget to restore the identity
  7. When setting security response headers in the global filter, pay attention to browser compatibility
  8. The account and password of Http Basic authentication are transmitted in plaintext over the network — must be used together with HTTPS

Data Privacy

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