如何在Swagger中轻松实现JWT身份验证保护API接口安全从配置到实践的全流程指南让您的API文档更加安全可靠

威震华夏关云长

引言

在现代Web开发中，API（应用程序编程接口）已经成为不同系统之间通信的核心组件。随着API的广泛应用，确保API的安全性变得尤为重要。Swagger（现为OpenAPI）作为一种流行的API文档和开发工具，提供了强大的功能来描述、生产和消费RESTful Web服务。而JWT（JSON Web Token）则是一种开放标准的令牌，用于在网络应用环境间传递声明的安全方式。

本文将详细介绍如何在Swagger中集成JWT身份验证，为您的API接口提供安全保障。我们将从基础概念开始，逐步引导您完成整个配置过程，并通过实际案例展示如何实现这一安全机制。

基础概念解释

Swagger简介

Swagger是一套围绕OpenAPI规范构建的开源工具，可以帮助您设计、构建、记录和使用RESTful Web服务。它主要包括以下几个部分：

• Swagger Editor：一个基于浏览器的编辑器，可以在其中编写OpenAPI规范。
• Swagger UI：一个将OpenAPI规范呈现为交互式API文档的工具。
• Swagger Codegen：从OpenAPI规范生成服务器存根和客户端库的工具。

JWT简介

JWT（JSON Web Token）是一种开放标准（RFC 7519），它定义了一种紧凑的、自包含的方式，用于作为JSON对象在各方之间安全地传输信息。JWT通常用于身份验证和信息交换。

一个JWT实际上由三部分组成，用点（.）分隔：

1. 头部（Header）
2. 载荷（Payload）
3. 签名（Signature）

例如：xxxxx.yyyyy.zzzzz

为什么需要在Swagger中集成JWT身份验证

在Swagger中集成JWT身份验证有以下几个主要原因：

1. 安全性：通过JWT身份验证，可以确保只有经过授权的用户才能访问API。
2. 文档完整性：在API文档中明确标识需要身份验证的接口，使开发者更容易理解API的使用方式。
3. 测试便利性：Swagger UI提供了直接在文档中测试API的功能，集成JWT后，开发者可以在文档中直接进行身份验证并测试受保护的接口。
4. 标准化：遵循行业标准的安全实践，提高API的专业性和可信度。

环境准备

在开始之前，您需要准备以下环境和工具：

必需工具

1. Java Development Kit (JDK)：版本8或更高
2. Maven：用于项目构建和依赖管理
3. IDE：如IntelliJ IDEA或Eclipse
4. Postman（可选）：用于API测试

项目依赖

如果您使用Maven构建项目，需要在pom.xml中添加以下依赖：

2. <!-- Spring Boot Starter Web -->
3. <dependency>
4.     <groupId>org.springframework.boot</groupId>
5.     <artifactId>spring-boot-starter-web</artifactId>
6. </dependency>
8. <!-- Spring Boot Starter Security -->
9. <dependency>
10.     <groupId>org.springframework.boot</groupId>
11.     <artifactId>spring-boot-starter-security</artifactId>
12. </dependency>
14. <!-- Spring Boot Starter Validation -->
15. <dependency>
16.     <groupId>org.springframework.boot</groupId>
17.     <artifactId>spring-boot-starter-validation</artifactId>
18. </dependency>
20. <!-- JWT Support -->
21. <dependency>
22.     <groupId>io.jsonwebtoken</groupId>
23.     <artifactId>jjwt-api</artifactId>
24.     <version>0.11.5</version>
25. </dependency>
26. <dependency>
27.     <groupId>io.jsonwebtoken</groupId>
28.     <artifactId>jjwt-impl</artifactId>
29.     <version>0.11.5</version>
30.     <scope>runtime</scope>
31. </dependency>
32. <dependency>
33.     <groupId>io.jsonwebtoken</groupId>
34.     <artifactId>jjwt-jackson</artifactId>
35.     <version>0.11.5</version>
36.     <scope>runtime</scope>
37. </dependency>
39. <!-- Swagger Dependencies -->
40. <dependency>
41.     <groupId>io.springfox</groupId>
42.     <artifactId>springfox-swagger2</artifactId>
43.     <version>3.0.0</version>
44. </dependency>
45. <dependency>
46.     <groupId>io.springfox</groupId>
47.     <artifactId>springfox-swagger-ui</artifactId>
48.     <version>3.0.0</version>
49. </dependency>
50. <dependency>
51.     <groupId>io.springfox</groupId>
52.     <artifactId>springfox-boot-starter</artifactId>
53.     <version>3.0.0</version>
54. </dependency>

