フィルターチェーン
すべてのリクエストは、ルーターに届く前にセキュリティフィルターのチェーンを通過します。ユーザーを読み込むもの、ヘッダーを書き込むもの、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 と同じくスターターが一つ宣言します。
- すべてのリクエストにログインが必要です (
anyRequest().authenticated())。 - 生成されたページによるフォームログインと、HTTP Basic。
spring.security.oauth2.resourceserver.jwt.issuer-uri、jwk-set-uri、secret-keyのどれか、またはJwtDecoderBean がある場合: 代わりに Bearer トークンになり、デフォルトのユーザーはありません。- OAuth2 クライアントの登録がある場合:
oauth2Login()。JwtDecoderがあれば Bearer トークンも。 - CSRF、ヘッダー、CORS、ログアウト、匿名ユーザー。
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())。
複数のチェーン
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) は、組み込みフィルターのクラスを基準に配置します。
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 と同じです。 - 直し方は、その処理のためのスコープです。
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())。