架构与系统设计 / 系统课时

JWT 租户声明

JWT 租户声明

本课设计并实现一组可验证的多租户 JWT 声明:用标准字段记录签发者、用户和有效期,用自定义字段携带租户、角色与会话标识,同时明确哪些信息不能直接信任或写入令牌。

学习目标

  • 设计租户、用户、角色、会话和签发信息对应的 JWT 声明
  • 使用 Spring Security JOSE 生成并验证 HMAC 签名令牌
  • 理解租户声明的安全边界与服务端校验顺序

设计声明边界

JWT 的负载可以被客户端读取,因此它解决的是完整性校验,不是内容保密。令牌中只放鉴权所需的最小信息,禁止写入密码、密钥、身份证号或其他敏感业务数据。

建议使用标准声明承载通用语义:iss 表示签发者,sub 表示用户,iat 表示签发时间,exp 表示过期时间,jti 表示令牌唯一编号。多租户信息放入 tenant_id,角色放入 roles,登录会话放入 sid。

多租户 JWT 结构与验证链路

tenant_id 只是经过签名保护的身份上下文,不代表用户天然拥有该租户的全部权限。服务端仍需检查用户状态、租户状态、会话状态,并确认请求资源确实属于同一租户。

生成和验证令牌

在 Spring Boot 3 项目的 pom.xml 中加入 JOSE 支持。由 Spring Boot 管理版本时不需要单独填写 version。

xml
<dependency>
    <groupId>org.springframework.security</groupId>
    <artifactId>spring-security-oauth2-jose</artifactId>
</dependency>

生效行为:项目可以使用 NimbusJwtEncoder 和 NimbusJwtDecoder 创建、签名并解析 JWT。验证方法是编译下面的示例,IDE 和构建工具应能正确解析这些类型。

下面的完整示例使用 HS256 演示令牌签发与验证。固定密钥只用于本地运行,生产环境应从安全配置中心读取足够强度的随机密钥,并设计密钥轮换机制。

java
package com.example.jwt;

import com.nimbusds.jose.jwk.source.ImmutableSecret;
import java.nio.charset.StandardCharsets;
import java.time.Duration;
import java.time.Instant;
import java.util.List;
import java.util.UUID;
import javax.crypto.SecretKey;
import javax.crypto.spec.SecretKeySpec;
import org.springframework.security.oauth2.jose.jws.MacAlgorithm;
import org.springframework.security.oauth2.jwt.Jwt;
import org.springframework.security.oauth2.jwt.JwtClaimsSet;
import org.springframework.security.oauth2.jwt.JwtEncoder;
import org.springframework.security.oauth2.jwt.JwtEncoderParameters;
import org.springframework.security.oauth2.jwt.JwsHeader;
import org.springframework.security.oauth2.jwt.NimbusJwtDecoder;
import org.springframework.security.oauth2.jwt.NimbusJwtEncoder;

public class TenantJwtDemo {

    private static final String ISSUER = "https://auth.anystack.local";

    private final JwtEncoder encoder;
    private final NimbusJwtDecoder decoder;

    public TenantJwtDemo(String secret) {
        SecretKey key = new SecretKeySpec(
                secret.getBytes(StandardCharsets.UTF_8),
                "HmacSHA256");
        this.encoder = new NimbusJwtEncoder(new ImmutableSecret<>(key));
        this.decoder = NimbusJwtDecoder.withSecretKey(key)
                .macAlgorithm(MacAlgorithm.HS256)
                .build();
    }

    public String issueToken(
            String tenantId,
            String userId,
            List<String> roles,
            String sessionId,
            Duration ttl) {

        Instant now = Instant.now();
        JwtClaimsSet claims = JwtClaimsSet.builder()
                .issuer(ISSUER)
                .subject(userId)
                .issuedAt(now)
                .expiresAt(now.plus(ttl))
                .id(UUID.randomUUID().toString())
                .claim("tenant_id", tenantId)
                .claim("roles", roles)
                .claim("sid", sessionId)
                .build();

        JwsHeader header = JwsHeader.with(MacAlgorithm.HS256).build();
        return encoder.encode(JwtEncoderParameters.from(header, claims))
                .getTokenValue();
    }

    public Jwt verify(String token) {
        Jwt jwt = decoder.decode(token);
        String issuer = jwt.getClaimAsString("iss");
        if (!ISSUER.equals(issuer)) {
            throw new IllegalArgumentException("unexpected issuer");
        }
        return jwt;
    }

    public static void main(String[] args) {
        TenantJwtDemo service = new TenantJwtDemo(
                "0123456789abcdef0123456789abcdef");

        String token = service.issueToken(
                "tenant-a",
                "user-42",
                List.of("ADMIN", "OPERATOR"),
                "session-1001",
                Duration.ofMinutes(30));

        Jwt jwt = service.verify(token);
        System.out.println("token=" + token);
        System.out.println("tenant_id=" + jwt.getClaimAsString("tenant_id"));
        System.out.println("user_id=" + jwt.getSubject());
        System.out.println("roles=" + jwt.getClaimAsStringList("roles"));
        System.out.println("sid=" + jwt.getClaimAsString("sid"));
        System.out.println("issuer=" + jwt.getClaimAsString("iss"));
    }
}

预期输出

text
token=<JWT>
tenant_id=tenant-a
user_id=user-42
roles=[ADMIN, OPERATOR]
sid=session-1001
issuer=https://auth.anystack.local

<JWT> 每次运行都会变化,因为 iat、exp 和 jti 是动态值。解码器会验证签名和过期时间,示例额外检查 iss;生产环境还应根据系统设计验证受众、允许的算法和密钥版本。

请求中的校验顺序

收到 Bearer Token 后,服务端应先验证签名、算法和有效期,再读取 tenant_id。不能先按未验证的租户声明查询数据,否则攻击者可以构造任意负载影响日志、缓存键或数据库路由。

令牌租户与请求目标租户必须一致。例如请求路径、域名或网关头已经解析出目标租户时,应与 tenant_id 比对;发生冲突应直接拒绝,而不是选择其中一个继续执行。

roles 适合携带较稳定的粗粒度角色。高频变化的权限、账户冻结状态和租户停用状态应在服务端查询或通过短期缓存确认,避免旧令牌在权限变更后长期有效。

常见错误

  • 把 JWT 当作加密容器,在负载中存放敏感数据
  • 只解码负载而不验证签名、算法、签发者和过期时间
  • 仅凭 tenant_id 拼接查询条件,却不检查资源归属和用户权限

本课总结

  • 标准声明记录签发与有效期,自定义声明只承载最小租户上下文
  • JWT 声明必须在签名和时效验证通过后才能参与业务处理
  • 租户、会话和角色仍需结合服务端状态完成最终授权

下一课预告

下一课将把 JWT 验证接入 Spring Security 过滤链,在每次请求中恢复租户上下文并确保请求结束后正确清理。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

JWT 租户声明

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通