Spring Cloud Gateway에서 JWT 인증 필터 구현하기

🤔 왜 Gateway에서 인증을 처리했냐면

아키텍처를 MSA 로 변경하면서 인증을 어디서 할지 은근 고민이 많았다

각각 서비스에서 처리할지 게이트웨이에서 한 번에 처리할지;;;

 

마이크로서비스 아키텍처에서 인증 처리 위치는 크게 두 가지다:

방식	장점	단점
각 서비스에서 처리	서비스별 세밀한 제어	중복 코드, 인증 로직 산재
Gateway에서 처리	단일 진입점, 중앙 관리	Gateway 부하 집중

 

나는 Gateway에서 인증을 처리하는 방식을 선택했다.

왜냐면?

• 인증 로직 한 곳에서 관리
• 각 마이크로서비스는 비즈니스 로직에만 집중
• 인증 정책 변경 시 Gateway만 수정

---

🛠️ GlobalFilter로 인증 필터 만들기

Spring Cloud Gateway에서는 GlobalFilter를 구현하면 모든 요청에 대해 필터가 실행된다.

@Slf4j
@Component
public class JwtAuthenticationFilter implements GlobalFilter, Ordered {

    private final JwtTokenValidator jwtValidator;
    private final AntPathMatcher pathMatcher = new AntPathMatcher();

    @Value("${app.auth.enabled:true}")
    private boolean authEnabled;

    @Value("${app.auth.public-paths:}")
    private String publicPathsConfig;

    public JwtAuthenticationFilter(JwtTokenValidator jwtValidator) {
        this.jwtValidator = jwtValidator;
    }

    @Override
    public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
        ServerHttpRequest request = exchange.getRequest();
        String path = request.getPath().value();

        // 1. CORS Preflight 요청은 통과
        if (CorsUtils.isPreFlightRequest(request)) {
            return chain.filter(exchange);
        }

        // 2. 인증 비활성화 (개발 환경)
        if (!authEnabled) {
            return chain.filter(exchange);
        }

        // 3. 공개 경로는 인증 생략
        if (isPublicPath(path)) {
            log.debug("Public path - skip auth: {}", path);
            return chain.filter(exchange);
        }

        // 4. 토큰 추출
        String token = extractToken(request);
        if (!StringUtils.hasText(token)) {
            return sendUnauthorized(exchange, "No token provided");
        }

        // 5. 토큰 검증
        if (!jwtValidator.validateToken(token)) {
            return sendUnauthorized(exchange, "Invalid token");
        }

        // 6. 클레임 추출 → 다운스트림 서비스로 전달
        Claims claims = jwtValidator.getClaims(token);
        ServerHttpRequest modifiedRequest = addUserHeaders(request, claims);

        return chain.filter(exchange.mutate().request(modifiedRequest).build());
    }

    @Override
    public int getOrder() {
        return Ordered.HIGHEST_PRECEDENCE;  // 가장 먼저 실행
    }
}

핵심 포인트

1. GlobalFilter + Ordered: 모든 요청에 대해 필터 실행, 순서 제어
2. HIGHEST_PRECEDENCE: 다른 필터보다 먼저 실행되어야 인증이 의미 있음
3. WebFlux 기반: Mono<Void> 반환 (리액티브)

---

🔑 토큰 추출: 헤더 vs 쿠키

실무에서는 토큰이 여러 곳에 있을 수 있다:

• SPA: Authorization: Bearer xxx 헤더
• SSR/웹사이트: HttpOnly 쿠키

둘 다 지원하려면:

private String extractToken(ServerHttpRequest request) {
    // 1순위: Authorization 헤더
    String bearerToken = request.getHeaders().getFirst(HttpHeaders.AUTHORIZATION);
    if (StringUtils.hasText(bearerToken) && bearerToken.startsWith("Bearer ")) {
        return bearerToken.substring(7);
    }

    // 2순위: 쿠키
    HttpCookie cookie = request.getCookies().getFirst("access_token");
    if (cookie != null && StringUtils.hasText(cookie.getValue())) {
        return cookie.getValue();
    }

    return null;
}

💡 Tip: 쿠키를 사용하면 XSS 공격에 더 안전하다 (HttpOnly 설정 시).
다만 CSRF 공격에는 취약해지므로 CSRF 토큰을 함께 사용하자.

 

---

🚪 공개 경로 설정

로그인, 회원가입, 헬스체크 같은 API는 인증 없이 접근 가능해야 한다.

 

application.yml:

