CORS

ブラウザーは、https://api.example が Access-Control-Allow-... ヘッダーで許可しない限り、https://shop.example のページがその応答を読むことを許しません。これが CORS (Cross-Origin Resource Sharing) です。スターターは、宣言したルールに従って CORS に応答します。ルールはコントローラーやメソッドの @CrossOrigin、WebMvcConfigurer の addCorsMappings、または corsConfigurationSource という名前の CorsConfigurationSource Bean で宣言します。

使う理由

オリジンとはスキーム、ホスト、ポートの組です。https://shop.example と https://api.example は別のオリジンで、http://localhost:3000 と http://localhost:8080 も別のオリジンです。ページが fetch で別のオリジンを呼ぶと、ブラウザーは次のように動きます。

  1. ほとんどのリクエストでは、まず Origin、Access-Control-Request-Method、多くの場合 Access-Control-Request-Headers を付けた OPTIONS のプリフライトを送り、その呼び出しが許可されるかを尋ねます。
  2. Origin ヘッダーを付けて実際のリクエストを送ります。
  3. 一致する Access-Control-Allow-Origin が応答にある場合に限り、ページに応答を読ませます。

別のオリジンにあるフロントエンドが API を呼ぶ場合に CORS のルールが必要です。CDN から配信される Flutter Web アプリ、別ドメインのサイト、別ポートの開発サーバーなどです。自分のページだけ、あるいはプログラム (他のサーバー、モバイルアプリ) だけが使う API には不要です。CORS が縛るのはブラウザーだけです。

例

import 'package:spring_boot_starter_web/spring_boot_starter_web.dart';

// コントローラーに付ける: ショップのページはそのすべてのメソッドを呼べる。
@RestController()
@RequestMapping('/api/books')
@CrossOrigin(origins: ['https://shop.example'], maxAge: 3600)
class BookController {
  @GetMapping()
  List<String> list() => ['Dune'];

  // メソッドの指定はクラスの指定に追加される: ショップからの PUT を、その Cookie 付きで許可する。
  @PutMapping('/{isbn}')
  @CrossOrigin(allowCredentials: true, exposedHeaders: ['Location'])
  void update(@PathVariable() String isbn) {}
}

// 多くのパスをまとめて指定する: WebMvcConfigurer。
@Configuration()
class WebConfig with WebMvcConfigurer {
  @override
  void addCorsMappings(CorsRegistry registry) {
    registry
        .addMapping('/api/**')
        .allowedOriginPatterns(['https://*.shop.example', 'http://localhost:[*]'])
        .allowedMethods(['GET', 'HEAD', 'POST', 'PUT', 'DELETE'])
        .allowCredentials(true);
    registry.addMapping('/public/**'); // 任意のオリジン、GET、HEAD、POST
  }
}

あるいはルールを Bean にします。その場合、Bean が対象とするパスでは Bean だけが判断します。

@Configuration()
class CorsConfig {
  @Bean()
  CorsConfigurationSource corsConfigurationSource() =>
      UrlBasedCorsConfigurationSource()
        ..registerCorsConfiguration(
          '/api/**',
          CorsConfiguration(
            allowedOriginPatterns: ['https://*.shop.example'],
            allowCredentials: true,
          )..applyPermitDefaultValues(), // GET、HEAD、POST、すべてのヘッダー、30 分
        );
}

プリフライトとその応答:

OPTIONS /api/books/42
Origin: https://eu.shop.example
Access-Control-Request-Method: PUT
Access-Control-Request-Headers: content-type

200 OK
Access-Control-Allow-Origin: https://eu.shop.example
Access-Control-Allow-Methods: GET,HEAD,POST,PUT,DELETE
Access-Control-Allow-Headers: content-type
Access-Control-Expose-Headers: Location
Access-Control-Allow-Credentials: true
Access-Control-Max-Age: 3600
Vary: Origin, Access-Control-Request-Method, Access-Control-Request-Headers

メソッドはグローバルマッピングとハンドラーの両方から、オリジンはグローバルパターンから、max age はクラスの @CrossOrigin から、クレデンシャルと公開ヘッダーはメソッドの @CrossOrigin から来ています。

ルールを宣言する 3 つの方法

方法 範囲 省略した項目のデフォルト 組み合わせる相手
クラスまたはメソッドの @CrossOrigin そのコントローラーのハンドラー すべてのオリジン、ハンドラーがマッピングされたメソッド、すべてのヘッダー、30 分 グローバルマッピング、およびクラスとメソッド
WebMvcConfigurer.addCorsMappings パスパターン: コントローラー、静的リソース、404 すべてのオリジン、GET・HEAD・POST、すべてのヘッダー、30 分 各ハンドラーの @CrossOrigin
corsConfigurationSource という名前の CorsConfigurationSource Bean 設定を返す対象すべて なし: 設定はそのまま使われる なし: ルールがある場所では、そのルールだけが適用される