复制代码

如果您使用Spring Boot 3.x或更高版本，Swagger依赖可能有所不同：

2. <!-- SpringDoc OpenAPI Dependencies -->
3. <dependency>
4.     <groupId>org.springdoc</groupId>
5.     <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
6.     <version>2.1.0</version>
7. </dependency>

复制代码

配置步骤

1. 创建JWT工具类

首先，我们需要创建一个JWT工具类，用于生成和验证JWT令牌。

2. import io.jsonwebtoken.Claims;
3. import io.jsonwebtoken.Jwts;
4. import io.jsonwebtoken.SignatureAlgorithm;
5. import io.jsonwebtoken.security.Keys;
6. import org.springframework.beans.factory.annotation.Value;
7. import org.springframework.security.core.userdetails.UserDetails;
8. import org.springframework.stereotype.Component;
10. import java.security.Key;
11. import java.util.Date;
12. import java.util.HashMap;
13. import java.util.Map;
14. import java.util.function.Function;
16. @Component
17. public class JwtTokenUtil {
19.     @Value("${jwt.secret}")
20.     private String secret;
22.     @Value("${jwt.expiration}")
23.     private Long expiration;
25.     // 生成用于签名的密钥
26.     private Key getSigningKey() {
27.         return Keys.hmacShaKeyFor(secret.getBytes());
28.     }
30.     // 从令牌中提取用户名
31.     public String getUsernameFromToken(String token) {
32.         return getClaimFromToken(token, Claims::getSubject);
33.     }
35.     // 从令牌中提取过期时间
36.     public Date getExpirationDateFromToken(String token) {
37.         return getClaimFromToken(token, Claims::getExpiration);
38.     }
40.     // 从令牌中提取特定声明
41.     public <T> T getClaimFromToken(String token, Function<Claims, T> claimsResolver) {
42.         final Claims claims = getAllClaimsFromToken(token);
43.         return claimsResolver.apply(claims);
44.     }
46.     // 解析令牌获取所有声明
47.     private Claims getAllClaimsFromToken(String token) {
48.         return Jwts.parserBuilder()
49.                 .setSigningKey(getSigningKey())
50.                 .build()
51.                 .parseClaimsJws(token)
52.                 .getBody();
53.     }
55.     // 检查令牌是否过期
56.     private Boolean isTokenExpired(String token) {
57.         final Date expiration = getExpirationDateFromToken(token);
58.         return expiration.before(new Date());
59.     }
61.     // 生成令牌
62.     public String generateToken(UserDetails userDetails) {
63.         Map<String, Object> claims = new HashMap<>();
64.         return doGenerateToken(claims, userDetails.getUsername());
65.     }
67.     private String doGenerateToken(Map<String, Object> claims, String subject) {
68.         return Jwts.builder()
69.                 .setClaims(claims)
70.                 .setSubject(subject)
71.                 .setIssuedAt(new Date(System.currentTimeMillis()))
72.                 .setExpiration(new Date(System.currentTimeMillis() + expiration * 1000))
73.                 .signWith(getSigningKey(), SignatureAlgorithm.HS256)
74.                 .compact();
75.     }
77.     // 验证令牌
78.     public Boolean validateToken(String token, UserDetails userDetails) {
79.         final String username = getUsernameFromToken(token);
80.         return (username.equals(userDetails.getUsername()) && !isTokenExpired(token));
81.     }
82. }

复制代码

2. 创建JWT认证过滤器

接下来，创建一个JWT认证过滤器，用于拦截请求并验证JWT令牌。

