CSRF

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

使う理由

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

例

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

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

チェックされること

トークンの保存場所

リポジトリ トークンの保存場所 用途
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) がそれを返し、クライアントが持っていなければ作ります。

@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()) を追加してください (テスト を参照)。

Spring (Java) との対応

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

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

関連項目