@CrossOrigin

属性 型 デフォルト 意味
origins List<String> []: originPatterns も空なら任意のオリジン 許可するオリジン全体 (https://shop.example)。大文字小文字を区別せずに比較する。* は任意のオリジンを許可する。
originPatterns List<String> [] オリジンパターン (https://*.shop.example、http://localhost:[*])。後述の「オリジンとパターン」を参照。
methods List<String> []: ハンドラーがマッピングされたメソッド 許可するメソッド (PUT、DELETE、*)。プリフライトと実際のリクエストの両方に使う。
allowedHeaders List<String> []: すべてのヘッダー プリフライトが要求できるリクエストヘッダー。大文字小文字を区別せずに比較する。* は任意のヘッダーを許可する。
exposedHeaders List<String> []: なし 単純なヘッダー以外で、ページのスクリプトが読めるレスポンスヘッダー (Location、X-Total-Count)。
allowCredentials bool? null: 許可しない ブラウザーが Cookie などのクレデンシャルを送り、ページに応答を読ませてよいか。
allowPrivateNetwork bool? null: 許可しない 公開サイトのページが、プライベートネットワーク上のこのサーバーを呼べるか (Chrome の Private Network Access)。
maxAge int? null: 1800 ブラウザーがプリフライトの応答を再利用できる時間 (秒)。

ルール:

WebMvcConfigurer.addCorsMappings

registry.addMapping(pattern) は、パターンに一致するパスで CORS を有効にし、CorsRegistration を返します。

CorsRegistration のメソッド 呼ばない場合のデフォルト 意味
allowedOrigins(List<String> origins) 任意のオリジン (パターンも設定されていない場合) オリジン全体を追加する。
allowedOriginPatterns(List<String> patterns) なし オリジンパターンを追加する。
allowedMethods(List<String> methods) GET、HEAD、POST メソッドを追加する。
allowedHeaders(List<String> headers) すべてのヘッダー リクエストヘッダーを追加する。
exposedHeaders(List<String> headers) なし 公開するレスポンスヘッダーを追加する。
allowCredentials(bool allow) 許可しない クレデンシャル。true にする場合は、オリジンを列挙するかパターンを使う。
allowPrivateNetwork(bool allow) 許可しない Private Network Access。true にする場合は、オリジンを列挙するかパターンを使う。
maxAge(Duration maxAge) 30 分 プリフライトのキャッシュ。秒ではなく Duration。

corsConfigurationSource Bean

corsConfigurationSource という名前の CorsConfigurationSource 型の Bean は、Spring Security がその名前の Bean を適用するのと同じく、セキュリティスターターの CORS フィルターが適用するルールを持ちます。ルーターも同じように適用するため、CORS はセキュリティスターターの有無にかかわらず同じように動きます。

UrlBasedCorsConfigurationSource は、パスパターンで設定を選びます。registerCorsConfiguration(pattern, configuration) で登録し、登録順に試され、最初に一致したものが採用されます。実行時に変わるルールには、CorsConfigurationSource を自分で実装します (getCorsConfiguration(request))。

// 許可するオリジンはテナントのサイトで、実行時に変わる。
@Component('corsConfigurationSource')
final class TenantCors implements CorsConfigurationSource {
  TenantCors(this.tenants);

  final TenantService tenants;

  @override
  CorsConfiguration? getCorsConfiguration(ServerHttpRequest request) =>
      request.path.startsWith('/api/')
          ? (CorsConfiguration(allowedOrigins: tenants.origins())
              ..applyPermitDefaultValues())
          : null;
}

CorsConfiguration

メンバー 意味
CorsConfiguration({allowedOrigins, allowedOriginPatterns, allowedMethods, allowedHeaders, exposedHeaders, allowCredentials, allowPrivateNetwork, maxAge}) 設定。リストはコピーされ、後から追加できる。それ以外はデフォルトで未設定。
CorsConfiguration.fromAnnotation(CrossOrigin annotation, {mappedMethods}) アノテーションのルール。methods がなければ mappedMethods、その後に寛容なデフォルトが入る。
allowedOrigins オリジン全体。大文字小文字を区別せずに比較する。* は任意のオリジンを許可する。空: なし。
allowedOriginPatterns オリジンパターン。大文字小文字を区別して比較する。
allowedMethods メソッド。大文字小文字を区別して比較する。* は任意のメソッドを許可する。空: GET と HEAD。
allowedHeaders リクエストヘッダー。大文字小文字を区別せずに比較する。* は任意のヘッダーを許可する。空: なし。
exposedHeaders Access-Control-Expose-Headers。
allowCredentials Access-Control-Allow-Credentials: true。null と false は許可しないことを意味する。
allowPrivateNetwork それを要求するプリフライトに対する Access-Control-Allow-Private-Network: true。null と false は許可しないことを意味する。
maxAge プリフライト応答の Access-Control-Max-Age (Duration)。null なら送らない。
applyPermitDefaultValues() 空の項目を埋める: すべてのオリジン (オリジンもパターンも設定されていない場合)、GET・HEAD・POST、すべてのヘッダー、max age 30 分。設定自身を返す。
combine(CorsConfiguration? other) 両方のルールを持つ新しい設定。other がより具体的な側。後述の「ルールの組み合わせ方」を参照。
checkOrigin(String origin) origin に対する Access-Control-Allow-Origin の値。許可されない場合は null。
checkMethod(String method) method に対する Access-Control-Allow-Methods のリスト。許可されない場合は null。
checkHeaders(List<String> requested) Access-Control-Allow-Headers のリスト。許可されないヘッダーが一つでもあれば null。
validateAllowCredentials()、validateAllowPrivateNetwork() フラグが true で allowedOrigins に * がある場合に StateError を投げる。

オリジンとパターン

オリジンは、Spring の CorsConfiguration と同じ方法で、AllowedOrigins (spring_web_dart のもの) によってチェックされます。WebSocket スターターもハンドシェイクを同じクラスでチェックするため、両者は同じオリジンを受け入れます。

@CrossOrigin の値のプレースホルダー (${...}) は解決されず、書いたとおりの値が使われます。オリジンを設定から取るには、WebMvcConfigurer か、プロパティを注入する Bean でルールを組み立て、カンマ区切りのリストを一つの値として渡します。

@Configuration()
class WebConfig with WebMvcConfigurer {
  WebConfig(@Value(r'${shop.cors.origins}') this.origins);

  final String origins; // "https://a.example, https://b.example"

  @override
  void addCorsMappings(CorsRegistry registry) =>
      registry.addMapping('/api/**').allowedOrigins([origins]);
}

リクエストのチェック方法

スキーム、ホスト、ポートのいずれかがリクエスト自身のものと異なる Origin を持つリクエストが CORS リクエストです (解析できない Origin は別のオリジンとみなされます)。ルールでチェックされるのは CORS リクエストだけです。CORS のルールを持つハンドラーへのすべてのリクエストに対して、スターターは Spring の DefaultCorsProcessor と同じく次のことを行います。

  1. CORS リクエストかどうかにかかわらず、Vary: Origin、Vary: Access-Control-Request-Method、Vary: Access-Control-Request-Headers を追加します。
  2. 可視の US-ASCII でない Origin を拒否します。
  3. CORS リクエストでなければ、そこで止めてリクエストを許可します。
  4. レスポンスにすでに Access-Control-Allow-Origin がある場合 (セキュリティスターターのものなど、フィルターが CORS を処理した場合)、レスポンスをそのままにします。
  5. オリジンをチェックします。
  6. メソッドをチェックします。プリフライトでは Access-Control-Request-Method のメソッド、それ以外ではリクエスト自身のメソッドです。
  7. プリフライトでは、Access-Control-Request-Headers のすべてのヘッダーをチェックします。
  8. 以下のヘッダーを書き込みます。

拒否は Invalid CORS request というテキストの 403 で、ハンドラーは呼ばれません。

ヘッダー プリフライト 実際のリクエスト
Access-Control-Allow-Origin オリジン、または * オリジン、または *
Access-Control-Allow-Methods 許可されたメソッド (* の場合: 要求されたメソッド) —
Access-Control-Allow-Headers 要求されたヘッダー (要求があった場合) —
Access-Control-Expose-Headers 設定されている場合 設定されている場合
Access-Control-Allow-Credentials 許可されている場合 true 許可されている場合 true
Access-Control-Allow-Private-Network 許可されていて、プリフライトが Access-Control-Request-Private-Network: true を送った場合 true 同じ
Access-Control-Max-Age 設定されている場合、その秒数 —

メソッドは常にチェックされる

クロスオリジンのリクエストは、実際のリクエストも含めて、すべてそのメソッドでチェックされます。そのため、許可されたオリジンからの DELETE、PUT、HEAD、OPTIONS でも、ルールに列挙されていなければ、ブラウザーがプリフライトを送らなかった場合でも、ハンドラーの実行前に 403 で拒否されます。セキュリティスターターがある場合、これはセキュリティチェックより前に行われます。

プリフライト

プリフライトは、Origin と Access-Control-Request-Method を持つ OPTIONS リクエストです。CORS のルールから応答され、ハンドラーやインターセプターに渡されることはありません。

状況 応答
どのハンドラーもマッピングしていないパス 次のハンドラーマッピングへ進み、最終的に 404。静的ファイルへのプリフライトはグローバルルールから応答される。
マッピングされたパスで、予告されたメソッドのハンドラーがあり、ルールがある CORS ヘッダー付きの 200、またはルールが拒否すれば 403。
マッピングされたパスで、予告されたメソッドのハンドラーがない Spring と同じく、グローバルルールだけが判断する: 200 または 403。405 にはならない。
CORS のルールがまったくないマッピングされたパス CORS ヘッダーも Vary もない 200。ブラウザーは予告したリクエストをブロックする。
サーバー自身のオリジンから CORS リクエストではない: 200。パスにルールがあれば Vary ヘッダー付き。

どのハンドラーのルールを使うか。 プリフライトは、そのリクエストがどの Content-Type や Accept を送るかを示せないため、そのパスと予告されたメソッドの最初のハンドラー (最も具体的なパターン、次に条件の最も多いもの) のルールから応答されます。プリフライトのパスとメソッドに複数のハンドラーが一致し、そのすべてが @CrossOrigin のルールを持つ場合、これは Spring と異なります。対象は、そのパスちょうどにマッピングされたハンドラーがあればそれら (あるオリジン向けに JSON、別のオリジン向けに CSV を返す GET /items)、なければ一致するすべてのパターン (/items/7 に対する /items/{id} と /items/**) です。Spring はこの場合、任意のオリジンからクレデンシャル付きでプリフライトを許可し、チェックを実際のリクエストに任せます。ここでは、最初のハンドラーのルールが許可しないオリジンはプリフライトで 403 を受け取ります。どのオリジンも、一つのハンドラーのルールを超える許可は得られません。そうしたハンドラーには同じ CORS ルールを与えてください。実際のリクエストは常に、それに応答するハンドラーのルールでチェックされます。

ルールのないリクエスト

Vary

CORS のルールを持つハンドラーのすべての応答に Vary: Origin, Access-Control-Request-Method, Access-Control-Request-Headers が付きます。CORS リクエストかどうか、許可されたオリジンか拒否されたオリジンかにかかわりません。これにより、間にあるキャッシュは異なるオリジンへの応答を区別して保持します。

ルールの組み合わせ方

ルールは Spring と同じ方法で組み合わされます。まずグローバルなもの (addCorsMappings のマッピング)、次にクラスの @CrossOrigin、そしてメソッドのものです。combine では、より具体的な側が other です。

allowedOrigins(['https://shop.example']) を持つグローバルマッピング /api/** のもとでの例:

ハンドラーの指定 オリジン メソッド
なし https://shop.example GET、HEAD、POST (マッピングのデフォルト)
@PutMapping に @CrossOrigin() https://shop.example PUT (ハンドラーが設定したマッピング先のメソッドが、マッピングのデフォルトを置き換える)
@CrossOrigin(origins: ['https://admin.example']) https://shop.example、https://admin.example マッピング先のメソッド

マッピングに .allowedMethods(['GET', 'POST']) がある場合、@CrossOrigin(methods: ['PUT']) のハンドラーは GET、POST、PUT を許可します。両側がリストを設定しているため、マージされます。

クレデンシャルとプライベートネットワーク

TLS を終端するプロキシの背後で

ブラウザーは、自分のサイトに対してもすべての POST、PUT、PATCH、DELETE に Origin を付けて送ります。プロキシが TLS を終端する (あるいはホストやポートを変える) と、サーバーには http と自身のアドレスが見えるため、アプリケーション自身のページが別のオリジンに見え、そのリクエストはクロスオリジンとしてチェックされます。デフォルトのまま /** に addCorsMappings のルールを付けていると、ページ自身の PUT や DELETE は 403 になり、サイト自身のオリジンを含まないオリジンを指定していると POST も 403 になります。

次のいずれかの方法で解決します。

ルールが適用される場所

DispatcherHandler.corsConfigurationFor(request) は、リクエスト自身と同じ順序でハンドラーマッピングに問い合わせ、そのリクエストに適用されるルールを返します。セキュリティスターターの CORS フィルターはこれを使います。Spring での対応物は HandlerMappingIntrospector.getCorsConfiguration です。

独自のフィルターやハンドラーマッピング向けには、isCorsRequest(request)、isPreFlightRequest(request)、そして processCors(config, request, response, preFlight: ...) があります。processCors はヘッダーを書き込み、リクエストを拒否すべきときに false を返します。

Spring (Java) との対応

@RestController
@CrossOrigin(origins = "https://shop.example", maxAge = 3600)
class BookController { ... }

@Override
public void addCorsMappings(CorsRegistry registry) {
  registry.addMapping("/api/**")
      .allowedOriginPatterns("https://*.shop.example")
      .allowCredentials(true);
}

重要な違い:

関連項目