使用 Swagger UI 进行基本身份验证

Question

我正在尝试通过 Swagger UI 开发一个基于 spring-boot 的带有 API 文档的 Rest API 服务。我想通过 swagger UI 启用基本身份验证，以便用户只有在使用 swagger UI 上的授权按钮进行身份验证后才能运行 API（通过该按钮，将

"authorization: Basic XYZ

标头添加到 API 调用

在前端（在 Swagger UI 的 .json 文件中，我使用以下代码（根据文档）为所有 API 添加了基本身份验证：

"securityDefinitions": {
        "basic_auth": {
            "type": "basic"
        }
    },
    "security": [
        {
            "basic_auth": []
        }
    ]

我应该如何实现上述用例的后端逻辑（用户只有在使用 swagger UI 上的授权按钮进行身份验证后才能运行 API，否则在运行 API 时会显示 401 错误）

一些文档或示例代码会很有帮助

Answer 1

一种选择是使用浏览器弹出授权。

1. 当您为 Spring Boot 应用程序启用基本身份验证时，swagger ui 将自动使用浏览器的弹出窗口，以便将其用于基本身份验证。这意味着浏览器将保留发出请求的凭据，就像您尝试访问安全的 GET 端点时一样，直到您将其关闭为止。

现在，假设您不想使用上述内容，并且希望使用 swagger-ui 进行基本身份验证，正如您所说，您必须在 swagger-ui 上启用身份验证功能，并可以选择在访问 swagger-ui url 时添加安全异常。

2. 要启用 swagger UI 的基本身份验证功能（使用 UI 中的“授权按钮”），您必须为 Swagger Docket 设置安全上下文和方案（这是简化版本）：

   @Configuration
   @EnableSwagger2
   public class SwaggerConfig implements WebMvcConfigurer{
   
       @Bean
       public Docket api() {
           return new Docket(DocumentationType.SWAGGER_2)
                   .select()
                   .apis(RequestHandlerSelectors.any())
                   .paths(PathSelectors.any())
                   .build()
                   .securityContexts(Arrays.asList(securityContext()))
                   .securitySchemes(Arrays.asList(basicAuthScheme()));
      }
   
       private SecurityContext securityContext() {
           return SecurityContext.builder()
                   .securityReferences(Arrays.asList(basicAuthReference()))
                   .forPaths(PathSelectors.ant("/api/v1/**"))
                   .build();
       }
   
       private SecurityScheme basicAuthScheme() {
           return new BasicAuth("basicAuth");
       }
   
       private SecurityReference basicAuthReference() {
           return new SecurityReference("basicAuth", new AuthorizationScope[0]);
       }
   
   }
   

这将启用 ui 中的授权按钮。

现在您可能希望您的用户自由访问 swagger-ui 并使用此按钮进行授权。为此，您必须免除应用程序基本身份验证的招摇。此配置的一部分是安全配置，您必须添加以下代码：

public class SecurityConfig extends WebSecurityConfigurerAdapter{

    @Override
    protected void configure(HttpSecurity http) throws Exception {

            http
                .httpBasic()
                .and().sessionManagement().sessionCreationPolicy(SessionCreationPolicy.STATELESS)   
                .and().authorizeRequests()
                .antMatchers(
                        "/", "/csrf", 
                        "/v2/api-docs", 
                        "/swagger-resources/**",
                        "/swagger-ui.html",
                        "/webjars/**"
                        ).permitAll()
                .anyRequest().authenticated();

    }
}

Answer 2

我面临的一个类似问题是，当将 springfox 文档与 Swagger OAS 3.0 一起使用时，“身份验证”按钮不会出现在 swagger UI 上。

事实证明，针对这个问题创建了一个错误 -

https://github.com/springfox/springfox/issues/3518

问题的核心—— 类

BasicAuth

已弃用。

上面的错误报告中找到的解决方案是使用

HttpAuthenticationScheme

来定义 SecurityScheme 对象。

Docket 配置看起来像这样 -

return new Docket(DocumentationType.OAS_30)
                .groupName("Your_Group_name")
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.mypackage"))
                .paths(PathSelectors.regex("/.*"))
                .build().securitySchemes(Arrays.asList(HttpAuthenticationScheme.BASIC_AUTH_BUILDER.name("basicAuth").description("Basic authorization").build())) 
                .securityContexts(); //define security context for your app here

Answer 3

在 build.gradle 中使用以下依赖项来启用安全性：

"org.springframework.boot:spring-boot-starter-security"

在 application.properties 中，您可以使用以下方式定义自己的用户名和密码：

spring.security.user.name=user
spring.security.user.password=password

Answer 4

那些只想对端点进行基本身份验证的人应该执行 @Sifis 编写的所有操作，但需要将 antMatchers 更改为：

public class SecurityConfig extends WebSecurityConfigurerAdapter{

    @Override
    protected void configure(HttpSecurity http) throws Exception {

        http
            .httpBasic()            
            .and().sessionManagement().sessionCreationPolicy(SessionCreationPolicy.STATELESS)   
            .and().authorizeRequests()
            .antMatchers(
                    "/",
                    "/v2/api-docs/**",
                    "/v3/api-docs/**",
                    "/swagger-resources/**",
                    "/swagger-ui/**",
                    "/swagger-ui.html").permitAll()
            .anyRequest().authenticated();

    }
}

Answer 5

参考 - Spring Boot 3 + 基本身份验证 + Swagger
Spring Boot3 + 基本身份验证示例面临类似的问题。 必须进行以下更改。
1.白名单 Swagger URL。
创建 OpenAPI bean，指定我们将为 swagger 使用基本身份验证安全方案，如下 -

@Configuration
public class SwaggerConfig {

    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info().title("JavaInUse Authentication Service"))             
                .addSecurityItem(new SecurityRequirement().addList("JavaInUseSecurityScheme"))
                .components(new Components().addSecuritySchemes("JavaInUseSecurityScheme", new SecurityScheme()
                        .name("JavaInUseSecurityScheme").type(SecurityScheme.Type.HTTP).scheme("basic")));
    }
}