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),
});
チェックされること
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) がそれを返し、クライアントが持っていなければ作ります。
@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() はまだありません。