Server Plugin

CORS

必須の依存関係: io.ktor:ktor-server-cors

コード例: cors

ネイティブサーバー

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

のサポート: ✅

サーバーがクロスオリジンリクエストを処理するように想定されている場合、CORS Ktorプラグインをインストールして設定する必要があります。このプラグインを使用すると、許可されたホスト、HTTPメソッド、クライアントによって設定されたヘッダーなどを設定できます。

依存関係の追加

CORSを使用するには、ktor-server-corsアーティファクトをビルドスクリプトに含める必要があります:

Gradle (Kotlin)Gradle (Groovy)Maven

CORSのインストール

CORSプラグインをアプリケーションにインストールするには、指定された

モジュール

モジュールを使用すると、ルートをグループ化してアプリケーションを構造化できます。

内のinstall関数に渡します。以下のコードスニペットは、CORSをインストールする方法を示しています...

• ...embeddedServer関数呼び出し内で。
• ...明示的に定義されたmodule内（Applicationクラスの拡張関数）。

embeddedServermodule

CORSプラグインは、特定のルートにもインストールできます。これは、異なるアプリケーションリソースに対して異なるCORS構成が必要な場合に役立ちます。

CORSプラグインを特定のルートにインストールする場合、このルートにoptions ハンドラーを追加する必要があります。これにより、KtorはCORSプリフライトリクエストに正しく応答できます。

CORSの設定

CORS固有の設定は、CORSConfigクラスによって公開されています。これらの設定を構成する方法を見てみましょう。

概要

8080ポートでリッスンし、/customer ルートがJSONデータを応答するサーバーがあるとします。以下のコードスニペットは、別のポートで動作するクライアントからFetch APIを使用して行われたサンプルリクエストを示しており、このリクエストがクロスオリジンになるようにしています。

function saveCustomer() {
    fetch('http://0.0.0.0:8080/customer',
        {
            headers: {
                'Accept': 'application/json',
                'Content-Type': 'application/json'
            },
            method: "POST",
            body: JSON.stringify({id: 3, firstName: "Jet", lastName: "Brains"})
        })
        .then(response => response.text())
        .then(data => {
            console.log('Success:', data);
            alert(data);
        })
        .catch((error) => {
            console.error('Error:', error);
        });
}

バックエンド側でこのようなリクエストを許可するには、CORSプラグインを次のように構成する必要があります:

install(CORS) {
    allowHost("0.0.0.0:8081")
    allowHeader(HttpHeaders.ContentType)
}

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

ホスト

クロスオリジンリクエストを行うことができる許可されたホストを指定するには、allowHost関数を使用します。ホスト名の他に、ポート番号、サブドメインのリスト、またはサポートされているHTTPスキームを指定できます。

install(CORS) {
    allowHost("client-host")
    allowHost("client-host:8081")
    allowHost("client-host", subDomains = listOf("en", "de", "es"))
    allowHost("client-host", schemes = listOf("http", "https"))
}

任意のホストからのクロスオリジンリクエストを許可するには、anyHost関数を使用します。

install(CORS) {
    anyHost()
}

HTTPメソッド

デフォルトでは、CORSプラグインはGET、POST、HEADのHTTPメソッドを許可します。追加のメソッドを追加するには、allowMethod関数を使用します。

install(CORS) {
    allowMethod(HttpMethod.Options)
    allowMethod(HttpMethod.Put)
    allowMethod(HttpMethod.Patch)
    allowMethod(HttpMethod.Delete)
}

ヘッダーの許可

デフォルトでは、CORSプラグインはAccess-Control-Allow-Headersによって管理される以下のクライアントヘッダーを許可します:

• Accept
• Accept-Language
• Content-Language

追加のヘッダーを許可するには、allowHeader関数を使用します。

install(CORS) {
    allowHeader(HttpHeaders.ContentType)
    allowHeader(HttpHeaders.Authorization)
}

カスタムヘッダーを許可するには、allowHeaders関数またはallowHeadersPrefixed関数を使用します。例えば、以下のコードスニペットは、custom-で始まるヘッダーを許可する方法を示しています。

install(CORS) {
    allowHeadersPrefixed("custom-")
}

allowHeadersまたはallowHeadersPrefixedは、非単純なコンテンツタイプの場合、allowNonSimpleContentTypesプロパティをtrueに設定する必要があることに注意してください。

ヘッダーの公開

Access-Control-Expose-Headersヘッダーは、ブラウザのJavaScriptがアクセスできる許可リストに指定されたヘッダーを追加します。このようなヘッダーを構成するには、exposeHeader関数を使用します。

install(CORS) {
    // ...
    exposeHeader("X-My-Custom-Header")
    exposeHeader("X-Another-Custom-Header")
}

認証情報

デフォルトでは、ブラウザはクロスオリジンリクエストで認証情報（クッキーや認証情報など）を送信しません。この情報の受け渡しを許可するには、allowCredentialsプロパティを使用してAccess-Control-Allow-Credentials応答ヘッダーをtrueに設定します。

install(CORS) {
    allowCredentials = true
}

その他

CORSプラグインは、他のCORS関連の設定も指定できます。例えば、maxAgeInSecondsを使用すると、プリフライトリクエストに対する応答を、別のプリフライトリクエストを送信することなくキャッシュできる期間を指定できます。

install(CORS) {
    maxAgeInSeconds = 3600
}

その他の設定オプションについては、CORSConfigで確認できます。