1
2
3
4
5
6
7
8
9

┌─────────────────────────────────────────────────────────────┐
│  L4 生产机制(用户感知)  │  双 Token · SSO · Gateway · 接口设计  │
├─────────────────────────────────────────────────────────────┤
│  L3 应用框架(代码落地)  │  Spring Security · sa-token(2 选 1)  │
├─────────────────────────────────────────────────────────────┤
│  L2 身份凭证(数据传输)  │  JWT                                  │
├─────────────────────────────────────────────────────────────┤
│  L1 密码学基石(底层算法)│  对称加密 · 非对称加密 · 数字签名 · HTTPS│
└─────────────────────────────────────────────────────────────┘

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

客户端                    网关                     业务服务
  │                        │                          │
  │ ① HTTPS 握手(TLS)      │                          │
  ├───────────────────────>│                          │
  │ ② 登录 → 拿 access+refresh                         │
  ├───────────────────────>│  →  鉴权服务签发 token    │
  │                        │                          │
  │ ③ 业务请求带 access    │                          │
  ├───────────────────────>│  →  Gateway 验签         │
  │                        │  →  解析 userId/role     │
  │                        │  →  X-User-Id 透传到下游  │
  │                        ├─────────────────────────>│
  │                        │                          │ ④ 业务服务
  │                        │                          │   本地鉴权
  │                        │                          │   (Spring Security
  │                        │                          │    或 sa-token)
  │ ⑤ access 过期          │                          │
  ├───────────────────────>│  →  refresh 换新 access │
  │ ⑥ 返回新 access        │                          │
  <────────────────────────┤                          │
  │                                                        │
  │ ⑦ 单点登录(SSO)        │                            │
  │   a.example.com ─┐                                    │
  │   b.example.com ─┼─→ 共享 SSO 中心                  │
  │   c.example.com ─┘   (Cookie 同域/跨域)              │

1
2

明文 ──[密钥 K]──> 密文  ──[密钥 K]──> 明文
       encrypt          decrypt

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48

import javax.crypto.Cipher;
import javax.crypto.KeyGenerator;
import javax.crypto.SecretKey;
import javax.crypto.spec.GCMParameterSpec;
import javax.crypto.spec.SecretKeySpec;
import java.security.SecureRandom;
import java.util.Base64;

public class AesGcmUtil {
    private static final int KEY_SIZE = 256;
    private static final int IV_SIZE = 12;       // GCM 推荐 12 字节
    private static final int TAG_SIZE = 128;     // 认证标签长度

    public static String encrypt(String plaintext, String keyBase64) throws Exception {
        byte[] keyBytes = Base64.getDecoder().decode(keyBase64);
        SecretKey key = new SecretKeySpec(keyBytes, "AES");

        // IV 每次随机(关键:不能复用)
        byte[] iv = new byte[IV_SIZE];
        new SecureRandom().nextBytes(iv);

        Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding");
        cipher.init(Cipher.ENCRYPT_MODE, key, new GCMParameterSpec(TAG_SIZE, iv));
        byte[] ct = cipher.doFinal(plaintext.getBytes("UTF-8"));

        // 输出 = IV(12) + ciphertext(含 tag)
        byte[] out = new byte[iv.length + ct.length];
        System.arraycopy(iv, 0, out, 0, iv.length);
        System.arraycopy(ct, 0, out, iv.length, ct.length);
        return Base64.getEncoder().encodeToString(out);
    }

    public static String decrypt(String ciphertextBase64, String keyBase64) throws Exception {
        byte[] keyBytes = Base64.getDecoder().decode(keyBase64);
        byte[] data = Base64.getDecoder().decode(ciphertextBase64);
        SecretKey key = new SecretKeySpec(keyBytes, "AES");

        // 拆 IV + ciphertext
        byte[] iv = new byte[IV_SIZE];
        System.arraycopy(data, 0, iv, 0, iv.length);
        byte[] ct = new byte[data.length - iv.length];
        System.arraycopy(data, iv.length, ct, 0, ct.length);

        Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding");
        cipher.init(Cipher.DECRYPT_MODE, key, new GCMParameterSpec(TAG_SIZE, iv));
        return new String(cipher.doFinal(ct), "UTF-8");
    }
}