2. import org.springframework.security.authentication.UsernamePasswordAuthenticationToken;
3. import org.springframework.security.core.context.SecurityContextHolder;
4. import org.springframework.security.core.userdetails.UserDetails;
5. import org.springframework.security.core.userdetails.UserDetailsService;
6. import org.springframework.security.web.authentication.WebAuthenticationDetailsSource;
7. import org.springframework.stereotype.Component;
8. import org.springframework.web.filter.OncePerRequestFilter;
10. import javax.servlet.FilterChain;
11. import javax.servlet.ServletException;
12. import javax.servlet.http.HttpServletRequest;
13. import javax.servlet.http.HttpServletResponse;
14. import java.io.IOException;
16. @Component
17. public class JwtAuthenticationFilter extends OncePerRequestFilter {
19.     private final UserDetailsService userDetailsService;
20.     private final JwtTokenUtil jwtTokenUtil;
22.     public JwtAuthenticationFilter(UserDetailsService userDetailsService, JwtTokenUtil jwtTokenUtil) {
23.         this.userDetailsService = userDetailsService;
24.         this.jwtTokenUtil = jwtTokenUtil;
25.     }
27.     @Override
28.     protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain chain)
29.             throws ServletException, IOException {
30.         
31.         final String requestTokenHeader = request.getHeader("Authorization");
33.         String username = null;
34.         String jwtToken = null;
36.         // 检查请求头中是否有JWT令牌
37.         if (requestTokenHeader != null && requestTokenHeader.startsWith("Bearer ")) {
38.             jwtToken = requestTokenHeader.substring(7);
39.             try {
40.                 username = jwtTokenUtil.getUsernameFromToken(jwtToken);
41.             } catch (Exception e) {
42.                 logger.error("Unable to get JWT Token", e);
43.             }
44.         }
46.         // 验证令牌
47.         if (username != null && SecurityContextHolder.getContext().getAuthentication() == null) {
48.             UserDetails userDetails = this.userDetailsService.loadUserByUsername(username);
50.             if (jwtTokenUtil.validateToken(jwtToken, userDetails)) {
51.                 UsernamePasswordAuthenticationToken authentication = new UsernamePasswordAuthenticationToken(
52.                         userDetails, null, userDetails.getAuthorities());
53.                 authentication.setDetails(new WebAuthenticationDetailsSource().buildDetails(request));
54.                 SecurityContextHolder.getContext().setAuthentication(authentication);
55.             }
56.         }
57.         
58.         chain.doFilter(request, response);
59.     }
60. }

复制代码

3. 配置Spring Security

现在，我们需要配置Spring Security以使用JWT进行身份验证。

2. import org.springframework.context.annotation.Bean;
3. import org.springframework.context.annotation.Configuration;
4. import org.springframework.security.authentication.AuthenticationManager;
5. import org.springframework.security.config.annotation.authentication.builders.AuthenticationManagerBuilder;
6. import org.springframework.security.config.annotation.method.configuration.EnableGlobalMethodSecurity;
7. import org.springframework.security.config.annotation.web.builders.HttpSecurity;
8. import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
9. import org.springframework.security.config.annotation.web.configuration.WebSecurityConfigurerAdapter;
10. import org.springframework.security.config.http.SessionCreationPolicy;
11. import org.springframework.security.core.userdetails.UserDetailsService;
12. import org.springframework.security.crypto.bcrypt.BCryptPasswordEncoder;
13. import org.springframework.security.crypto.password.PasswordEncoder;
14. import org.springframework.security.web.authentication.UsernamePasswordAuthenticationFilter;
16. @Configuration
17. @EnableWebSecurity
18. @EnableGlobalMethodSecurity(prePostEnabled = true)
19. public class SecurityConfig extends WebSecurityConfigurerAdapter {
21.     private final UserDetailsService userDetailsService;
22.     private final JwtAuthenticationFilter jwtAuthenticationFilter;
24.     public SecurityConfig(UserDetailsService userDetailsService, JwtAuthenticationFilter jwtAuthenticationFilter) {
25.         this.userDetailsService = userDetailsService;
26.         this.jwtAuthenticationFilter = jwtAuthenticationFilter;
27.     }
29.     @Override
30.     protected void configure(AuthenticationManagerBuilder auth) throws Exception {
31.         auth.userDetailsService(userDetailsService).passwordEncoder(passwordEncoder());
32.     }
34.     @Bean
35.     public PasswordEncoder passwordEncoder() {
36.         return new BCryptPasswordEncoder();
37.     }
39.     @Bean
40.     @Override
41.     public AuthenticationManager authenticationManagerBean() throws Exception {
42.         return super.authenticationManagerBean();
43.     }
45.     @Override
46.     protected void configure(HttpSecurity http) throws Exception {
47.         http.csrf().disable()
48.             .authorizeRequests()
49.             .antMatchers("/api/authenticate", "/api/register", "/v2/api-docs", "/configuration/**", "/swagger*/**", "/webjars/**").permitAll()
50.             .anyRequest().authenticated()
51.             .and()
52.             .exceptionHandling()
53.             .and()
54.             .sessionManagement()
55.             .sessionCreationPolicy(SessionCreationPolicy.STATELESS);
56.         
57.         http.addFilterBefore(jwtAuthenticationFilter, UsernamePasswordAuthenticationFilter.class);
58.     }
59. }

