[Spring] Swagger3.0 버전 Authorize button 설정

인증(Authentication), 인가(Authorization)에 대해 설명드리겠습니다.

인증은 클라이언트 측에서 서버 측으로 요청한 사용자 정보가 올바른지 확인하는 과정입니다. (Login)

인가는 요청에 대한 권한이 있는지 판단하는 과정입니다. 만약 클라이언트의 요청에 대한 권한이 없다는 경우, HTTP 403(Forbidden) 상태 코드를 반환하게 됩니다.

 

클라이언트는 서버로부터 전달받은 토큰을 관리하며, Authorization Header에 Jwt 토큰을 담아 관리하게 됩니다. Postman과 같은 툴에서는 서버로 요청을 보낼 때, 매번 Bearer Token에 토큰 정보를 담아줘야 하는 불편함이 있습니다. 하지만, Swagger에서 Authorize 버튼에 관련한 설정을 활성화시킨다면 Authorization Header에 담아둔 Token 값을 모든 요청 시에 담을 수 있는 편리함을 느낄 수 있게 됩니다.

 

<코드>

HeaderReaderController 

@RestController
public class HeaderReaderController {

    @Operation(summary = "API Operation", security = {@SecurityRequirement(name = "Authorization")})
    @GetMapping("/api")
    public Response authHeaderChecker(HttpServletRequest request) {
        String authorizationHeaderValue = request.getHeader("Authorization");
        Map<String, String> result = new HashMap<>();
        result.put("Authorization", authorizationHeaderValue);
        return Response.success(result);
    }
}

/api 경로로 이루어진 모든 HTTP 요청에 클라이언트가 처음으로 받은 Access Token 값을 Authorization Header에 담을 수 있는 로직입니다. 

 

SwaggerConfig 설정

@Configuration
@OpenAPIDefinition(info = @Info(title = "HandOver API", version = "v3"),
        security = {@SecurityRequirement(name = "Authorization")}
)
@SecurityScheme(
        name = "Authorization",
        type = SecuritySchemeType.HTTP,
        bearerFormat = "JWT",
        scheme = "bearer",
        in = SecuritySchemeIn.HEADER
)
// http://localhost:8080/swagger-ui/index.html
public class SwaggerConfig {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.OAS_30)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.handoverbackend.controller"))
                .paths(PathSelectors.any())
                .build()
                .securityContexts(Arrays.asList(securityContext()))
                .securitySchemes(Arrays.asList(bearerAuthSecurityScheme()));
    }

    private HttpAuthenticationScheme bearerAuthSecurityScheme() {
        return HttpAuthenticationScheme.JWT_BEARER_BUILDER.name("Authorization").build(); 
    }
    private SecurityContext securityContext() {
        return SecurityContext.builder().securityReferences(defaultAuth()).build();
    }

    private List<SecurityReference> defaultAuth() {
        AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
        return List.of(new SecurityReference("Authorization", new AuthorizationScope[] {authorizationScope}));
    }
}

여기에서 가장 중요한 부분은 @SecurityRequirement 어노테이션입니다. 모든 http 요청에 Authorizattion 헤더값을 불러오기 위해 해당 어노테이션을 달아주었습니다. API와 보안에 대한 요구사항을 명시해주는 역할을 합니다. 

 

위의 설정을 통해, 다음과 같이 Authorize 버튼을 활성화 할 수 있게 되었고, Authorize 버튼에 Access Token을 등록해 주면 클라이언트가 HTTP 요청을 보낼 때 매번 Bearer Token 값을 넣어주지 않아도 됩니다. 

<참고 자료>

https://bugoverdose.github.io/development/swagger-auth-tutorial/

Swagger: JWT 인증 버튼 셋업