app:
  auth:
    enabled: true
    public-paths: >
      /api/auth/**,
      /api/public/**,
      /actuator/health,
      /swagger-ui/**,
      /v3/api-docs/**

 

필터에서 확인:

private boolean isPublicPath(String path) {
    if (!StringUtils.hasText(publicPathsConfig)) {
        return false;
    }

    List<String> publicPaths = Arrays.stream(publicPathsConfig.split(","))
            .map(String::trim)
            .filter(StringUtils::hasText)
            .toList();

    return publicPaths.stream()
            .anyMatch(pattern -> pathMatcher.match(pattern, path));
}

 

 

AntPathMatcher를 사용하면 /** 같은 와일드카드 패턴을 지원한다.

 

---

📤 다운스트림 서비스로 인증 정보 전달

Gateway에서 인증을 처리하면 다운스트림 서비스는 토큰을 다시 파싱할 필요가 없다.
HTTP 헤더로 사용자 정보를 전달하면 된다:

private ServerHttpRequest addUserHeaders(ServerHttpRequest request, Claims claims) {
    return request.mutate()
            .header("X-User-Id", claims.getSubject())
            .header("X-User-Name", claims.get("name", String.class))
            .header("X-User-Roles", String.join(",", getRoles(claims)))
            .header("X-Token-Issued-At", String.valueOf(claims.getIssuedAt().getTime()))
            .header("X-Token-Expiration", String.valueOf(claims.getExpiration().getTime()))
            .build();
}

 

다운스트림 서비스에서는 헤더만 읽으면 됨:

// 각 마이크로서비스에서
@GetMapping("/me")
public UserInfo getCurrentUser(
        @RequestHeader("X-User-Id") String userId,
        @RequestHeader("X-User-Name") String userName) {
    return new UserInfo(userId, userName);
}

 

---

🔄 토큰 자동 갱신 (Refresh Token)

Access Token이 곧 만료될 때 자동으로 갱신하면 UX가 좋아진다.

@Slf4j
@Component
public class TokenRefreshFilter implements GlobalFilter, Ordered {

    private final JwtTokenValidator jwtValidator;
    private final WebClient webClient;

    @Value("${app.auth.token-uri}")
    private String tokenUri;

    @Override
    public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
        String accessToken = extractAccessToken(exchange.getRequest());

        // Access Token이 5분 이내 만료 예정이면 갱신 시도
        if (StringUtils.hasText(accessToken) && jwtValidator.isExpiringSoon(accessToken)) {
            String refreshToken = extractRefreshToken(exchange.getRequest());

            if (StringUtils.hasText(refreshToken)) {
                return refreshTokens(refreshToken)
                        .flatMap(newTokens -> {
                            setTokenCookies(exchange.getResponse(), newTokens);
                            return chain.filter(exchange);
                        })
                        .onErrorResume(e -> {
                            log.warn("Token refresh failed: {}", e.getMessage());
                            return chain.filter(exchange);  // 실패해도 진행
                        });
            }
        }

        return chain.filter(exchange);
    }

    @Override
    public int getOrder() {
        return Ordered.HIGHEST_PRECEDENCE + 1;  // 인증 필터 다음에 실행
    }
}

갱신 로직 포인트

1. 만료 5분 전에 갱신: 요청 중 토큰 만료 방지
2. 실패해도 진행: 갱신 실패 시 기존 토큰으로 계속 (다음 요청에 401)
3. 쿠키로 새 토큰 전달: 클라이언트가 알아서 다음 요청에 사용

---

🚨 401 응답 처리

토큰이 없거나 유효하지 않으면 401을 반환한다:

private Mono<Void> sendUnauthorized(ServerWebExchange exchange, String message) {
    ServerHttpResponse response = exchange.getResponse();
    response.setStatusCode(HttpStatus.UNAUTHORIZED);
    response.getHeaders().add("X-Auth-Error", message);

    log.debug("Unauthorized: {}", message);
    return response.setComplete();
}

💡 Tip: X-Auth-Error 헤더에 구체적인 이유를 담으면 디버깅이 편하다.
(프로덕션에서는 보안상 일반적인 메시지로 대체할 수도 있음)

---

😵 삽질 & 해결

1. CORS Preflight 요청에 401이 떨어짐

문제: 브라우저가 보내는 OPTIONS 요청에도 인증 필터가 적용됨

해결: Preflight 요청은 무조건 통과시키기

if (CorsUtils.isPreFlightRequest(request)) {
    return chain.filter(exchange);
}

2. 필터 순서가 꼬임

문제: 로깅 필터가 인증 필터보다 먼저 실행되어 사용자 정보가 로그에 안 찍힘

해결: getOrder() 메서드로 명시적 순서 지정

// 인증 필터: HIGHEST_PRECEDENCE (가장 먼저)
// 토큰 갱신: HIGHEST_PRECEDENCE + 1
// 로깅 필터: HIGHEST_PRECEDENCE + 100

 

3. WebFlux에서 Request Body를 두 번 읽을 수 없음

문제: 로깅 필터에서 body를 읽으면 다운스트림에서 못 읽음

해결: ServerHttpRequestDecorator로 body 캐싱하거나, 인증 필터에서는 헤더/쿠키만 사용 (body 접근 X)

---

 

📋 정리

구성 요소	역할
JwtAuthenticationFilter	토큰 검증, 클레임 추출, 헤더 전달
TokenRefreshFilter	만료 임박 시 자동 갱신
JwtTokenValidator	토큰 파싱/검증 유틸
application.yml	공개 경로, 토큰 설정

 

Gateway에서 인증을 처리하면:

• 각 서비스는 비즈니스 로직에만 집중
• 인증 정책 변경이 한 곳에서 끝
• 토큰 갱신도 중앙에서 처리

단, Gateway가 SPOF(단일 장애점)가 될 수 있으니 이중화는 필수다.

---

📚 참고

• Spring Cloud Gateway 공식 문서
• JWT.io - JWT 디버깅
• WebFlux에서 GlobalFilter 사용법