在Linux上实现Swagger的安全认证,通常涉及到对API文档访问权限的控制,确保只有经过认证的用户才能查看或操作API文档。这可以通过多种方式实现,例如使用基本认证、OAuth2、JWT等。以下是基于Spring Boot和Springdoc(用于生成OpenAPI文档的工具)实现安全认证的一些步骤:
首先,需要在你的Spring Boot项目中引入springdoc-openapi-starter-webmvc-ui
依赖,这是Springdoc提供的用于集成Swagger UI和OpenAPI文档的工具。
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
<version>2.1.0</version>
</dependency>
Springdoc支持多种认证机制,包括OAuth2和JWT。以下是一个基本的配置示例,展示如何在Spring Boot应用中启用OAuth2认证:
import io.swagger.v3.oas.annotations.security.Security;
import io.swagger.v3.oas.annotations.security.SecurityRequirement;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
@Configuration
@Security(name = "oauth2", securitySchemes = {
@SecurityScheme(name = "oauth2", type = SecurityScheme.Type.OAUTH2, flows = {
@SecurityFlow(name = "authorizationCode", authorizationUrl = "/oauth/authorize", tokenUrl = "/oauth/token")
})
})
public class SecurityConfig {
@Bean
public SecurityRequirement securityRequirement() {
return new SecurityRequirement().securitySchemes(Collections.singletonList(securityScheme())).securityContexts(Collections.singletonList(securityContext()));
}
@Bean
public SecurityScheme securityScheme() {
return new OAuth("oauth2", Collections.singletonList(new AuthorizationScope("read", "read access")), Collections.singletonList(new GrantType("authorization_code", new AuthorizationCodeUrl("/oauth/authorize"), new TokenUrl("/oauth/token"))));
}
@Bean
public SecurityContext securityContext() {
return SecurityContext.builder()
.securityReferences(defaultAuth())
.forPaths(PathSelectors.any())
.build();
}
private List<AuthorizationScope> defaultAuth() {
return Collections.singletonList(new AuthorizationScope("read", "read access"));
}
}
在application.properties
文件中,可以配置OAuth2相关的参数,例如客户端ID和客户端密钥:
springdoc.security.oauth2.client-id=your-client-id
springdoc.security.oauth2.client-secret=your-client-secret
springdoc.security.oauth2.token-url=/oauth/token
配置完成后,访问Swagger UI时,系统会提示用户进行认证。用户需要先通过OAuth2授权流程获取访问令牌,然后在Swagger UI中使用该令牌进行认证。
除了OAuth2,还可以使用JWT进行认证。JWT通常与Spring Security结合使用,可以在控制器方法上添加安全注解来保护API:
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
@RestController
@RequestMapping("/api")
@Tag(name = "Protected API")
public class ProtectedController {
@GetMapping("/secure")
public String secureEndpoint() {
return "This is a secure endpoint";
}
}
在Spring Security配置中,需要添加对Swagger UI端点的保护:
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
import org.springframework.security.config.annotation.web.configuration.WebSecurityConfigurerAdapter;
import org.springframework.security.oauth.jwt.JwtDecoder;
import org.springframework.security.oauth.jwt.NimbusJwtDecoder;
@Configuration
@EnableWebSecurity
public class SecurityConfig extends WebSecurityConfigurerAdapter {
@Override
protected void configure(HttpSecurity http) throws Exception {
http
.authorizeRequests(authorizeRequests ->
authorizeRequests
.antMatchers("/swagger-ui/**", "/v2/api-docs/**").permitAll()
.anyRequest().authenticated()
)
.oauth2ResourceServer(oauth2 ->
oauth2
.jwt(jwt ->
jwt.decoder(jwtDecoder())
)
);
}
@Bean
public JwtDecoder jwtDecoder() {
return NimbusJwtDecoder.withJwkSetUri("https://your-auth-server/.well-known/jwks.json").build();
}
}
通过上述步骤,可以在Linux系统上使用Swagger实现安全认证,确保API文档的访问受到保护。