复制代码

4. 创建认证控制器

创建一个控制器，用于处理用户认证和生成JWT令牌。

2. import org.springframework.beans.factory.annotation.Autowired;
3. import org.springframework.http.ResponseEntity;
4. import org.springframework.security.authentication.AuthenticationManager;
5. import org.springframework.security.authentication.BadCredentialsException;
6. import org.springframework.security.authentication.DisabledException;
7. import org.springframework.security.authentication.UsernamePasswordAuthenticationToken;
8. import org.springframework.security.core.userdetails.UserDetails;
9. import org.springframework.web.bind.annotation.PostMapping;
10. import org.springframework.web.bind.annotation.RequestBody;
11. import org.springframework.web.bind.annotation.RequestMapping;
12. import org.springframework.web.bind.annotation.RestController;
14. @RestController
15. @RequestMapping("/api")
16. public class AuthenticationController {
18.     private final AuthenticationManager authenticationManager;
19.     private final JwtTokenUtil jwtTokenUtil;
20.     private final UserDetailsService userDetailsService;
22.     @Autowired
23.     public AuthenticationController(AuthenticationManager authenticationManager,
24.                                    JwtTokenUtil jwtTokenUtil,
25.                                    UserDetailsService userDetailsService) {
26.         this.authenticationManager = authenticationManager;
27.         this.jwtTokenUtil = jwtTokenUtil;
28.         this.userDetailsService = userDetailsService;
29.     }
31.     @PostMapping("/authenticate")
32.     public ResponseEntity<?> createAuthenticationToken(@RequestBody AuthenticationRequest authenticationRequest) throws Exception {
33.         try {
34.             authenticationManager.authenticate(new UsernamePasswordAuthenticationToken(
35.                     authenticationRequest.getUsername(), authenticationRequest.getPassword()));
36.         } catch (DisabledException e) {
37.             throw new Exception("USER_DISABLED", e);
38.         } catch (BadCredentialsException e) {
39.             throw new Exception("INVALID_CREDENTIALS", e);
40.         }
41.         
42.         final UserDetails userDetails = userDetailsService.loadUserByUsername(authenticationRequest.getUsername());
43.         final String jwt = jwtTokenUtil.generateToken(userDetails);
44.         
45.         return ResponseEntity.ok(new AuthenticationResponse(jwt));
46.     }
47. }
49. // 请求和响应DTO
50. class AuthenticationRequest {
51.     private String username;
52.     private String password;
53.    
54.     // Getters and Setters
55.     public String getUsername() {
56.         return username;
57.     }
58.    
59.     public void setUsername(String username) {
60.         this.username = username;
61.     }
62.    
63.     public String getPassword() {
64.         return password;
65.     }
66.    
67.     public void setPassword(String password) {
68.         this.password = password;
69.     }
70. }
72. class AuthenticationResponse {
73.     private String jwt;
74.    
75.     public AuthenticationResponse(String jwt) {
76.         this.jwt = jwt;
77.     }
78.    
79.     // Getter
80.     public String getJwt() {
81.         return jwt;
82.     }
83. }

