Skip to content
Server Plugin

CORS

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

コード例: cors

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

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

依存関係の追加 ​

CORS を使用するには、ビルドスクリプトに ktor-server-cors アーティファクトを追加します:

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

CORS のインストール ​

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

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

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

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

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

CORS の設定 ​

CORS 固有の設定は、CORSConfig クラスによって提供されます。これらの設定を行う方法を見てみましょう。

概要 ​

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

javascript
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 プラグインを次のように設定する必要があります:

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

完全な例は cors で確認できます。

ホスト ​

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

kotlin
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 関数を使用します。

kotlin
install(CORS) {
    anyHost()
}

HTTP メソッド ​

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

kotlin
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 関数を使用します。

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

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

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

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

ヘッダーの公開 ​

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

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

クレデンシャル ​

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

kotlin
install(CORS) {
    allowCredentials = true
}

その他 ​

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

kotlin
install(CORS) {
    maxAgeInSeconds = 3600
}

その他の設定オプションについては、CORSConfig を参照してください。