Skip to content
Server Plugin

Forwarded ヘッダー

必要な依存関係: io.ktor:ktor-server-forwarded-header

コード例: forwarded-header

ネイティブサーバーKtorはKotlin/Nativeをサポートしており、追加のランタイムや仮想マシンなしでサーバーを実行できます。のサポート: ✅

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 アーティファクトを含める必要があります。

kotlin
implementation(ktorLibs.server.forwardedHeader)
上記のコードスニペットでは、Ktor の依存関係を指定するために Ktor バージョンカタログ を使用しています。
groovy
implementation ktorLibs.server.forwardedHeader
上記のコードスニペットでは、Ktor の依存関係を指定するために Ktor バージョンカタログ を使用しています。
xml
<dependency>
    <groupId>io.ktor</groupId>
    <artifactId>ktor-server-forwarded-header-jvm</artifactId>
    <version>${ktor_version}</version>
</dependency>

プラグインのインストール ​

アプリケーションに ForwardedHeaders プラグインをインストールするには、指定されたモジュールモジュールを使用すると、ルートをグループ化してアプリケーションを構造化できます。内の install 関数に渡します。 以下の例は、ForwardedHeaders をインストールする方法を示しています:

  • embeddedServer() 関数の呼び出し内。
  • Application クラスに明示的に定義された module() 拡張関数内。
kotlin
import io.ktor.server.engine.*
import io.ktor.server.netty.*
import io.ktor.server.application.*
import io.ktor.server.plugins.forwardedheaders.*

fun main() {
    embeddedServer(Netty, port = 8080) {
        install(ForwardedHeaders)
        // ...
    }.start(wait = true)
}
kotlin
import io.ktor.server.application.*
import io.ktor.server.plugins.forwardedheaders.*
// ...
fun Application.module() {
    install(ForwardedHeaders)
    // ...
}

アプリケーションに XForwardedHeaders プラグインをインストールするには、指定されたモジュールモジュールを使用すると、ルートをグループ化してアプリケーションを構造化できます。内の install 関数に渡します。 以下の例は、XForwardedHeaders をインストールする方法を示しています:

  • embeddedServer() 関数の呼び出し内。
  • Application クラスに明示的に定義された module() 拡張関数内。
kotlin
import io.ktor.server.engine.*
import io.ktor.server.netty.*
import io.ktor.server.application.*
import io.ktor.server.plugins.forwardedheaders.*

fun main() {
    embeddedServer(Netty, port = 8080) {
        install(XForwardedHeaders)
        // ...
    }.start(wait = true)
}
kotlin
import io.ktor.server.application.*
import io.ktor.server.plugins.forwardedheaders.*
// ...
fun Application.module() {
    install(XForwardedHeaders)
    // ...
}

ForwardedHeaders/XForwardedHeaders をインストールすると、call.request.origin プロパティを使用して元のリクエストに関する情報を取得できるようになります。

リクエスト情報の取得 ​

プロキシリクエスト情報 ​

プロキシリクエストに関する情報を取得するには、ルートハンドラー内で call.request.local プロパティを使用します。 以下のコードスニペットは、プロキシアドレスおよびリクエスト先のホストに関する情報を取得する方法を示しています:

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

元のリクエスト情報 ​

元のリクエストに関する情報を読み取るには、call.request.origin プロパティを使用します:

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

以下の表は、ForwardedHeaders/XForwardedHeaders がインストールされているかどうかに応じた、call.request.origin によって公開されるさまざまなプロパティの値を示しています。

Request diagram

プロパティForwardedHeaders なしForwardedHeaders あり
origin.localHostweb-serverweb-server
origin.localPort80808080
origin.serverHostweb-serverproxy
origin.serverPort808080
origin.remoteHostproxyclient
origin.remotePort3286432864

完全な例はこちらで確認できます: forwarded-header。

ForwardedHeaders の設定 ​

リクエストが複数のプロキシを経由する場合、ForwardedHeaders/XForwardedHeaders の設定が必要になることがあります。 この場合、X-Forwarded-For には後続の各プロキシのすべての IP アドレスが含まれます。例えば:

HTTP
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 を返します:
    HTTP
    X-Forwarded-For: 10.0.0.123, proxy-1, proxy-2, proxy-3
  • skipKnownProxies は、リストから指定されたエントリを削除し、最後のエントリを取得します。 例えば、この関数に listOf("proxy-1", "proxy-3") を渡した場合、以下のヘッダーに対して origin.remoteHost は proxy-2 を返します:
    HTTP
    X-Forwarded-For: 10.0.0.123, proxy-1, proxy-2, proxy-3
  • extractEdgeProxy を使用すると、X-Forward-* ヘッダーから値を抽出するためのカスタムロジックを提供できます。