复制代码

5. 配置Swagger

现在，让我们配置Swagger以支持JWT身份验证。

2. import org.springframework.context.annotation.Bean;
3. import org.springframework.context.annotation.Configuration;
4. import springfox.documentation.builders.ApiInfoBuilder;
5. import springfox.documentation.builders.PathSelectors;
6. import springfox.documentation.builders.RequestHandlerSelectors;
7. import springfox.documentation.service.*;
8. import springfox.documentation.spi.DocumentationType;
9. import springfox.documentation.spi.service.contexts.SecurityContext;
10. import springfox.documentation.spring.web.plugins.Docket;
12. import java.util.Arrays;
13. import java.util.Collections;
14. import java.util.List;
16. @Configuration
17. public class SwaggerConfig {
19.     @Bean
20.     public Docket api() {
21.         return new Docket(DocumentationType.SWAGGER_2)
22.                 .select()
23.                 .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
24.                 .paths(PathSelectors.any())
25.                 .build()
26.                 .apiInfo(apiInfo())
27.                 .securitySchemes(Arrays.asList(apiKey()))
28.                 .securityContexts(Collections.singletonList(securityContext()));
29.     }
31.     private ApiInfo apiInfo() {
32.         return new ApiInfoBuilder()
33.                 .title("API with JWT Authentication")
34.                 .description("Spring Boot REST API with JWT Authentication")
35.                 .version("1.0")
36.                 .contact(new Contact("Your Name", "www.example.com", "your.email@example.com"))
37.                 .build();
38.     }
40.     private ApiKey apiKey() {
41.         return new ApiKey("JWT", "Authorization", "header");
42.     }
44.     private SecurityContext securityContext() {
45.         return SecurityContext.builder()
46.                 .securityReferences(defaultAuth())
47.                 .forPaths(PathSelectors.regex("/api/.*"))
48.                 .build();
49.     }
51.     private List<SecurityReference> defaultAuth() {
52.         AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
53.         AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
54.         authorizationScopes[0] = authorizationScope;
55.         return Collections.singletonList(new SecurityReference("JWT", authorizationScopes));
56.     }
57. }

复制代码

2. import io.swagger.v3.oas.models.Components;
3. import io.swagger.v3.oas.models.OpenAPI;
4. import io.swagger.v3.oas.models.info.Contact;
5. import io.swagger.v3.oas.models.info.Info;
6. import io.swagger.v3.oas.models.info.License;
7. import io.swagger.v3.oas.models.security.SecurityRequirement;
8. import io.swagger.v3.oas.models.security.SecurityScheme;
9. import org.springframework.context.annotation.Bean;
10. import org.springframework.context.annotation.Configuration;
12. @Configuration
13. public class OpenApiConfig {
15.     private static final String SECURITY_SCHEME_NAME = "Bearer Token";
17.     @Bean
18.     public OpenAPI customOpenAPI() {
19.         return new OpenAPI()
20.                 .info(new Info()
21.                         .title("API with JWT Authentication")
22.                         .version("1.0")
23.                         .description("Spring Boot REST API with JWT Authentication")
24.                         .contact(new Contact()
25.                                 .name("Your Name")
26.                                 .url("www.example.com")
27.                                 .email("your.email@example.com"))
28.                         .license(new License()
29.                                 .name("Apache 2.0")
30.                                 .url("http://springdoc.org")))
31.                 .addSecurityItem(new SecurityRequirement().addList(SECURITY_SCHEME_NAME))
32.                 .components(new Components()
33.                         .addSecuritySchemes(SECURITY_SCHEME_NAME,
34.                                 new SecurityScheme()
35.                                         .name(SECURITY_SCHEME_NAME)
36.                                         .type(SecurityScheme.Type.HTTP)
37.                                         .scheme("bearer")
38.                                         .bearerFormat("JWT")));
39.     }
40. }

复制代码

6. 创建示例API控制器

创建一个示例API控制器，用于演示JWT身份验证的保护效果。