1
2
3
4
5

公钥加密,私钥解密(机密性):
明文 ──[公钥 PK]──> 密文  ──[私钥 SK]──> 明文

私钥签名,公钥验签(真实性):
明文 ──[私钥 SK]──> 签名  ──[公钥 PK + 明文]──> true/false

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

import java.security.KeyPair;
import java.security.KeyPairGenerator;
import java.security.spec.ECGenParameterSpec;
import javax.crypto.KeyAgreement;

public class EcdhDemo {
    public static void main(String[] args) throws Exception {
        // 1. Alice 生成密钥对
        KeyPairGenerator kpg = KeyPairGenerator.getInstance("EC");
        kpg.initialize(new ECGenParameterSpec("secp256r1"));
        KeyPair aliceKp = kpg.generateKeyPair();

        // 2. Bob 生成密钥对
        KeyPair bobKp = kpg.generateKeyPair();

        // 3. Alice 用自己的私钥 + Bob 的公钥 → 共享密钥
        KeyAgreement aliceKa = KeyAgreement.getInstance("ECDH");
        aliceKa.init(aliceKp.getPrivate());
        aliceKa.doPhase(bobKp.getPublic(), true);
        byte[] aliceShared = aliceKa.generateSecret();

        // 4. Bob 用自己的私钥 + Alice 的公钥 → 共享密钥
        KeyAgreement bobKa = KeyAgreement.getInstance("ECDH");
        bobKa.init(bobKp.getPrivate());
        bobKa.doPhase(aliceKp.getPublic(), true);
        byte[] bobShared = bobKa.generateSecret();

        // 5. 双方得到相同的共享密钥(用于后续对称加密)
        System.out.println(aliceShared.length == bobShared.length);  // true
        // 攻击者即使截获双方公钥,也算不出共享密钥(离散对数难题)
    }
}

1
2
3
4
5
6

签名:
明文 M ──[hash]──> 摘要 H ──[私钥 SK]──> 签名 S

验签:
明文 M ──[hash]──> 摘要 H' ←─┐
签名 S ──[公钥 PK]──> 摘要 H ──┴─> 比较 H == H'

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.util.Base64;

public class HmacUtil {
    public static String sign(String data, String secret) throws Exception {
        Mac mac = Mac.getInstance("HmacSHA256");
        mac.init(new SecretKeySpec(secret.getBytes("UTF-8"), "HmacSHA256"));
        byte[] sig = mac.doFinal(data.getBytes("UTF-8"));
        return Base64.getUrlEncoder().withoutPadding().encodeToString(sig);
    }

