API 라우팅 - Spring Cloud Gateway로 인증/비인증 API 라우팅

API 라우팅 Spring Cloud Gateway는 MSA 환경에서 API 요청을 받아 적절한 마이크로서비스로 라우팅하는 프론트 도어 역할을 한다.
특히 인증 기반 MSA에서 게이트웨이는 인증 여부에 따라 요청을 분기 처리하고, JWT 토큰을 검증하는 필터 역할까지 수행한다.
이 글에서는 Spring Cloud Gateway를 활용해 인증이 필요한 API와 공개 API를 효과적으로 분리하는 방법을 정리한다.

1. 게이트웨이 설정 개요

클라이언트 요청의 첫 진입점
라우팅 경로 정의 및 필터 처리
JWT 토큰의 유효성 검증 수행

2. 의존성 설정 (gateway-service/build.gradle.kts)

dependencyManagement {
    imports {
        mavenBom("org.springframework.cloud:spring-cloud-dependencies:2022.0.5")
    }
}

dependencies {
    implementation("org.springframework.boot:spring-boot-starter-actuator")
    implementation("com.fasterxml.jackson.module:jackson-module-kotlin")
    implementation("org.jetbrains.kotlin:kotlin-reflect")
    implementation("org.springframework.boot:spring-boot-starter-security")
    implementation("org.springframework.boot:spring-boot-starter-oauth2-resource-server")
    implementation("org.springframework.boot:spring-boot-starter-webflux")
    implementation("org.springframework.cloud:spring-cloud-starter-gateway")
    testImplementation("org.springframework.boot:spring-boot-starter-test")
}

3. application.yml 설정 예시

spring:
  application:
    name: gateway-service
  cloud:
    gateway:
      routes:
        - id: user-service
          uri: http://localhost:8082
          predicates:
            - Path=/api/user/**
          filters:
            - StripPrefix=2
        - id: public-service
          uri: http://localhost:8083
          predicates:
            - Path=/api/public/**
          filters:
            - StripPrefix=2
  security:
    oauth2:
      resourceserver:
        jwt:
          jwk-set-uri: http://localhost:8081/oauth2/jwks
logging:
  level:
    org.springframework.cloud.gateway: DEBUG

4. 인증 필터 구현

application.yml에 아래와 같이 설정하면

  spring:
    security:
      oauth2:
        resourceserver:
          jwt:
            jwk-set-uri: http://localhost:8081/oauth2/jwks

Spring Security + Spring Cloud Gateway가 자동으로
- Authorization 헤더의 JWT 토큰을 파싱
- JWK Set URI에서 공개키를 받아와 서명 검증
- 토큰이 유효하지 않으면 401 Unauthorized 반환
- 토큰이 유효하면 SecurityContext에 인증 정보 저장
죽,
- 직접 JWT 검증 필터(커스텀 WebFilter 등)를 구현할 필요없음
- Gateway가 알아서 모든 요청에 대해 JWT를 검증
- 라우팅/권한/인증 등은 Spring Security 설정만으로 처리 가능합니다.
추가로
- 특별한 커스텀 검증(예: 토큰 내 커스텀 클레임 체크, 추가 로깅 등)이 필요하다면 WebFilter를 추가할 수 있지만,
- 일반적인 JWT 인증/인가는 Spring Security가 모두 처리된다.

5. 인증/비인증 요청 흐름

클라이언트가 JWT를 포함한 요청을 게이트웨이에 전송
게이트웨이에서 JWT 유효성 검증 (AuthenticationFilter)
유효하면 해당 마이크로서비스로 요청 전달
토큰이 없거나 유효하지 않으면 401 응답 반환

6. 서비스 별 라우팅 전략

서비스 이름	경로 패턴	인증 필요 여부
user-service	/api/user/**	필요
public-service	/api/public/**	불필요

7. 테스트결과

인증 경계의 관문, 게이트웨이

Spring Cloud Gateway는 인증 중심 MSA에서 토큰의 첫 검사자 역할을 수행한다.
인증 여부에 따라 요청을 분기하고, 마이크로서비스로 유효한 요청만 전달함으로써 전체 시스템의 보안성과 일관성을 확보할 수 있다.
다음 글에서는 Eureka를 활용해 서비스 간 연결을 구성하는 방법을 이어서 정리한다.

이전편 보기
인증 서비스 구축: OAuth2 + JWT 기반 토큰 발급

참고

자세한 코드는 아래 저장소에서 확인 가능하다.
Github – 저장소

API 라우팅 – Spring Cloud Gateway로 인증/비인증 API 라우팅