2. import org.springframework.http.ResponseEntity;
3. import org.springframework.security.access.prepost.PreAuthorize;
4. import org.springframework.web.bind.annotation.GetMapping;
5. import org.springframework.web.bind.annotation.RequestMapping;
6. import org.springframework.web.bind.annotation.RestController;
8. @RestController
9. @RequestMapping("/api")
10. public class DemoController {
12.     @GetMapping("/public")
13.     public ResponseEntity<String> publicEndpoint() {
14.         return ResponseEntity.ok("This is a public endpoint that anyone can access.");
15.     }
17.     @GetMapping("/user")
18.     @PreAuthorize("hasRole('USER') or hasRole('ADMIN')")
19.     public ResponseEntity<String> userEndpoint() {
20.         return ResponseEntity.ok("This is a user endpoint that requires USER or ADMIN role.");
21.     }
23.     @GetMapping("/admin")
24.     @PreAuthorize("hasRole('ADMIN')")
25.     public ResponseEntity<String> adminEndpoint() {
26.         return ResponseEntity.ok("This is an admin endpoint that requires ADMIN role.");
27.     }
28. }

复制代码

7. 配置应用程序属性

在application.properties或application.yml文件中添加JWT相关配置：

2. # JWT Configuration
3. jwt.secret=mySecretKey
4. jwt.expiration=86400

复制代码

或使用YAML格式：

2. # JWT Configuration
3. jwt:
4.   secret: mySecretKey
5.   expiration: 86400

复制代码

实践案例

现在，让我们通过一个完整的示例项目来演示如何在Swagger中实现JWT身份验证。

项目结构

2. src/main/java/com/example/demo/
3. ├── config/
4. │   ├── SecurityConfig.java
5. │   ├── SwaggerConfig.java
6. │   └── OpenApiConfig.java (for Spring Boot 3.x)
7. ├── controller/
8. │   ├── AuthenticationController.java
9. │   └── DemoController.java
10. ├── filter/
11. │   └── JwtAuthenticationFilter.java
12. ├── model/
13. │   ├── AuthenticationRequest.java
14. │   └── AuthenticationResponse.java
15. ├── security/
16. │   └── JwtTokenUtil.java
17. ├── service/
18. │   └── UserDetailsServiceImpl.java
19. └── DemoApplication.java

复制代码

用户详情服务实现

2. import org.springframework.security.core.authority.SimpleGrantedAuthority;
3. import org.springframework.security.core.userdetails.User;
4. import org.springframework.security.core.userdetails.UserDetails;
5. import org.springframework.security.core.userdetails.UserDetailsService;
6. import org.springframework.security.core.userdetails.UsernameNotFoundException;
7. import org.springframework.stereotype.Service;
9. import java.util.Collections;
11. @Service
12. public class UserDetailsServiceImpl implements UserDetailsService {
14.     @Override
15.     public UserDetails loadUserByUsername(String username) throws UsernameNotFoundException {
16.         // 在实际应用中，这里应该从数据库或其他存储中获取用户信息
17.         // 这里我们使用硬编码的用户信息作为示例
18.         if ("user".equals(username)) {
19.             return new User("user", "$2a$10$slYQmyNdGzTn7ZLBXBChFOC9f6kFjAqPhccnP6DxlWXx2lPk1C3G6",
20.                     Collections.singletonList(new SimpleGrantedAuthority("ROLE_USER")));
21.         } else if ("admin".equals(username)) {
22.             return new User("admin", "$2a$10$slYQmyNdGzTn7ZLBXBChFOC9f6kFjAqPhccnP6DxlWXx2lPk1C3G6",
23.                     Collections.singletonList(new SimpleGrantedAuthority("ROLE_ADMIN")));
24.         } else {
25.             throw new UsernameNotFoundException("User not found with username: " + username);
26.         }
27.     }
28. }

复制代码

主应用程序类

2. import org.springframework.boot.SpringApplication;
3. import org.springframework.boot.autoconfigure.SpringBootApplication;
5. @SpringBootApplication
6. public class DemoApplication {
7.     public static void main(String[] args) {
8.         SpringApplication.run(DemoApplication.class, args);
9.     }
10. }

复制代码

运行和测试

