Server Plugin

포워디드 헤더

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

코드 예시: forwarded-header

네이티브 서버

Ktor supports Kotlin/Native and allows you to run a server without an additional runtime or virtual machine.

지원: ✅

ForwardedHeaders 및 XForwardedHeaders 플러그인을 사용하면 Ktor 서버가 리버스 프록시 뒤에 배치될 때 리버스 프록시 헤더를 처리하여 원본 요청에 대한 정보를 얻을 수 있습니다. 이는 로깅 목적에 유용할 수 있습니다.

• 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 플러그인을 설치하려면, 지정된

모듈

Modules allow you to structure your application by grouping routes.

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

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

embeddedServermodule

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

모듈

Modules allow you to structure your application by grouping routes.

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

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

embeddedServermodule

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

요청 정보 가져오기

프록시 요청 정보

프록시 요청에 대한 정보를 얻으려면 라우트 핸들러 내에서 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	웹 서버	웹 서버
origin.localPort	8080	8080
origin.serverHost	웹 서버	프록시
origin.serverPort	8080	80
origin.remoteHost	프록시	클라이언트
origin.remotePort	32864	32864

전체 예시는 다음에서 찾을 수 있습니다: forwarded-header.

ForwardedHeaders 구성

요청이 여러 프록시를 통과하는 경우 ForwardedHeaders/XForwardedHeaders를 구성해야 할 수 있습니다. 이 경우, X-Forwarded-For에는 각 연속적인 프록시의 모든 IP 주소가 포함됩니다. 예를 들어:

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

기본적으로 XForwardedHeader는 X-Forwarded-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-* 헤더에서 값을 추출하기 위한 사용자 지정 로직을 제공할 수 있도록 허용합니다.