フィルターチェーン

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

使う理由

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

例

@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 と同じくスターターが一つ宣言します。

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

HttpSecurity

ステップ 設定するもの
securityMatcher(pattern, ...)、securityMatcherOf(matcher) このチェーンが扱うリクエスト。ない場合はすべて。
authorizeHttpRequests((auth) => ...) アクセスルール (リクエストのルール を参照)。
formLogin([customizer]) フォームによるログイン (フォームログインと HTTP Basic を参照)。
httpBasic([customizer]) HTTP Basic。
oauth2ResourceServer((s) => s.jwt()) Bearer トークンと DPoP トークン (JWT リソースサーバー を参照)。
oauth2Login([customizer]) シングルサインオン (シングルサインオン を参照)。
csrf((c) => ...) CSRF 保護 (CSRF を参照)。
cors([customizer]) CORS (ヘッダーと CORS を参照)。
headers((h) => ...) セキュリティヘッダー。
sessionManagement((s) => ...) セッション (セッション を参照)。
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())。

複数のチェーン

組み込みフィルター

実行される順序 (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) は、組み込みフィルターのクラスを基準に配置します。

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 = ...) は、プログラム全体に一つだけのコンテキストに入り、そのまま残ります。リクエストの外で動く他のすべてのコードが、そのユーザーとして動くことになります。

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

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

Spring (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())。

関連項目