1. 启动应用程序
2. 访问Swagger UI：http://localhost:8080/swagger-ui.html(对于Springfox) 或http://localhost:8080/swagger-ui.html(对于SpringDoc)
3. 在Swagger UI界面中，您会看到一个”Authorize”按钮，点击它
4. 在弹出的对话框中，输入JWT令牌（格式为Bearer <your_jwt_token>）
5. 现在，您可以测试受保护的API端点了

首先，使用/api/authenticate端点获取JWT令牌：

2. {
3.   "username": "user",
4.   "password": "password"
5. }

复制代码

响应将包含JWT令牌：

2. {
3.   "jwt": "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJ1c2VyIiwiaWF0IjoxNjE2MjM5MDI2LCJleHAiOjE2MTYzMjU0MjZ9.5Q5WZsKc8vZrI5iL_2iX5yV5x5g5h5j5k5l5m5n5o5p"
4. }

复制代码

复制这个令牌，然后在Swagger UI的”Authorize”对话框中输入Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJ1c2VyIiwiaWF0IjoxNjE2MjM5MDI2LCJleHAiOjE2MTYzMjU0MjZ9.5Q5WZsKc8vZrI5iL_2iX5yV5x5g5h5j5k5l5m5n5o5p。

现在，您可以测试受保护的端点，如/api/user和/api/admin。

常见问题及解决方案

1. JWT令牌过期问题

问题：JWT令牌有一定的有效期，过期后需要重新获取。

解决方案：

• 实现令牌刷新机制，允许用户使用过期的令牌获取新的令牌。
• 在客户端实现令牌过期检测和自动刷新逻辑。

2. // 在JwtTokenUtil类中添加刷新令牌的方法
3. public String refreshToken(String token) {
4.     final Date createdDate = new Date();
5.     final Date expirationDate = calculateExpirationDate(createdDate);
6.    
7.     final Claims claims = getAllClaimsFromToken(token);
8.     claims.setIssuedAt(createdDate);
9.     claims.setExpiration(expirationDate);
10.    
11.     return Jwts.builder()
12.             .setClaims(claims)
13.             .signWith(getSigningKey(), SignatureAlgorithm.HS256)
14.             .compact();
15. }
17. private Date calculateExpirationDate(Date createdDate) {
18.     return new Date(createdDate.getTime() + expiration * 1000);
19. }

复制代码

2. Swagger UI无法显示

问题：访问Swagger UI时出现404错误。

解决方案：

• 确保已正确添加Swagger依赖。
• 检查Spring Security配置，确保允许访问Swagger相关路径。

2. @Override
3. protected void configure(HttpSecurity http) throws Exception {
4.     http.csrf().disable()
5.         .authorizeRequests()
6.         .antMatchers("/api/authenticate", "/api/register",
7.                      "/v2/api-docs", "/configuration/**",
8.                      "/swagger*/**", "/webjars/**").permitAll()
9.         .anyRequest().authenticated()
10.         .and()
11.         // ... 其他配置
12. }

复制代码

3. JWT令牌验证失败

问题：即使提供了有效的JWT令牌，API请求仍然返回401未授权错误。

解决方案：

• 检查JWT令牌是否正确添加到请求头中，格式应为Bearer <token>。
• 确保JWT令牌未过期。
• 检查服务器端的JWT验证逻辑，确保密钥和算法匹配。

2. // 在JwtAuthenticationFilter中添加调试日志
3. @Override
4. protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain chain)
5.         throws ServletException, IOException {
6.    
7.     final String requestTokenHeader = request.getHeader("Authorization");
8.    
9.     logger.debug("Authorization Header: " + requestTokenHeader);
10.    
11.     // ... 其余代码
12. }

复制代码

4. 角色权限不生效

问题：即使用户具有特定角色，访问需要该角色的端点时仍然被拒绝。

解决方案：

• 确保在用户详情服务中正确设置了用户角色。
• 检查角色名称是否以ROLE_前缀开头，这是Spring Security的默认要求。
• 确保在控制器上正确使用了@PreAuthorize注解。

2. // 在UserDetailsServiceImpl中确保角色名称正确
3. return new User("admin", "$2a$10$slYQmyNdGzTn7ZLBXBChFOC9f6kFjAqPhccnP6DxlWXx2lPk1C3G6",
4.         Collections.singletonList(new SimpleGrantedAuthority("ROLE_ADMIN")));

