使用Spring Security和Java如何在JWT中传入角色/权限供Redux鉴权

常见报错根因 #

你尝试添加角色字段时触发错误，基本可以归为三类问题：

• 直接把自定义User实体、自定义Role实体这类复杂业务对象整个放入claims，导致序列化失败。JJWT要求claims的value必须是可被默认Jackson序列化的基础类型、标准集合类型，无法直接序列化任意自定义实体
• 角色数据的获取逻辑不对：如果从Authentication中拿到的是自定义非标准User实现，直接把未类型转换的权限集合放入claims，会触发类型不匹配错误
• 方法调用顺序错误：现有代码把setSubject放在setClaims之前，setClaims会完全替换构建器中已有的claims内容，后续新增字段如果没有同步到传入的map中，就会出现字段丢失、签名校验不通过的问题

具体实现步骤 #

1. 改造Token生成方法，正确写入角色字段 #

调整代码顺序，从Authentication上下文提取标准格式的角色数据写入claims：

public String generateToken(Authentication authentication){
    UserPrincipal userPrincipal = (UserPrincipal) authentication.getPrincipal();
    Date now = new Date(System.currentTimeMillis());
    Date expiryDate = new Date(now.getTime() + SecurityConstants.EXPIRATION_TIME); 
    String userId = Long.toString(userPrincipal.getId());
   
    Map<String, Object> claims = new HashMap<>();
    claims.put("id", userId);
    claims.put("username", userPrincipal.getUsername());
    // 提取角色为标准字符串集合，避免序列化问题
    List<String> roles = userPrincipal.getAuthorities().stream()
        .map(GrantedAuthority::getAuthority)
        .collect(Collectors.toList());
    // 单角色场景简化为字符串，多角色场景存为数组
    if (roles.size() == 1) {
        claims.put("userRole", roles.get(0));
    } else {
        claims.put("userRoles", roles);
    }

    return Jwts.builder()
            // 先设置完整claims，再补充其他配置，避免内容被覆盖
            .setClaims(claims)
            .setSubject(userId)
            .setIssuedAt(now)
            .setExpiration(expiryDate)
            .signWith(SignatureAlgorithm.HS512, SecurityConstants.SECRET)
            .compact();
}

注意：原代码中setSubject放在setClaims前面的写法有典型隐患——setClaims会直接替换当前构建器中所有已设置的claims内容，如果没有把subject同步到传入的map中，就会被后续调用覆盖，这也是很多人加字段后出现token校验失败、解析为空的常见原因。

2. 配套增加角色解析方法 #

保留现有getUserIdFromJWT、validateToken的逻辑不变，新增对应读取角色的方法，避免后续解析时出现类型转换错误：

// 单角色场景读取
public String getUserRoleFromJWT(String token) {
    Claims claims = Jwts.parser()
        .setSigningKey(SecurityConstants.SECRET)
        .parseClaimsJws(token)
        .getBody();
    return (String) claims.get("userRole");
}

// 多角色场景读取
public List<String> getUserRolesFromJWT(String token) {
    Claims claims = Jwts.parser()
        .setSigningKey(SecurityConstants.SECRET)
        .parseClaimsJws(token)
        .getBody();
    return (List<String>) claims.get("userRoles");
}

3. 前端Redux侧适配 #

后端返回token后，前端解析payload时会自动把userRole/userRoles字段和其他用户基础信息合并，不需要额外做特殊处理。最终Redux存储的用户状态会直接包含类似userRole: "ADMIN"的字段，可以直接用来做路由守卫、按钮级权限判断，和你参考的Redux存储结构完全对齐。

额外注意事项 #

• 不要把权限、角色这类业务自定义字段放在JWT的header中，header只用来存加密算法、token类型等元信息，所有业务字段统一放在payload的claims中
• 多角色场景建议直接存标准JSON数组结构，不要拼接成逗号分隔的字符串，避免前端解析时额外增加拆分逻辑
• 写入角色字段后，不需要修改现有validateToken逻辑，因为校验流程只验证签名和有效期，不关心claims中的具体业务内容

内容的提问来源于stack exchange，提问作者Carlos Jasso