CORS
必要な依存関係: io.ktor:ktor-server-cors
コード例: cors
Native サーバーKtorはKotlin/Nativeをサポートしており、追加のランタイムや仮想マシンなしでサーバーを実行できます。のサポート: ✅
サーバーでクロスオリジンリクエスト(cross-origin requests)を処理する必要がある場合は、Ktor の CORS プラグインをインストールして設定する必要があります。このプラグインを使用すると、許可されたホスト、HTTP メソッド、クライアントによって設定されるヘッダーなどを設定できます。
依存関係の追加
CORS を使用するには、ビルドスクリプトに ktor-server-cors アーティファクトを追加します:
implementation(ktorLibs.server.cors)implementation ktorLibs.server.cors<dependency>
<groupId>io.ktor</groupId>
<artifactId>ktor-server-cors-jvm</artifactId>
<version>${ktor_version}</version>
</dependency>CORS のインストール
アプリケーションに CORS プラグインをインストールするには、指定されたモジュールモジュールを使用すると、ルートをグループ化してアプリケーションを構造化できます。内の install 関数に渡します。 以下の例は、CORS をインストールする方法を示しています:
embeddedServer()関数呼び出し内。Applicationクラスで明示的に定義されたmodule()拡張関数内。
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)
}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 を使用して行われるサンプルのリクエストを示しています:
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 によって管理される以下のクライアントヘッダーを許可します:
AcceptAccept-LanguageContent-Language
追加のヘッダーを許可するには、allowHeader 関数を使用します。
install(CORS) {
allowHeader(HttpHeaders.ContentType)
allowHeader(HttpHeaders.Authorization)
}カスタムヘッダーを許可するには、allowHeaders または allowHeadersPrefixed 関数を使用します。たとえば、以下のコードスニペットはプレフィックスが custom- のヘッダーを許可する方法を示しています。
install(CORS) {
allowHeadersPrefixed("custom-")
}単純でないコンテンツタイプ(non-simple content types)の場合、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 を参照してください。
