
# CSRF

クロスサイトリクエストフォージェリとは、他のサイトのページがユーザーのブラウザーに、ユーザーの Cookie 付きでアプリケーションへのリクエストを送らせることです。CSRF 保護は、状態を変えるすべてのリクエストに、そうしたページが知りえないトークンを持たせます。デフォルトで有効です。

## 使う理由

ブラウザーは、誰が始めたかにかかわらず、サイトへのすべてのリクエストに Cookie を付けて送ります。トークンがなければ、`evil.example` の隠しフォームが、ログイン中のユーザーとして `/api/transfer` に POST できます。他のページはあなたのページも Cookie も読めないため、トークンを知ることができず、そのリクエストは失敗します。

## 例

シングルページアプリや Flutter Web アプリは、トークンを Cookie から読み、ヘッダーで送り返します。

```dart
@Bean()
SecurityFilterChain filterChain(HttpSecurity http) => http
    .authorizeHttpRequests((auth) => auth.anyRequest().authenticated())
    .formLogin()
    .csrf((c) => c
        // スクリプトが読める Cookie...
        .csrfTokenRepository(const CookieCsrfTokenRepository.withHttpOnlyFalse())
        // ...その生の値をスクリプトが送り返す。マスクされたトークンではない。
        .csrfTokenRequestHandler(const CsrfTokenRequestAttributeHandler())
        // サードパーティがこのパスに POST する。独自の署名チェックがある。
        .ignoringRequestMatchers('/webhooks/**'))
    // 最初の POST より前に Cookie を持たせる。
    .addFilterAfter(CsrfCookieFilter(), CsrfFilter)
    .build();

// トークンを読むと、新しい場合は XSRF-TOKEN Cookie が書き込まれる。
final class CsrfCookieFilter extends OncePerRequestFilter {
  @override
  Future<void> doFilterInternal(
    ServerHttpRequest request,
    ServerHttpResponse response,
    WebFilterChain chain,
  ) {
    csrfTokenOf(request);
    return chain.doFilter(request, response);
  }
}
```

```javascript
// ブラウザー側: Cookie の値をヘッダーで送り返す。
fetch('/api/books', {
  method: 'POST',
  credentials: 'include',
  headers: {'X-XSRF-TOKEN': readCookie('XSRF-TOKEN'), 'Content-Type': 'application/json'},
  body: JSON.stringify(book),
});
```

## チェックされること

- `GET`、`HEAD`、`TRACE`、`OPTIONS` を除くすべてのメソッドは、ヘッダー (デフォルトの Cookie リポジトリでは `X-XSRF-TOKEN`) かフォームフィールド `_csrf` にトークンを必要とします。
- クライアントのトークンがまだ保存されていない (最初のリクエスト): `403`。次の試行のために新しいトークンが作られます。
- リクエストにトークンがない、または保存されたものと等しくない (定数時間で比較): `403`。
- `403` は匿名ユーザーにも返されます。ログインは求められません。トークンなしで POST されたログインフォームも拒否されます。

## トークンの保存場所

| リポジトリ | トークンの保存場所 | 用途 |
|---|---|---|
| `CookieCsrfTokenRepository()` (デフォルト) | Cookie `XSRF-TOKEN`、`HttpOnly`、`SameSite=Lax`、ヘッダー `X-XSRF-TOKEN` | サーバーが描画するページ |
| `CookieCsrfTokenRepository.withHttpOnlyFalse()` | 同じ Cookie。スクリプトから読める | シングルページアプリと Flutter Web アプリ |
| `HttpSessionCsrfTokenRepository()` | セッション、ヘッダー `X-CSRF-TOKEN` | Spring のデフォルト。訪問者ごとにセッションを作る |

`CookieCsrfTokenRepository` は `cookieName`、`headerName`、`parameterName`、`cookieHttpOnly`、`cookiePath`、`cookieDomain`、`sameSite` を取ります。トークンは、何かがそれを読むか、チェックが必要としたときにだけ作られます。

## サーバーが描画するページ

各フォームに隠しフィールドとしてトークンを入れます。`csrfTokenOf(request)` がそれを返し、クライアントが持っていなければ作ります。

