[Etc] Swagger JWT 인증 설정

 

Swagger를 잘 사용하다가 추후 JWT 인증 방식을 적용하면 Token 정보가 없어 401 Unauthorized 에러가 난다.

단순히 Controller 메소드에서 JWT Token을 받는 방법이 있지만, 모든 메소드에 추가하는 건 코드의 양과 가독성이 나빠져서 정말 비효율적인 코딩이 된다. 또한 Interceptor에서 JWT 인증에 대한 검사를 한다면 위에 언급한 방법은 무용지물이 된다.

 

인증 설정

Swagger 2.9.2부터 Authorize를 지원한다. Swagger Configuration 설정을 통해 Swagger GUI에서 간단하게 인증을 등록할 수 있다.

Authorize 버튼을 눌러보면 Swagger Configuration에서 설정한 정보를 바탕으로 값을 셋팅을 할 수 있다. 설정이 완료되면 Swagger의 모든 API는 JWT_TOKEN에 대한 인증정보를 기본적으로 가지고 API요청을 하게 된다.

 

Swagger Configuration

@Configuration
@EnableSwagger2
public class SwaggerConfiguration {
	
    @Bean
    public Docket swaggerSpringfoxDocket() {
    	
		Docket docket = new Docket(DocumentationType.SWAGGER_2)
				.apiInfo(apiInfo())
				.pathMapping("/")
				.forCodeGeneration(true)
				.genericModelSubstitutes(ResponseEntity.class)
				.ignoredParameterTypes(java.sql.Date.class)
				.securityContexts(Lists.newArrayList(securityContext()))
				.securitySchemes(Lists.newArrayList(authorizationKey(), httpRequestKey()))
				.useDefaultResponseMessages(false);
		
		docket = docket
				.select()
				.apis(RequestHandlerSelectors.basePackage("com.tistory.reference.api"))
				.paths(PathSelectors.any()).build();
		
		return docket;
    }

    /**
     * apiInfo
     * 
     * @return
     */
    private ApiInfo apiInfo() {

        return new ApiInfo(
                "reference-m1 System",           // Title
                "reference-m1 System APIs",      // Description
                "v1.0",                          // Version
                "",                              // termsOfServiceUrl
                new Contact("reference", "",""), // contact (Name, Url, Email)
                "",                              // license
                "",                              // licenseUrl
                Collections.emptyList());
    }
    
	/**
	 * authorizationKey
	 * 
	 * @return
	 */
	private ApiKey authorizationKey() {
		return new ApiKey("JWT_TOKEN", ServiceConstant.AUTHORIZATION_KEY, "header");
	}
	
	/**
	 * httpRequestKey
	 * 
	 * @return
	 */
	private ApiKey httpRequestKey() {
		return new ApiKey("HTTP_REQUEST", ServiceConstant.X_REQUESTED_WITH_KEY, "header");
	}
	
	/**
	 * securityContext
	 * 
	 * @return
	 */
	private springfox.documentation.spi.service.contexts.SecurityContext securityContext() {
		
		return springfox.documentation.spi.service.contexts.SecurityContext.builder()
				.securityReferences(defaultAuth())
				.forPaths(PathSelectors.any())
				.build();
	}
	
	/**
	 * defaultAuth
	 * 
	 * @return
	 */
	private List<SecurityReference> defaultAuth() {

		AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
		AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
		authorizationScopes[0] = authorizationScope;
		
		return Lists.newArrayList(new SecurityReference("JWT_TOKEN", authorizationScopes),
				new SecurityReference("HTTP_REQUEST", authorizationScopes));
	}

Swagger를 구성할때 기존에 설정한 정보에 JWT_TOKEN에 대한 소스만 추가하여 수정하면 된다.

필자는 JWT_TOKEN이외에 추가적인 인증이 있어서 2개를 기본 인증으로 설정하였다. JWT_TOKEN만 사용한다면 HTTP_REQUEST에 대한 부분을 삭제하고 사용하시면 된다.

눈여겨봐야 할 부분은 authorizationKey(), securityContext(), deaultAuth() 함수이다. 또한 SpringSecurity 또는 Interceptor를 사용한다면 Swagger관련 Path를 제외시켜야 한다.

/**
 * WebSecurity ignore
 */
@Override public void configure(WebSecurity web) {
	web.ignoring().antMatchers("/swagger/**", "/swagger-ui.html", "/swagger-resources/**", "/webjars/**", "/v2/api-docs");
}

/**
* url Interceptor
*/
@Override
public void addInterceptors(InterceptorRegistry registry) {

    registry.addInterceptor(authenticationInterceptor())
        .addPathPatterns("/**")
        .excludePathPatterns("/")
        .excludePathPatterns("/swagger/**")
        .excludePathPatterns("/swagger-ui.html")
        .excludePathPatterns("/swagger-resources/**")
        .excludePathPatterns("/webjars/**")
        .excludePathPatterns("/v2/api-docs");
}