架构与系统设计 / 系统课时
JWT 租户声明
JWT 租户声明
本课设计并实现一组可验证的多租户 JWT 声明:用标准字段记录签发者、用户和有效期,用自定义字段携带租户、角色与会话标识,同时明确哪些信息不能直接信任或写入令牌。
学习目标
- 设计租户、用户、角色、会话和签发信息对应的 JWT 声明
- 使用 Spring Security JOSE 生成并验证 HMAC 签名令牌
- 理解租户声明的安全边界与服务端校验顺序
设计声明边界
JWT 的负载可以被客户端读取,因此它解决的是完整性校验,不是内容保密。令牌中只放鉴权所需的最小信息,禁止写入密码、密钥、身份证号或其他敏感业务数据。
建议使用标准声明承载通用语义:iss 表示签发者,sub 表示用户,iat 表示签发时间,exp 表示过期时间,jti 表示令牌唯一编号。多租户信息放入 tenant_id,角色放入 roles,登录会话放入 sid。

tenant_id 只是经过签名保护的身份上下文,不代表用户天然拥有该租户的全部权限。服务端仍需检查用户状态、租户状态、会话状态,并确认请求资源确实属于同一租户。
生成和验证令牌
在 Spring Boot 3 项目的 pom.xml 中加入 JOSE 支持。由 Spring Boot 管理版本时不需要单独填写 version。
<dependency>
<groupId>org.springframework.security</groupId>
<artifactId>spring-security-oauth2-jose</artifactId>
</dependency>生效行为:项目可以使用 NimbusJwtEncoder 和 NimbusJwtDecoder 创建、签名并解析 JWT。验证方法是编译下面的示例,IDE 和构建工具应能正确解析这些类型。
下面的完整示例使用 HS256 演示令牌签发与验证。固定密钥只用于本地运行,生产环境应从安全配置中心读取足够强度的随机密钥,并设计密钥轮换机制。
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"));
}
}预期输出
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 过滤链,在每次请求中恢复租户上下文并确保请求结束后正确清理。