Spring Authorization Server 实战：如何在JWT访问令牌中添加自定义权限声明

前言

在现代OAuth2.0授权体系中，JWT(JSON Web Token)已成为访问令牌的事实标准格式。Spring Authorization Server作为新一代的授权服务器实现，提供了灵活的JWT定制能力。本文将深入讲解如何在该项目中为JWT访问令牌添加自定义权限声明，帮助资源服务器更好地理解用户的访问权限。

核心概念解析

在开始之前，我们需要明确几个关键概念：

1. JWT访问令牌：采用JSON格式的令牌，包含头部(Header)、载荷(Payload)和签名(Signature)三部分
2. 声明(Claims)：JWT载荷中的键值对，包含标准声明(如iss, sub等)和自定义声明
3. 权限(Authorities)：代表用户的访问权限，可以是角色(Roles)、权限(Permissions)或用户组(Groups)

基础配置：添加自定义声明

Spring Authorization Server提供了OAuth2TokenCustomizer<JWTEncodingContext>接口，允许我们定制JWT令牌。以下是基础实现步骤：

@Bean
public OAuth2TokenCustomizer<JwtEncodingContext> jwtTokenCustomizer() {
    return context -> {
        if (OAuth2TokenType.ACCESS_TOKEN.equals(context.getTokenType())) {
            context.getClaims().claims(claims -> {
                claims.put("custom-claim", "custom-value");
                // 添加更多自定义声明
            });
        }
    };
}

关键点说明：

• 通过context.getTokenType()确保只处理访问令牌
• 使用context.getClaims()获取当前声明集合
• claims.put()方法添加自定义声明

进阶实践：添加权限声明

实际业务中，我们通常需要将用户权限信息包含在令牌中。下面展示如何将用户角色信息作为自定义声明添加到JWT：

@Configuration
public class CustomClaimsWithAuthoritiesConfiguration {
    
    // 示例用户配置
    @Bean
    public UserDetailsService users() {
        UserDetails user = User.withUsername("user1")
            .password("{noop}password")
            .roles("USER", "ADMIN")  // 分配角色
            .build();
        return new InMemoryUserDetailsManager(user);
    }

    // JWT定制器
    @Bean
    public OAuth2TokenCustomizer<JwtEncodingContext> jwtTokenCustomizer() {
        return context -> {
            if (OAuth2TokenType.ACCESS_TOKEN.equals(context.getTokenType())) {
                context.getClaims().claims(claims -> {
                    // 从Principal中提取角色信息
                    Set<String> roles = context.getPrincipal().getAuthorities().stream()
                        .map(GrantedAuthority::getAuthority)
                        .map(authority -> authority.replace("ROLE_", ""))  // 移除ROLE_前缀
                        .collect(Collectors.toSet());
                    
                    // 添加roles自定义声明
                    claims.put("roles", roles);
                });
            }
        };
    }
}

代码解析：

1. 首先配置了一个示例用户，赋予USER和ADMIN两个角色
2. 在JWT定制器中，我们：
   • 确认当前处理的是访问令牌
   • 从Principal对象中获取用户权限集合
   • 对权限名称进行处理（移除ROLE_前缀）
   • 将处理后的权限集合作为自定义声明添加到JWT

实际应用场景

这种权限声明方式在以下场景特别有用：

1. 微服务架构：资源服务器可以直接从令牌中获取用户权限，无需额外查询
2. 细粒度授权：基于声明的权限控制可以实现方法级别的访问控制
3. 跨系统集成：标准化权限声明格式便于不同系统间的权限识别

最佳实践建议

1. 声明命名规范：建议使用小写字母和下划线组合（如user_roles）
2. 敏感信息处理：不要在令牌中包含敏感信息，JWT默认只进行Base64编码
3. 声明大小控制：避免添加过多声明，防止令牌过大影响性能
4. 前缀处理一致性：确保角色前缀处理逻辑在客户端和资源端保持一致

总结

通过本文，我们学习了如何在Spring Authorization Server中为JWT访问令牌添加自定义权限声明。这种技术实现了用户权限信息的标准化传递，简化了资源服务器的权限验证逻辑，是构建安全、高效授权体系的重要一环。开发者可以根据实际业务需求，扩展更多自定义声明，构建更加强大的授权解决方案。