Server Plugin

CORS

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

コード例: cors

Native サーバー

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

のサポート: ✅

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

依存関係の追加

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

Gradle (Kotlin)Gradle (Groovy)Maven

CORS のインストール

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

モジュール

Modules allow you to structure your application by grouping routes.

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

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

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-")
}

シンプルではない（non-simple）コンテンツタイプの場合、allowHeaders または allowHeadersPrefixed を使用するには、allowNonSimpleContentTypes プロパティを true に設定する必要があることに注意してください。

ヘッダーの公開

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

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

資格情報

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

install(CORS) {
    allowCredentials = true
}

その他

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

install(CORS) {
    maxAgeInSeconds = 3600
}

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