
# 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 が縛るのはブラウザーだけです。

## 例

```dart
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 だけが判断します。

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

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

```text
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 | ブラウザーがプリフライトの応答を再利用できる時間 (**秒**)。 |

ルール:

- **クラスに付ける**とそのすべてのハンドラーに、**メソッドに付ける**とそのメソッドだけに適用されます。両方にある場合、リストはマージされ、`allowCredentials`、`allowPrivateNetwork`、`maxAge` はメソッドのものが優先されます。
- **`methods` がない場合**、Spring と同じく、ハンドラーがマッピングされたメソッドが許可されます。`@DeleteMapping` なら `DELETE`、`@GetMapping` なら `GET` です。**`HEAD` は含まれません**。`GET` ハンドラーへのクロスオリジンの `HEAD` は拒否されます。ページが `HEAD` を送るなら `methods: ['GET', 'HEAD']` と書いてください。
- **`origins` も `originPatterns` もない (つまりすべてのオリジンを許可する) まま `allowCredentials: true` または `allowPrivateNetwork: true` を指定すると**、Spring と同じく**起動が止まります**: `BookController.update: @CrossOrigin(allowCredentials: true) needs origins or originPatterns (all origins, "*", cannot be allowed with credentials)`。`origins: ['*']` も同様です。[起動時のチェック](controllers/startup-checks.md) を参照してください。

### `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`。 |

- リストを受け取るメソッドは、既存の内容に**追加**します。Spring のものは置き換えます。
- マッピングはすべての configurer を通して追加された順に試され、**パスに一致した最初のパターンが採用されます**。最も具体的なパターンではありません。具体的なパターンを先に追加してください。
- ルールは、そのパス上のコントローラー (その `@CrossOrigin` と組み合わせて)、静的リソース、どのハンドラーも受け取らないリクエストに適用されます。
- **クレデンシャルまたはプライベートネットワークと `*` の組み合わせ**は、ここでは起動を止めません。Spring がリクエストごとに設定を検証するのと同じく、マッピングのパスへのすべてのリクエストが `500` (`StateError`) で失敗します。

### `corsConfigurationSource` Bean

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

- **リクエストに対して設定を返す場合**、その設定だけが判断します。`@CrossOrigin` も `addCorsMappings` のルールもそれを広げません。それらが追加するはずのオリジン、ヘッダー、max age は追加されません。
- **`null` を返す場合**、`@CrossOrigin` とマッピングが適用されます。
- **重要なのは型ではなく名前です。** `corsConfigurationSource()` という名前の `@Bean` メソッドはその名前を与えます。同じ型でも別の名前の Bean (`apiCors` やライブラリのもの) は Spring Security と同じく無視され、そうした Bean が複数あっても起動が失敗することはありません。その名前でも `CorsConfigurationSource` でない Bean はルールとして扱われません (セキュリティスターターはその場合に起動を失敗させます)。
- **自分で組み立てた設定はそのまま使われます**。空のリストはどのオリジンもどのリクエストヘッダーも許可せず、空の `allowedMethods` は `GET` と `HEAD` を許可します。寛容なデフォルトにするには `applyPermitDefaultValues()` を呼んでください。
- **クレデンシャルまたはプライベートネットワークと `*` の組み合わせ**では、チェックに到達したクロスオリジンのリクエストがそれぞれ失敗します (`500`)。

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

```dart
// 許可するオリジンはテナントのサイトで、実行時に変わる。
@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 スターターもハンドシェイクを同じクラスでチェックするため、両者は同じオリジンを受け入れます。

- **`origins` / `allowedOrigins`** はオリジン全体で、大文字小文字を区別せずに比較されます。`https://shop.example` は `https://SHOP.example` に一致します。`*` は任意のオリジンを許可し、そのときの応答は `Access-Control-Allow-Origin: *` になります。
- **`originPatterns` / `allowedOriginPatterns`** は大文字小文字を区別して比較されます。`*` は Spring の `.*` と同じく任意のテキストに一致します。
  - `https://*.shop.example` は `https://eu.shop.example` と `https://a.b.shop.example` に一致し、`https://shop.example` には一致しません。
  - `*.shop.example` は任意のスキームに一致します。`*localhost*` は任意の `localhost` のオリジンに一致します。
  - 末尾のポートリストは、列挙したポートに一致します: `http://localhost:[3000,3001]`。
  - `[*]` は任意のポート、またはポートなしに一致します。`http://localhost:[*]` は `http://localhost` と `http://localhost:5173` に一致します。