    public static boolean verify(String data, String signature, String secret) throws Exception {
        String expected = sign(data, secret);
        // 恒定时间比较,防时序攻击
        return java.security.MessageDigest.isEqual(
            expected.getBytes("UTF-8"), signature.getBytes("UTF-8")
        );
    }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

客户端                                       服务端
  │                                             │
  │  ① ClientHello(支持的密码套件+随机数+密钥共享)│
  ├────────────────────────────────────────────>│
  │                                             │
  │                              生成临时 ECDHE 密钥对
  │                              用 CA 证书(公钥+签名)响应
  │  ② ServerHello + EncryptedExtensions + Certificate + CertificateVerify + Finished
  <────────────────────────────────────────────┤
  │                                             │
  │  验证证书链(数字签名验签)                    │
  │  用服务器 ECDHE 公钥 + 自己 ECDHE 私钥      │
  │  → 计算出 pre-master secret                │
  │  → 派生出会话密钥(对称加密密钥)             │
  │                                             │
  │  ③ Finished(用会话密钥加密)                  │
  ├────────────────────────────────────────────>│
  │                                             │
  │  解密 Finished(对称加密)                     │
  │  验证握手完整性                              │
  │                                             │
  │  ④ Application Data(开始用对称加密传输)      │
  <──────────────────────────────────────────>│

1
2
3

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.   ← Header (base64)
eyJzdWIiOiIxMjM0NSIsIm5hbWUiOiJ4eHgiLCJleHAiOjE3MzAwMDB9.  ← Payload (base64)
SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c   ← Signature

1
2
3
4

{
  "alg": "HS256",      // 签名算法
  "typ": "JWT"
}

1
2
3
4
5
6
7
8
9

{
  "sub": "12345",            // 用户 ID
  "name": "liangweidong",
  "role": "admin",
  "iat": 1700000000,         // 签发时间
  "exp": 1700003600,         // 过期时间(1 小时后)
  "iss": "auth-service",     // 签发方
  "aud": "order-service"     // 接收方
}

1
2
3
4

HMAC-SHA256(
  base64UrlEncode(header) + "." + base64UrlEncode(payload),
  secret
)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75

import com.fasterxml.jackson.databind.ObjectMapper;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;
import java.time.Instant;
import java.util.Base64;
import java.util.HashMap;
import java.util.Map;

public class JwtUtil {
    private static final String SECRET = "${JWT_SECRET:从环境变量注入,32+ 字节随机}";
    private static final long DEFAULT_TTL_SECONDS = 3600;  // 1 小时
    private static final ObjectMapper MAPPER = new ObjectMapper();
    private static final Base64.Encoder ENCODER = Base64.getUrlEncoder().withoutPadding();
    private static final Base64.Decoder DECODER = Base64.getUrlDecoder();

    /** 生成 JWT */
    public static String generate(Long userId, String role, long ttlSeconds) throws Exception {
        // 1. Header
        Map<String, String> header = new HashMap<>();
        header.put("alg", "HS256");
        header.put("typ", "JWT");
        String headerB64 = ENCODER.encodeToString(MAPPER.writeValueAsBytes(header));

        // 2. Payload(标准 claim)
        Map<String, Object> payload = new HashMap<>();
        payload.put("sub", userId);
        payload.put("role", role);
        payload.put("iat", Instant.now().getEpochSecond());
        payload.put("exp", Instant.now().getEpochSecond() + ttlSeconds);
        String payloadB64 = ENCODER.encodeToString(MAPPER.writeValueAsBytes(payload));

        // 3. Signature
        String data = headerB64 + "." + payloadB64;
        String sig = ENCODER.encodeToString(hmacSha256(data.getBytes(StandardCharsets.UTF_8)));

        return data + "." + sig;
    }

    /** 解析 JWT(不验签,只解码 Payload) */
    public static Map<String, Object> parseUnsafe(String token) throws Exception {
        String[] parts = token.split("\\.");
        if (parts.length != 3) {
            throw new IllegalArgumentException("invalid JWT format");
        }
        byte[] payloadBytes = DECODER.decode(parts[1]);
        return MAPPER.readValue(payloadBytes, Map.class);
    }

    /** 验签 + 检查过期 */
    public static boolean verify(String token) throws Exception {
        String[] parts = token.split("\\.");
        if (parts.length != 3) return false;

        String data = parts[0] + "." + parts[1];
        String expected = ENCODER.encodeToString(hmacSha256(data.getBytes(StandardCharsets.UTF_8)));
        // 恒定时间比较
        if (!MessageDigest.isEqual(
                expected.getBytes(StandardCharsets.UTF_8),
                parts[2].getBytes(StandardCharsets.UTF_8))) {
            return false;
        }

        // 过期检查
        Map<String, Object> payload = parseUnsafe(token);
        long exp = ((Number) payload.get("exp")).longValue();
        return Instant.now().getEpochSecond() < exp;
    }