```dart
@GetMapping('/form')
String form(ServerHttpRequest request) {
  final csrf = csrfTokenOf(request)!;
  return '<form method="post" action="/books">'
      '<input type="hidden" name="${csrf.parameterName}" value="${csrf.token}">'
      '<button>Add</button></form>';
}
```

デフォルトでは、各ページは新しいランダムなバイトでマスクされたトークンを受け取ります (`XorCsrfTokenRequestAttributeHandler`)。そのためバイト列が二度同じになることはなく、圧縮された応答のサイズから推測することもできません (BREACH)。

## シングルページアプリと Flutter Web アプリ

これらはフォームを描画しません。`XSRF-TOKEN` Cookie からトークンを読み、`X-XSRF-TOKEN` ヘッダーで送ります。そのためには、例のように二つの設定を組み合わせる必要があります。スクリプトが読める Cookie と、生の値を受け入れるハンドラー (`CsrfTokenRequestAttributeHandler`) です。Cookie だけでは、デフォルトのハンドラーがマスクされたトークンを期待し、生の値は `403` で拒否されます。最初の `POST` より前に Cookie が存在するよう、すべてのリクエストでトークンを読むフィルターを追加してください。

## 除外

| 状況 | CSRF |
|---|---|
| `csrf((c) => c.ignoringRequestMatchers('/webhooks/**'))` | それらのパスは除外される (一回の呼び出しで最大四つのパターン。何度でも呼べる)。 |
| `oauth2ResourceServer()` を持つチェーンでの、`Authorization: Bearer`、または証明付きの `DPoP` を持つリクエスト | Spring と同じく除外される。ブラウザーはこれらのヘッダーを自分から付けることはなく、トークンがリクエストをログインさせるか、`401` で拒否される。チェーンのブラウザーセッションのリクエストはチェックを保つ。 |
| `access_token` クエリパラメーターのトークン | 決して除外されない。どのページもそうした URL にフォームを POST できるため。 |
| チェーンのログアウト URL とフォームログインの URL | トークンのヘッダーがあってもチェックを保つ。それらのフィルターは、トークンを見るより前にブラウザーのセッションに作用するため (Spring は除外する)。 |
| `oauth2Login()` のコールバックの `POST` (`response_mode=form_post`) | 除外される。ブラウザーに結び付いた `state` が保護する。 |

トークンのフィルターより前に置いた独自のフィルターは、トークンを使うリクエストを、そのトークンがチェックされる前に見ます。そのリクエストのためにセッションに作用してはいけません。

## 無効にする

`csrf((c) => c.disable())` は、クライアントがクレデンシャルをヘッダー (Basic、Bearer トークン) だけで送り、Cookie では決して送らないチェーンのためのものです。ブラウザーはそれらのヘッダーを自分から送らないため、他のサイトがそうしたリクエストを偽造することはできません。CSRF 保護のないブラウザーセッションは、ユーザーが訪れるどのページからでも使えてしまいます。無効にすると、`GET /logout` でもログアウトできるようになります。

## テストでは

状態を変える `MockMvc` のリクエストにはトークンが必要です。`..with_(csrf())` を追加してください ([テスト](testing.md) を参照)。

## Spring (Java) との対応

```java
http.csrf(c -> c
    .csrfTokenRepository(CookieCsrfTokenRepository.withHttpOnlyFalse())
    .csrfTokenRequestHandler(new CsrfTokenRequestAttributeHandler()));
```

クラスは Spring のものです。違い: デフォルトのリポジトリはセッションではなく Cookie なので、ログインしていない訪問者はセッションを作りません。リクエストを除外するのはヘッダーのトークンだけです (Spring は `BearerTokenResolver` が見つけたものを除外し、これにはフォームフィールドが含まれることがあります)。ログアウトとログインの URL は、トークンのヘッダーがあってもチェックを保ちます。`csrf.spa()` はまだありません。

## 関連項目

- [セッション](sessions.md)
- [JWT リソースサーバー](jwt.md)
- [シングルサインオン](oauth2-login.md)