- **列挙したオリジンやパターンに一致した場合、オリジンはブラウザーが送ったとおりにそのまま返されます**。そのため、`*` が使えないクレデンシャル付きでもパターンは機能します。
- **一つの値に複数を列挙できます**。カンマで区切ります (`'https://a.example, https://b.example'`)。一つのプロパティから値を取るときに便利です。ポートリストのカンマは区切りになりません。
- **末尾の `/` は無視されます**。値でも `Origin` ヘッダーでも同じです。
- **1024 文字を超える `Origin` は決して許可されません** (`AllowedOrigins.maxOriginLength`)。実際のオリジンは 300 文字未満です。パターンの照合時間は、`*` がいくつあってもオリジンの長さに比例して増えます。
- **可視の US-ASCII 以外の文字** (空白、制御文字、ASCII 外の文字) を含む `Origin` は `403` で拒否されます。そうしたメソッドやヘッダーを要求するプリフライトも、`*` で任意のものを許可していても同様です。そうした値を送るブラウザーはなく、応答でそれを返すこともできません。
- Spring と同じく、`https://*.example.com` は `https://evil.com/.example.com` にも一致します。そうした `Origin` を送るブラウザーはなく、他のクライアントはどのみち任意の `Origin` を送れます。

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

```dart
@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 ルールを与えてください。実際のリクエストは常に、それに応答するハンドラーのルールでチェックされます。

### ルールのないリクエスト

- CORS のルールがないパスでは、クロスオリジンのリクエストも他のリクエストと同じく、CORS ヘッダーなしで処理されます。ブラウザーはその応答をページに渡しません。
- プリフライトではない `OPTIONS` リクエストが `OPTIONS` ハンドラーのないパスに来た場合、`Allow` 付きの `200` を受け取ります。その前に、`OPTIONS` をメソッドとしてグローバルルールが適用されます。

### `Vary`

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

- 各名前は、大文字小文字にかかわらず、`Vary` にすでにある名前 (フィルターが付けたもの) の隣に一度だけ追加されます。
- ハンドラー自身の `Vary` (`ResponseEntity` や `ErrorResponse` のもの) は、Spring の `HttpEntityMethodProcessor` がマージするのと同じく、置き換えるのではなくこれらに名前を追加します。CORS のルールがないハンドラーでは、そのまま書き込まれます。
- すでに `Vary: *` がある場合は何も追加されません。
- セキュリティスターターがある場合、その CORS フィルターが、CORS のルールを持つすべてのリクエストに対してセキュリティチェックの前に名前を追加します。そのため、セキュリティスターター自身の `401` と `403` の応答にも付きます。
- ルールのないハンドラーの応答には付きません。

## ルールの組み合わせ方

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

- **両側が設定したリスト**はマージされます。どちらかの側に `*` があれば結果は `*` です。
- **`@CrossOrigin` や `applyPermitDefaultValues()` のデフォルトだけを持つリスト**は、相手側のリストに譲ります。相手側が設定したものを広げることはありません。`origins` のない `@CrossOrigin()` は、グローバルのオリジンを `*` に広げず、そのまま保ちます。
- **空のリスト**は相手側のものを取ります。
- **デフォルトのオリジン**と、相手側の**パターン**: パターンだけになります。
- **`allowCredentials`、`allowPrivateNetwork`、`maxAge`** は、設定されていればより具体的な側のものが優先されます。`@CrossOrigin` は常に `maxAge` (自身のもの、または 1800 秒) を持つため、グローバルのものより優先されます。

`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` を許可します。両側がリストを設定しているため、マージされます。

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

- **クレデンシャル** (Cookie、HTTP 認証、クライアント証明書) がクロスオリジンで送られるのは、ページが要求し (`fetch(url, {credentials: 'include'})`)、応答が正確なオリジンとともに `Access-Control-Allow-Credentials: true` を返す場合だけです。ブラウザーはクレデンシャル付きの `*` を拒否します。そのため `allowCredentials: true` には、列挙したオリジンかパターンが必要です。
  - `@CrossOrigin`: 起動が失敗します。
  - `addCorsMappings` のマッピング: そのパスへのすべてのリクエストが `500` になります。
  - `corsConfigurationSource` Bean: `*` によって許可するすべてのクロスオリジンのリクエストが `500` になります。
- **Private Network Access** (Chrome): 公開サイトのページが `localhost` やオフィスネットワーク上のサーバーを呼ぶと、`Access-Control-Request-Private-Network: true` 付きのプリフライトを送ります。`allowPrivateNetwork: true` にすると、応答に `Access-Control-Allow-Private-Network: true` が追加されます。クレデンシャルと同じルールがあり、`*` とは決して組み合わせられません。組み合わせると、あらゆるサイトがプライベートネットワークに届いてしまいます。公開サイトから呼ばれるローカルのヘルパーアプリやイントラネットのサーバーに使います。
- クロスサイトで送られるセッション Cookie には、`SameSite=None` と `Secure` も必要です。[セッション](sessions.md) を参照してください。

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

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

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

- `server.forward-headers-strategy` を設定し、リクエストがプロキシのヘッダーから実際のスキーム、ホスト、ポートを知るようにします ([リバースプロキシの背後で](server/reverse-proxy.md) を参照)。
- 他のサイトが呼ぶパスだけに CORS のルールを付けます (`/**` ではなく `/api/public/**`)。
- サイト自身のオリジンと、そのページが送るすべてのメソッドを列挙します。
- アプリケーションで TLS を終端します ([SSL](server/ssl.md) を参照)。

## ルールが適用される場所

- **コントローラー:** ハンドラーのルール (Bean のもの、またはグローバルのものと `@CrossOrigin` を組み合わせたもの)。
- **静的リソース:** Spring がリソースハンドラーマッピングに与えるのと同じく、グローバルのルール (`addCorsMappings`、または Bean のもの)。[静的リソース](static-resources.md) を参照してください。
- **`404`** (ハンドラーなし): グローバルのルール。
- **その他のハンドラーマッピング** (WebSocket エンドポイント): Bean がルールを持つ場所でのみ、Bean のルール。`addCorsMappings` のルールと `@CrossOrigin` はコントローラーのためのものです。WebSocket エンドポイントはハンドシェイクの `Origin` を自分でチェックします。[WebSocket](server/websocket.md) を参照してください。

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

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

## Spring (Java) との対応

```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);
}
```

重要な違い:

- `CorsRegistration` のリストを受け取るメソッドはリストに追加します。Spring のものは置き換えます。可変長引数ではなくリストを受け取ります。`maxAge` は `Duration` を受け取ります。
- `corsConfigurationSource` Bean はルーターも適用するため、CORS はセキュリティスターターの有無にかかわらず同じように動きます。Spring MVC 単体ではそうした Bean を読みません。
- `@CrossOrigin` のルールを持つ複数のハンドラーに一致するプリフライトは、最初のハンドラーのルールから応答されます。Spring は任意のオリジンからクレデンシャル付きで許可します。
- 1024 文字を超える `Origin`、または可視の US-ASCII 以外の文字を含む `Origin` は拒否されます。Spring は後者をそのまま返します。
- オリジンパターンは線形時間で照合されます。Spring の正規表現は、`*` が複数あると、オリジンの長さの 2 乗や 3 乗の時間がかかることがあります。

## 関連項目

- [WebMvcConfigurer](web-mvc-configurer.md)
- [フィルター](filters.md)
- [静的リソース](static-resources.md)
- [リバースプロキシの背後で](server/reverse-proxy.md)
- [起動時のチェック](controllers/startup-checks.md)
- [WebSocket](server/websocket.md)
