Server Plugin

전달된 헤더 (Forwarded headers

[//]: # (title: 전달된 헤더 (Forwarded headers))

필수 의존성: io.ktor:ktor-server-forwarded-header

코드 예제: forwarded-header

네이티브 서버

Ktor는 Kotlin/Native를 지원하며 추가 런타임이나 가상 머신 없이 서버를 실행할 수 있게 해줍니다.

지원: ✅

ForwardedHeaders 및 XForwardedHeaders 플러그인을 사용하면 Ktor 서버가 리버스 프록시(reverse proxy) 뒤에 배치되었을 때 원본 요청(request)에 대한 정보를 얻기 위해 리버스 프록시 헤더를 처리할 수 있습니다. 이는 로깅(logging) 목적으로 유용할 수 있습니다.

• ForwardedHeaders는 Forwarded 헤더(RFC 7239)를 처리합니다.
• XForwardedHeaders는 다음과 같은 X-Forwarded- 헤더들을 처리합니다:
  • X-Forwarded-Host/X-Forwarded-Server
  • X-Forwarded-For
  • X-Forwarded-By
  • X-Forwarded-Proto/X-Forwarded-Protocol
  • X-Forwarded-SSL/Front-End-Https

Forwarded 헤더 조작을 방지하려면, 애플리케이션이 리버스 프록시 연결만 허용하는 경우에만 이 플러그인들을 설치하세요.

의존성 추가

ForwardedHeaders/XForwardedHeaders 플러그인을 사용하려면 빌드 스크립트에 ktor-server-forwarded-header 아티팩트를 포함해야 합니다:

Gradle (Kotlin)Gradle (Groovy)Maven

플러그인 설치

ForwardedHeaderXForwardedHeader

애플리케이션에 ForwardedHeaders 플러그인을 설치하려면, 지정된

모듈

모듈을 사용하면 라우트를 그룹화하여 애플리케이션을 구성할 수 있습니다.

에서 install 함수에 전달하세요. 아래 코드 스니펫은 ForwardedHeaders을 설치하는 방법을 보여줍니다...

• ... embeddedServer 함수 호출 내부에서 설치.
• ... Application 클래스의 확장 함수인 명시적으로 정의된 module 내부에서 설치.

embeddedServermodule

애플리케이션에 XForwardedHeaders 플러그인을 설치하려면, 지정된

모듈

모듈을 사용하면 라우트를 그룹화하여 애플리케이션을 구성할 수 있습니다.

에서 install 함수에 전달하세요. 아래 코드 스니펫은 XForwardedHeaders을 설치하는 방법을 보여줍니다...

• ... embeddedServer 함수 호출 내부에서 설치.
• ... Application 클래스의 확장 함수인 명시적으로 정의된 module 내부에서 설치.

embeddedServermodule

ForwardedHeaders/XForwardedHeaders를 설치한 후, call.request.origin 속성을 사용하여 원본 요청에 대한 정보를 얻을 수 있습니다.

요청 정보 가져오기

프록시 요청 정보

프록시 요청에 대한 정보를 얻으려면 라우트 핸들러(route handler) 내부에서 call.request.local 속성을 사용하세요. 아래 코드 스니펫은 프록시 주소와 요청이 전달된 호스트에 대한 정보를 얻는 방법을 보여줍니다:

get("/hello") {
    val remoteHost = call.request.local.remoteHost
    val serverHost = call.request.local.serverHost
}

원본 요청 정보

원본 요청에 대한 정보를 읽으려면 call.request.origin 속성을 사용하세요:

get("/hello") {
    val originRemoteHost = call.request.origin.remoteHost
    val originServerHost = call.request.origin.serverHost
}

아래 표는 ForwardedHeaders/XForwardedHeaders 설치 여부에 따라 call.request.origin에 의해 노출되는 다양한 속성들의 값을 보여줍니다.

속성	ForwardedHeaders 없음	ForwardedHeaders 포함
origin.localHost	web-server	web-server
origin.localPort	8080	8080
origin.serverHost	web-server	proxy
origin.serverPort	8080	80
origin.remoteHost	proxy	client
origin.remotePort	32864	32864

전체 예제는 여기에서 확인할 수 있습니다: forwarded-header.

ForwardedHeaders 설정

요청이 여러 프록시를 거치는 경우 ForwardedHeaders/XForwardedHeaders를 설정해야 할 수도 있습니다. 이 경우, X-Forwarded-For는 각 연속된 프록시의 모든 IP 주소를 포함합니다. 예:

X-Forwarded-For: <client>, <proxy1>, <proxy2>

기본적으로 XForwardedHeader는 X-Forward-For의 첫 번째 항목을 call.request.origin.remoteHost 속성에 할당합니다. IP 주소 선택을 위한 사용자 정의 로직을 제공할 수도 있습니다. XForwardedHeadersConfig는 이를 위해 다음과 같은 API를 노출합니다:

• useFirstProxy 및 useLastProxy는 각각 IP 주소 목록에서 첫 번째 또는 마지막 값을 가져올 수 있게 합니다.
• skipLastProxies는 오른쪽부터 지정된 수의 항목을 건너뛰고 다음 항목을 가져옵니다. 예를 들어, proxiesCount 매개변수가 3인 경우, 아래 헤더에 대해 origin.remoteHost는 10.0.0.123을 반환합니다:

  X-Forwarded-For: 10.0.0.123, proxy-1, proxy-2, proxy-3

• skipKnownProxies는 목록에서 지정된 항목들을 제거하고 마지막 항목을 가져옵니다. 예를 들어, 이 함수에 listOf("proxy-1", "proxy-3")을 전달하면, 아래 헤더에 대해 origin.remoteHost는 proxy-2를 반환합니다:

  X-Forwarded-For: 10.0.0.123, proxy-1, proxy-2, proxy-3

• extractEdgeProxy를 사용하면 X-Forward-* 헤더에서 값을 추출하기 위한 사용자 정의 로직을 제공할 수 있습니다.