复制代码

最佳实践和安全性建议

1. 使用HTTPS

始终使用HTTPS来保护API通信，防止JWT令牌被中间人攻击截获。

2. 设置合理的令牌过期时间

根据应用的安全需求，设置合理的JWT令牌过期时间。对于高安全性要求的应用，可以使用较短的过期时间（如30分钟），并实现令牌刷新机制。

3. 使用强密钥

使用足够长且随机的密钥来签名JWT令牌。避免使用简单或可预测的密钥。

2. # 使用至少256位（32字节）的随机密钥
3. jwt.secret=5A7B3C9D2E4F6A8B1C3D5E7F9A2B4C6D8E1F3A5B7C9D2E4F6A8B1C3D5E7F9A

复制代码

4. 实现令牌撤销机制

虽然JWT是无状态的，但在某些情况下（如用户注销或令牌泄露），您可能需要实现令牌撤销机制。这可以通过维护令牌黑名单来实现。

2. @Component
3. public class JwtTokenBlacklist {
4.     private final Set<String> blacklist = ConcurrentHashMap.newKeySet();
5.    
6.     public void addToBlacklist(String token) {
7.         blacklist.add(token);
8.     }
9.    
10.     public boolean isBlacklisted(String token) {
11.         return blacklist.contains(token);
12.     }
13. }

复制代码

5. 限制登录尝试

实现登录尝试限制，防止暴力破解攻击。

2. import org.springframework.context.event.EventListener;
3. import org.springframework.security.authentication.event.AuthenticationFailureBadCredentialsEvent;
4. import org.springframework.stereotype.Component;
6. import java.util.HashMap;
7. import java.util.Map;
8. import java.util.concurrent.atomic.AtomicInteger;
10. @Component
11. public class AuthenticationFailureListener {
12.    
13.     private final Map<String, AtomicInteger> failedAttempts = new HashMap<>();
14.     private final int MAX_ATTEMPTS = 5;
15.    
16.     @EventListener
17.     public void authenticationFailed(AuthenticationFailureBadCredentialsEvent event) {
18.         String username = event.getAuthentication().getName();
19.         failedAttempts.computeIfAbsent(username, k -> new AtomicInteger(0)).incrementAndGet();
20.         
21.         if (failedAttempts.get(username).get() >= MAX_ATTEMPTS) {
22.             // 锁定账户或采取其他安全措施
23.             // 例如，可以设置一个标志，在UserDetailsService中检查该标志
24.         }
25.     }
26. }

复制代码

6. 定期更新依赖

定期更新Spring Security、JWT库和其他相关依赖，以获取最新的安全修复和功能改进。

7. 敏感信息不要存储在JWT中

避免在JWT载荷中存储敏感信息，如密码、信用卡号等。JWT只是Base64编码的，不是加密的，可以被任何人解码。

8. 使用适当的算法

使用强签名算法（如HS256或RS256）来签名JWT令牌。避免使用无签名算法（如”none”）。

总结

在本文中，我们详细介绍了如何在Swagger中实现JWT身份验证，以保护API接口的安全。我们从基础概念开始，逐步引导您完成了整个配置过程，并通过实际案例展示了如何实现这一安全机制。

主要内容包括：

1. 介绍了Swagger和JWT的基本概念及其在API安全中的重要性。
2. 准备了必要的环境和依赖。
3. 详细说明了如何创建JWT工具类、认证过滤器和Spring Security配置。
4. 展示了如何在Swagger中配置JWT身份验证。
5. 提供了一个完整的示例项目，包括用户认证、API保护和Swagger文档集成。
6. 讨论了常见问题及其解决方案。
7. 分享了最佳实践和安全性建议。

通过遵循本文中的步骤和建议，您可以轻松地在Swagger中实现JWT身份验证，为您的API接口提供强大的安全保障。这不仅有助于保护您的API免受未授权访问，还能提供更好的开发者体验，使API文档更加完整和易于使用。

希望本文对您有所帮助，祝您在API开发中取得成功！