
# フィルターチェーン

すべてのリクエストは、ルーターに届く前にセキュリティフィルターのチェーンを通過します。ユーザーを読み込むもの、ヘッダーを書き込むもの、CSRF トークンをチェックするもの、ユーザーをログインさせるもの、アクセスルールをチェックするものがあります。チェーンは `SecurityFilterChain` Bean の中で `HttpSecurity` を使って記述します。それがなければ、スターターはすべてにログインを要求するデフォルトのチェーンを作ります。

## 使う理由

セキュリティのチェックはコントローラーの手前の一か所に置くべきです。そうすれば新しいエンドポイントはデフォルトで保護され、どのコントローラーもチェックを忘れることがありません。チェーンがその場所です。`HttpSecurity` は読みやすいステップからチェーンを組み立て、スターターは組み込みフィルターを正しい順序に並べます。

## 例

```dart
@Configuration()
class SecurityConfig {
  // API: トークン、セッションなし、CSRF なし (偽造される Cookie がない)。
  @Bean()
  @Order(1)
  SecurityFilterChain api(HttpSecurity http) => http
      .securityMatcher('/api/**')
      .authorizeHttpRequests((auth) => auth.anyRequest().authenticated())
      .oauth2ResourceServer((server) => server.jwt())
      .sessionManagement((s) => s.sessionCreationPolicy(SessionCreationPolicy.stateless))
      .build();

  // それ以外すべて: ログインフォームのあるページ。すべてのリクエストに一致するので、最後に置く。
  @Bean()
  @Order(2)
  SecurityFilterChain web(HttpSecurity http) => http
      .authorizeHttpRequests((auth) => auth
          .requestMatchers('/', '/public/**', '/sign-in').permitAll()
          .anyRequest().authenticated())
      .formLogin((form) => form.loginPage('/sign-in'))
      .addFilterAfter(AuditFilter(), UsernamePasswordAuthenticationFilter)
      .build();
}
```

## デフォルトのチェーン

`SecurityFilterChain` Bean がなければ、Spring Boot と同じくスターターが一つ宣言します。

- すべてのリクエストにログインが必要です (`anyRequest().authenticated()`)。
- 生成されたページによるフォームログインと、HTTP Basic。
- `spring.security.oauth2.resourceserver.jwt.issuer-uri`、`jwk-set-uri`、`secret-key` のどれか、または `JwtDecoder` Bean がある場合: 代わりに Bearer トークンになり、デフォルトのユーザーはありません。
- OAuth2 クライアントの登録がある場合: `oauth2Login()`。`JwtDecoder` があれば Bearer トークンも。
- CSRF、ヘッダー、CORS、ログアウト、匿名ユーザー。

`HttpSecurity` を受け取る Bean メソッドは、それぞれ新しいビルダーを受け取ります。

## HttpSecurity

| ステップ | 設定するもの |
|---|---|
| `securityMatcher(pattern, ...)`、`securityMatcherOf(matcher)` | このチェーンが扱うリクエスト。ない場合はすべて。 |
| `authorizeHttpRequests((auth) => ...)` | アクセスルール ([リクエストのルール](authorize-http-requests.md) を参照)。 |
| `formLogin([customizer])` | フォームによるログイン ([フォームログインと HTTP Basic](form-login.md) を参照)。 |
| `httpBasic([customizer])` | HTTP Basic。 |
| `oauth2ResourceServer((s) => s.jwt())` | Bearer トークンと DPoP トークン ([JWT リソースサーバー](jwt.md) を参照)。 |
| `oauth2Login([customizer])` | シングルサインオン ([シングルサインオン](oauth2-login.md) を参照)。 |
| `csrf((c) => ...)` | CSRF 保護 ([CSRF](csrf.md) を参照)。 |
| `cors([customizer])` | CORS ([ヘッダーと CORS](headers-and-cors.md) を参照)。 |
| `headers((h) => ...)` | セキュリティヘッダー。 |
| `sessionManagement((s) => ...)` | セッション ([セッション](sessions.md) を参照)。 |
| `logout((l) => ...)` | ログアウトのエンドポイント。 |
| `exceptionHandling((e) => ...)` | `authenticationEntryPoint` (ログインが必要なクライアントが受け取るもの)、`accessDeniedHandler` (拒否されたクライアントが受け取るもの)。 |
| `anonymous((a) => ...)` | 匿名ユーザー。`a.disable()` で取り除く。 |
| `requestCache((r) => ...)` | ログイン後に戻るページを保持する場所。 |
| `securityContext((s) => ...)` | リクエストの間でユーザーを保持する `SecurityContextRepository`。 |
| `authenticationManager(manager)`、`userDetailsService(service)` | このチェーンだけのユーザー。 |
| `addFilterBefore`、`addFilterAfter`、`addFilterAt` | 組み込みフィルターのクラスを基準にした独自の `WebFilter`。 |
| `build()` | `SecurityFilterChain`。 |

どのカスタマイザーも、コンフィギュラーを受け取る関数を取ります: `csrf((c) => c.disable())`。

## 複数のチェーン

- `securityMatcher('/api/**')` はチェーンを一部のパスに限定します。Bean の順序は `@Order` で決めます。マッチャーが一致した最初のチェーンがリクエストを扱います。
- すべてのリクエストに一致するチェーンは最後に置かなければなりません。そうしないと起動が失敗します。
- どのチェーンにも一致しないリクエストは、Spring と同じく、セキュリティフィルターなしで先へ進みます。`securityMatcher` のない最後のチェーンを置いてください。
- `authorizeHttpRequests` のないチェーンは、ログに警告を出したうえで、すべてのリクエストを通します。