    private static byte[] hmacSha256(byte[] data) throws Exception {
        Mac mac = Mac.getInstance("HmacSHA256");
        mac.init(new SecretKeySpec(SECRET.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
        return mac.doFinal(data);
    }
}

1

攻击者把 header 改成 {"alg": "none"} → 删掉 signature → 服务端如果"按 alg 选算法",直接放行

1
2
3
4

// 拒绝 alg=none
if (!"HS256".equals(alg)) {
    throw new SecurityException("unsupported alg: " + alg);
}

1

攻击者把服务端用 RS256(公钥验签)的算法 → 改成 HS256 → 用"公钥"作为 HMAC 密钥伪造 token

1
2
3
4
5

// 强制用配置的算法,不信 header 里的 alg
String alg = (String) header.get("alg");
if (!ALLOWED_ALG.equals(alg)) {
    throw new SecurityException("alg mismatch");
}

1

攻击者截获合法 token → token 还在有效期内 → 重复使用

1

攻击者 base64 解码 Payload → 看到明文 userId / role → 篡改 role=admin 重新签名

1

开发者把 JWT secret 提交到 GitHub → 攻击者拿到 secret → 伪造任意 token

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

// 引入 dev.sigstore:paseto
String token = Paseto.builder()
    .setSubject(String.valueOf(userId))
    .setExpiration(Instant.now().plus(15, ChronoUnit.MINUTES))
    .setIssuer("auth-center")
    .setKey(KeyUtil.encodeKeyToHex(secretKeyBytes))  // 32 字节对称密钥
    .compact(Paseto.V2.LOCAL);  // LOCAL = 对称加密模式

// 解析
Map<String, Object> claims = Paseto.parser(Paseto.V2.LOCAL)
    .key(KeyUtil.encodeKeyToHex(secretKeyBytes))
    .build()
    .parseClaims(token);

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

@Configuration
@EnableWebSecurity
public class SecurityConfig {

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        return http
            // 1. 关闭 CSRF(前后端分离 + JWT 不需要)
            .csrf(csrf -> csrf.disable())
            // 2. 关闭 Session(用 JWT 替代)
            .sessionManagement(s -> s.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
            // 3. 允许匿名访问的路径
            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/api/public/**", "/api/auth/login").permitAll()
                .anyRequest().authenticated()
            )
            // 4. 添加自定义 JWT 过滤器
            .addFilterBefore(new JwtAuthFilter(), UsernamePasswordAuthenticationFilter.class)
            // 5. 异常处理
            .exceptionHandling(eh -> eh
                .authenticationEntryPoint((req, res, e) -> {
                    res.setStatus(401);
                    res.getWriter().write("{\"code\":401,\"msg\":\"未登录\"}");
                })
            )
            .build();
    }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

@Component
public class JwtAuthFilter extends OncePerRequestFilter {
    @Override
    protected void doFilterInternal(HttpServletRequest req, HttpServletResponse res, FilterChain chain)
            throws ServletException, IOException {
        String token = req.getHeader("Authorization");
        if (token != null && token.startsWith("Bearer ")) {
            token = token.substring(7);
            try {
                Map<String, Object> payload = JwtUtil.parseUnsafe(token);
                if (JwtUtil.verify(token)) {
                    // 把用户信息塞进 SecurityContext
                    Long userId = ((Number) payload.get("sub")).longValue();
                    String role = (String) payload.get("role");
                    List<SimpleGrantedAuthority> auths = List.of(new SimpleGrantedAuthority("ROLE_" + role));
                    UsernamePasswordAuthenticationToken auth = new UsernamePasswordAuthenticationToken(userId, null, auths);
                    SecurityContextHolder.getContext().setAuthentication(auth);
                }
            } catch (Exception ignored) {}
        }
        chain.doFilter(req, res);
    }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

@Configuration
public class SaTokenConfig {
    // 1. 注册 Sa-Token 拦截器(打开注解鉴权)
    @Bean
    public SaInterceptor saInterceptor() {
        return new SaInterceptor();
    }

    // 2. 注册路由拦截器
    @Bean
    public WebMvcConfigurer saTokenWebMvcConfigurer() {
        return new WebMvcConfigurer() {
            @Override
            public void addInterceptors(InterceptorRegistry registry) {
                registry.addInterceptor(saInterceptor())
                    .addPathPatterns("/**")
                    .excludePathPatterns("/api/auth/login", "/api/public/**");
            }
        };
    }

    // 3. 自定义权限验证接口(从 DB 查 userId 的权限列表)
    @Bean
    public StpInterface stpInterface() {
        return new StpInterface() {
            @Autowired private UserService userService;

            @Override
            public List<String> getPermissionList(Object loginId, String loginType) {
                return userService.getPermissions((Long) loginId);
            }
            @Override
            public List<String> getRoleList(Object loginId, String loginType) {
                return userService.getRoles((Long) loginId);
            }
        };
    }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

@RestController
@RequestMapping("/api/order")
public class OrderController {

    // 1. 登录即可访问
    @SaCheckLogin
    @GetMapping("/list")
    public List<Order> list() {
        return orderService.listByUser(StpUtil.getLoginIdAsLong());
    }

    // 2. 需要 admin 角色
    @SaCheckRole("admin")
    @DeleteMapping("/{id}")
    public void delete(@PathVariable Long id) {
        orderService.delete(id);
    }

    // 3. 需要特定权限标识
    @SaCheckPermission("order:export")
    @GetMapping("/export")
    public void export() {
        orderService.export();
    }

    // 4. SSO 鉴权(从认证中心回调后校验)
    @SaCheckLogin
    @GetMapping("/profile")
    public User profile() {
        return userService.getById(StpUtil.getLoginIdAsLong());
    }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

Q1: 团队有 Spring Security 历史经验吗?
    ├─ 有 + 复杂 RBAC 需求 → Spring Security
    └─ 没有 / 经验少
        Q2: 业务权限复杂度?
            ├─ 简单(用户/角色/资源)→ sa-token
            └─ 复杂(用户/角色/资源/数据范围/字段级)→ Spring Security

        Q3: 微服务 + 分布式会话需求?
            ├─ 强(多端登录踢人)→ Spring Security + Spring Session Redis
            └─ 弱 → sa-token 内置方案

        Q4: 鉴权代码量敏感度?
            ├─ 敏感(想少写代码)→ sa-token
            └─ 不敏感(要可扩展)→ Spring Security

最终推荐:
- 中小项目 + 国内团队 + 追求开发效率 → sa-token
- 集团级 + 复杂权限 + Spring 全家桶 → Spring Security
- 已经在用 Spring Security → 不要为换而换
- 新项目 + 团队没经验 → sa-token(更快上手)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

请求进入
  ↓
[SaInterceptor]  ← 拦截带 @SaCheckLogin 等注解的请求
  ↓
[AOP 切面]  ← 解析注解(角色/权限/登录)
  ↓
[StpUtil.getLoginId()]  ← 从 ThreadLocal 拿当前登录用户
  ↓
[StpInterface]  ← 自定义接口查 userId → 角色/权限
  ↓
业务代码(完全不用 if 判断鉴权)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

请求进入
  ↓
[SecurityFilterChain]  ← 13+ 个 Filter 按顺序执行
  ↓
[JwtAuthFilter]  ← 自定义 Filter 解析 JWT
  ↓
[AuthenticationManager]  ← 认证管理器
  ↓
[AccessDecisionManager]  ← 鉴权决策
  ↓
[@PreAuthorize 表达式解析]  ← 业务代码写表达式
  ↓
[SecurityContextHolder]  ← ThreadLocal 存用户信息
  ↓
业务代码(偶尔要 SecurityContextHolder.getContext().getAuthentication())

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

                  ┌─────────────────────────────────────┐
                  │  浏览器 / App / 小程序                │
                  └─────────────────┬───────────────────┘
                                    │ HTTPS (TLS 1.3)
                                    ↓
                  ┌─────────────────────────────────────┐
                  │  Nginx (SSL 卸载 / 静态资源)         │
                  └─────────────────┬───────────────────┘
                                    ↓
                  ┌─────────────────────────────────────┐
                  │  Spring Cloud Gateway                │
                  │  ┌─────────────────────────────┐    │
                  │  │ AuthGlobalFilter            │    │
                  │  │  - 解析 access token         │    │
                  │  │  - 验签 + 过期检查           │    │
                  │  │  - 注入 X-User-Id / X-Role   │    │
                  │  └─────────────────────────────┘    │
                  └────┬──────────────┬─────────────┬───┘
                       ↓              ↓             ↓
                  ┌─────────┐    ┌─────────┐   ┌─────────┐
                  │ user-svc │   │order-svc│   │pay-svc  │
                  │ sa-token │   │ sa-token │   │ sa-token│
                  │ @SaCheck │   │ @SaCheck │   │ @SaCheck│
                  └────┬─────┘    └────┬────┘    └────┬────┘
                       ↓              ↓             ↓
                  ┌─────────────────────────────────────┐
                  │  Redis (sa-token 会话 / refresh)     │
                  │  + MySQL (用户/角色/权限)            │
                  └─────────────────────────────────────┘
                       ↑
                       │ (SSO 时)
                  ┌─────────────────────────────────────┐
                  │  SSO 认证中心 (auth-center)          │
                  │  - 统一登录页                        │
                  │  - 颁发 ticket (一次性)              │
                  │  - 颁发 access+refresh (双 Token)    │
                  └─────────────────────────────────────┘

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53

# sa-token 配置
sa-token:
  # token 名称(同时也是前端请求头的 key)
  token-name: Authorization
  # token 有效期(单位:秒,默认 30 天,-1 代表永久)
  timeout: 900          # access token 15 分钟
  # 临时有效期(指定时间内无操作就视为 token 过期,单位:秒,默认 -1 不过期)
  active-timeout: 1800  # 30 分钟活跃
  # 是否允许同一账号并发登录(为 true 时共用一个 token,为 false 时新登录挤掉旧的)
  is-concurrent: true
  # 在多人登录同一账号时,是否共用一个 token(为 true 时,所有登录共用一个 token)
  is-share: false
  # token 风格(默认可不填,使用默认值)
  token-style: uuid
  # 是否输出操作日志
  is-log: true
  # 是否从 cookie 中读取 token
  is-read-cookie: false
  # 是否从 header 中读取 token
  is-read-header: true
  # token 前缀
  token-prefix: "Bearer "
  # 写入 token 时是否拼接前缀
  is-write-prefix: true
  # jwt 签名密钥(HS256,32+ 字节随机)
  jwt-secret-key: ${SA_TOKEN_SECRET:从环境变量注入,32+ 字节随机}
  # 单独配置 refresh token(用不同的 timeout,本配置用 7 天)
  # (sa-token 原生没有 refresh 概念,我们在自定义逻辑里实现,见 5.5)

# Redis 存储(sa-token 的会话、token 验证信息都放 Redis)
spring:
  data:
    redis:
      host: ${REDIS_HOST:127.0.0.1}
      port: 6379
      password: ${REDIS_PASSWORD}
      database: 0
      timeout: 3000ms
      lettuce:
        pool:
          max-active: 200
          max-idle: 50
          min-idle: 10

# HTTPS 配置(生产环境)
server:
  port: 8443
  ssl:
    enabled: true
    key-store: classpath:keystore.p12
    key-store-password: ${SSL_KEYSTORE_PASSWORD}
    key-store-type: PKCS12
    key-alias: tomcat

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48

@RestController
@RequestMapping("/api/auth")
public class AuthController {

    @Autowired private UserService userService;
    @Autowired private PasswordEncoder passwordEncoder;
    @Autowired private RefreshTokenService refreshTokenService;

    /**
     * 登录:颁发 access + refresh 双 token
     */
    @PostMapping("/login")
    public Result<LoginResponse> login(@RequestBody LoginRequest req) {
        // 1. 校验密码
        User user = userService.getByUsername(req.getUsername());
        if (user == null || !passwordEncoder.matches(req.getPassword(), user.getPasswordHash())) {
            return Result.fail(401, "用户名或密码错误");
        }

        // 2. 颁发 access token(15 分钟,放 sa-token 默认存储)
        StpUtil.login(user.getId());
        String accessToken = StpUtil.getTokenValue();

        // 3. 颁发 refresh token(7 天,自己用 DB 或 Redis 存)
        String refreshToken = refreshTokenService.create(
            user.getId(),
            7 * 24 * 3600  // 7 天过期
        );

        // 4. 返回双 token
        return Result.ok(new LoginResponse(
            accessToken,
            refreshToken,
            900,           // access 过期秒数
            7 * 24 * 3600  // refresh 过期秒数
        ));
    }

    /** 登出 */
    @PostMapping("/logout")
    public Result<Void> logout() {
        // 注销当前 access
        StpUtil.logout();
        // 同时撤销 refresh token
        refreshTokenService.revoke(StpUtil.getLoginIdAsLong());
        return Result.ok();
    }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55

@Service
public class RefreshTokenService {

    @Autowired private StringRedisTemplate redis;

    // 存储 key 前缀
    private static final String PREFIX = "auth:refresh:";

    /**
     * 创建 refresh token(随机 32 字节)
     */
    public String create(Long userId, long ttlSeconds) {
        String token = generateRandomToken();
        String key = PREFIX + token;

        // 存 Redis(值是 userId,带过期时间)
        redis.opsForValue().set(key, String.valueOf(userId), Duration.ofSeconds(ttlSeconds));
        return token;
    }

    /**
     * 校验 + 撤销旧的 + 创建新的(轮换机制)
     */
    public Long verifyAndRotate(String refreshToken) {
        String key = PREFIX + refreshToken;
        String userId = redis.opsForValue().get(key);

        if (userId == null) {
            throw new BizException("refresh token 无效或已过期");
        }

        // 撤销旧的 refresh token(防重放)
        redis.delete(key);

        return Long.valueOf(userId);
    }

    /**
     * 撤销
     */
    public void revoke(Long userId) {
        // 反向查找:用户的所有 refresh token
        // 简单做法:维护"用户 → refresh token 列表" 的映射
        // 实际生产中用 userId 前缀存储,模糊匹配删除
        Set<String> keys = redis.keys(PREFIX + "*:" + userId);
        if (keys != null) redis.delete(keys);
    }

    private String generateRandomToken() {
        SecureRandom random = new SecureRandom();
        byte[] bytes = new byte[32];
        random.nextBytes(bytes);
        return Base64.getUrlEncoder().withoutPadding().encodeToString(bytes);
    }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

@RestController
@RequestMapping("/api/auth")
public class AuthController {

    @Autowired private RefreshTokenService refreshTokenService;

    /**
     * 刷新 access token(access 过期时调用)
     */
    @PostMapping("/refresh")
    public Result<LoginResponse> refresh(@RequestBody RefreshRequest req) {
        // 1. 校验 + 轮换 refresh token
        Long userId = refreshTokenService.verifyAndRotate(req.getRefreshToken());

        // 2. 颁发新 access token
        StpUtil.login(userId);  // 会顶掉旧的 access(因为 is-concurrent=false)
        String newAccessToken = StpUtil.getTokenValue();

        // 3. 颁发新 refresh token(已经在 verifyAndRotate 里轮换过了)
        String newRefreshToken = refreshTokenService.create(userId, 7 * 24 * 3600);

        return Result.ok(new LoginResponse(
            newAccessToken,
            newRefreshToken,
            900,
            7 * 24 * 3600
        ));
    }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

// axios 拦截器:access 过期时自动 refresh
axios.interceptors.response.use(
  response => response,
  async error => {
    const originalRequest = error.config;
    if (error.response?.status === 401 && !originalRequest._retry) {
      originalRequest._retry = true;
      try {
        // 用 refresh token 换新 access
        const refreshToken = localStorage.getItem('refresh_token');
        const resp = await axios.post('/api/auth/refresh', { refreshToken });
        localStorage.setItem('access_token', resp.data.data.accessToken);
        localStorage.setItem('refresh_token', resp.data.data.refreshToken);
        // 重试原请求
        originalRequest.headers.Authorization = `Bearer ${resp.data.data.accessToken}`;
        return axios(originalRequest);
      } catch (refreshError) {
        // refresh 也过期,跳登录页
        window.location.href = '/login';
        return Promise.reject(refreshError);
      }
    }
    return Promise.reject(error);
  }
);

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64

@RestController
@RequestMapping("/sso")
public class SsoController {

    @Autowired private UserService userService;
    @Autowired private RefreshTokenService refreshTokenService;

    // 1. SSO 中心登录页
    @GetMapping("/login")
    public String loginPage(@RequestParam String redirect, Model model) {
        model.addAttribute("redirect", redirect);  // 登录后跳回的地址
        return "sso-login";  // 模板
    }

    // 2. SSO 中心登录提交
    @PostMapping("/doLogin")
    public Result<String> doLogin(@RequestBody LoginRequest req,
                                   @RequestParam String redirect,
                                   HttpServletResponse response) {
        // 1. 验证密码
        User user = userService.getByUsername(req.getUsername());
        if (user == null || !passwordEncoder.matches(req.getPassword(), user.getPasswordHash())) {
            return Result.fail(401, "用户名或密码错误");
        }

        // 2. 颁发一次性的 ticket(5 分钟有效,只能使用一次)
        String ticket = UUID.randomUUID().toString().replace("-", "");
        redis.opsForValue().set("sso:ticket:" + ticket, String.valueOf(user.getId()),
                                 Duration.ofMinutes(5));

        // 3. 写共享 Cookie(关键:domain=.example.com 让所有子域共享)
        Cookie ssoCookie = new Cookie("sso_token", ticket);
        ssoCookie.setDomain(".example.com");   // 关键:点开头的 domain 让所有子域共享
        ssoCookie.setPath("/");
        ssoCookie.setHttpOnly(true);            // 防 XSS 偷 cookie
        ssoCookie.setSecure(true);              // 只在 HTTPS 下发送
        ssoCookie.setMaxAge(5 * 60);            // 5 分钟
        response.addCookie(ssoCookie);

        // 4. 跳回业务系统(URL 携带 ticket)
        String redirectUrl = redirect + "?ticket=" + ticket;
        return Result.ok(redirectUrl);
    }

    // 3. 业务系统用 ticket 换 token
    @GetMapping("/callback")
    public Result<LoginResponse> callback(@RequestParam String ticket) {
        // 1. 校验 ticket + 立即销毁(防重放)
        String userIdStr = redis.opsForValue().get("sso:ticket:" + ticket);
        if (userIdStr == null) {
            return Result.fail(401, "ticket 无效或已使用");
        }
        redis.delete("sso:ticket:" + ticket);

        Long userId = Long.valueOf(userIdStr);

        // 2. 颁发 access + refresh
        StpUtil.login(userId);
        String accessToken = StpUtil.getTokenValue();
        String refreshToken = refreshTokenService.create(userId, 7 * 24 * 3600);

        return Result.ok(new LoginResponse(accessToken, refreshToken, 900, 7 * 24 * 3600));
    }
}