## 組み込みフィルター

実行される順序 (`SecurityFilterOrder`):

| 順序 | フィルター | 処理 |
|---|---|---|
| 100 | `SecurityContextHolderFilter` | リクエストのユーザーを、そのリクエスト専用のセキュリティコンテキストのスコープに読み込む。 |
| 200 | `HeaderWriterFilter` | セキュリティヘッダーを書き込む。 |
| 300 | `CorsFilter` | プリフライトに応答し、オリジンをチェックする。 |
| 400 | `CsrfFilter` | CSRF トークンをチェックする。 |
| 500 | `LogoutFilter` | `POST /logout` でログアウトさせる。 |
| 520、560 | OAuth2 ログインのフィルター | プロバイダーへのリダイレクトと、コールバック。 |
| 600 | `UsernamePasswordAuthenticationFilter` | フォームログイン。 |
| 700、800 | `DefaultLoginPageGeneratingFilter`、`DefaultLogoutPageGeneratingFilter` | 生成されるページ。 |
| 890 | `DPoPAuthenticationFilter` | DPoP にバインドされたトークン。 |
| 900 | `BearerTokenAuthenticationFilter` | Bearer トークン。 |
| 1000 | `BasicAuthenticationFilter` | HTTP Basic。 |
| 1100 | `SecurityContextHolderAwareRequestFilter` | コントローラーのためのリクエストのユーザー。 |
| 1200 | `AnonymousAuthenticationFilter` | 誰もログインしていないときの匿名ユーザー。 |
| 1300 | `ExceptionTranslationFilter` | セキュリティの例外を `401`、ログインへのリダイレクト、または `403` に変換する。 |
| 1400 | `AuthorizationFilter` | アクセスルールをチェックする。 |

## 独自のフィルター

`WebFilter` (通常は `OncePerRequestFilter`) は、組み込みフィルターのクラスを基準に配置します。

```dart
final class AuditFilter extends OncePerRequestFilter {
  @override
  Future<void> doFilterInternal(
    ServerHttpRequest request,
    ServerHttpResponse response,
    WebFilterChain chain,
  ) {
    final user = SecurityContextHolder.getContext().authentication?.name;
    SpringLog('audit').info('${request.method} ${request.uri.path} by $user');
    return chain.doFilter(request, response);
  }
}

// チェーンの中で:
.addFilterAfter(AuditFilter(), AuthorizationFilter)
```

`addFilterAt` は、組み込みフィルターの位置、つまりその直後に置きます。組み込みフィルターは残ります。組み込みフィルターでないクラスを指定すると `ArgumentError` になります。

## チェーンが実行される場所

セキュリティチェーン全体は Web スターターの一つの Web フィルターで、他の `WebFilter` Bean の間の `spring.security.filter.order` (デフォルトは `-100`) の位置にあります。順序の値が小さいフィルターはセキュリティより前に、大きいものは後に実行されます。

## リクエストより長く残る認証

すべてのリクエストは独自のセキュリティコンテキストで実行され、コンテキストはリクエストとともに終わります。リクエストの外のコードは、自分でスコープを開かないかぎりコンテキストを持ちません。`@Scheduled` メソッド、タイマー、起動時に開いたストリームのリスナーなどです。そこで設定した認証 (`SecurityContextHolder.getContext().authentication = ...`) は、プログラム全体に一つだけのコンテキストに入り、そのまま残ります。リクエストの外で動く他のすべてのコードが、そのユーザーとして動くことになります。

- **ログ。** コードの新しい場所からそれが起こるたびに、`spring.security.context.ProgramWideAuthentication` の WARN が、その場所と認証の種類を示します。ユーザーは決して示しません。拒否されるものはありません。意図してそうするアプリケーション (バックグラウンド処理全体に一人のシステムユーザー) は、そのロガーを `error` にします。
- **ヘルス。** `management.health.securityContext.enabled=true` にすると、`/actuator/health` に `securityContext` が加わります。常に `UP` で、`programWideAuthentication` (今あるかどうか) と `setOutsideRequests` (起動からの回数) を持ちます。デフォルトではオフなので、ヘルスは Spring Boot と同じです。
- **直し方**は、その処理のためのスコープです。

```dart
await SecurityContextHolder.runWithContext(
  () => reports.sendFor(user),
  SecurityContextImpl(authentication),
);
```

どちらも、もはや認証ではないものは見ません。キャッシュにあるユーザーの行、フィールドにある結果などです。それらには、複数のユーザーの同時リクエストでテストします: `withMockUsersAtOnce` ([テスト](testing.md) を参照)。Spring Security と Spring Boot には、このログもインジケーターもありません。

## Spring (Java) との対応

```java
@Bean
@Order(1)
SecurityFilterChain api(HttpSecurity http) throws Exception {
  return http.securityMatcher("/api/**")
      .authorizeHttpRequests(auth -> auth.anyRequest().authenticated())
      .oauth2ResourceServer(o -> o.jwt(Customizer.withDefaults()))
      .build();
}
```

ビルダーは Spring のものです。設定を取らないカスタマイザーは省略できます (`formLogin(Customizer.withDefaults())` の代わりに `formLogin()`)。

## 関連項目

- [リクエストのルール](authorize-http-requests.md)
- [フィルター](../spring-boot-starter-web/filters.md)
- [Spring との違い](differences.md)
