リクエストのルール

authorizeHttpRequests はチェーンのアクセスルールを列挙します。リクエストの集合ごとに、呼び出し元に何が必要かを指定します。最初に一致したルールが判断し、どのルールにも一致しないリクエストは拒否されます。ルールはルーターのパスパターンを使うため、ルールはその下のコントローラーが提供するものをちょうど覆います。

使う理由

URL のルールは、アプリケーションのある領域全体 (/api/admin/**) を、後から追加されるエンドポイントも含めて一度に保護します。メソッドセキュリティは、一つのサービスメソッドを、どこから呼ばれても保護します。ほとんどのアプリケーションは両方を使います。パスには大まかなルール、サービスにはより細かいルールです。

例

@Bean()
SecurityFilterChain filterChain(HttpSecurity http) => http
    .authorizeHttpRequests((auth) => auth
        .requestMatchers('/', '/public/**', '/login').permitAll()
        .requestMatchers('/api/admin/**').hasRole('ADMIN')
        .requestMatchersFor(HttpMethod.get, ['/api/books/**']).permitAll()
        .requestMatchersFor(HttpMethod.delete, ['/api/books/**']).hasAnyRole(['ADMIN', 'EDITOR'])
        .requestMatchers('/api/orders/**').hasAuthority('SCOPE_orders')
        // ユーザーは自分のプロフィールだけを読み、変更できる。管理者はすべて。
        .requestMatchers('/users/{id}/**').access(const SelfOrAdmin())
        .requestMatchers('/sign-up').anonymous()
        .anyRequest().authenticated())
    .formLogin()
    .build();

final class SelfOrAdmin implements AuthorizationManager<RequestAuthorizationContext> {
  const SelfOrAdmin();

  @override
  AuthorizationResult authorize(
    Authentication? Function() authentication,
    RequestAuthorizationContext context,
  ) {
    final user = authentication();
    final admin = user != null && user.authorities.any((a) => a.authority == 'ROLE_ADMIN');
    return AuthorizationDecision(
      admin ||
          (user != null &&
              user is! AnonymousAuthenticationToken &&
              user.name == context.variables['id']),
    );
  }
}

リクエストを選ぶ

呼び出し 対象のリクエスト
requestMatchers(pattern, ...) パスが最大六つのルーターパターンのいずれかに一致するもの。メソッドは問わない。
requestMatchersFor(method, [patterns]) その HttpMethod (null なら任意) で、パスが一致するもの。Spring の requestMatchers(HttpMethod, ...)。
requestMatchersOf([matchers]) いずれかの RequestMatcher に一致するもの。
anyRequest() それより前のどのルールにも一致しなかったすべてのリクエスト。最後のルールでなければならない。

パターンはルーターのものです: /api/**、/users/{id}、/files/*.pdf。コンテキストパスを除いた、ルーターが見るパスに対して照合されます。パスは大文字と小文字を区別し、末尾のスラッシュも意味を持ちます。/admin と /admin/** の両方がある場合は、両方を保護してください。

リクエストマッチャー

マッチャー 一致するもの
PathPatternRequestMatcher(pattern, method:) パスパターン。メソッドを伴うこともある。
HttpMethodRequestMatcher(method) メソッド。
RequestHeaderRequestMatcher(name, [value]) ヘッダーがある、またはその値を持つ。
MediaTypeRequestMatcher(...) Accept のメディアタイプ。
AndRequestMatcher([...])、OrRequestMatcher([...])、NegatedRequestMatcher(m) 組み合わせ。
AnyRequestMatcher.instance すべてのリクエスト。

独自の判定には RequestMatcher を実装します (または SimpleRequestMatcher を継承して matches(request) を書きます)。

リクエストに必要なもの

呼び出し 通すもの
permitAll() ログインしているかにかかわらず全員。公開ページ、ログインページ、静的アセット。
denyAll() 誰も通さない。
authenticated() ログインしたユーザー。匿名ユーザーにはログインが求められる。
fullyAuthenticated() ここでは authenticated() と同じ (remember-me がないため)。
anonymous() ログインしていないユーザーだけ (サインアップページ)。ログイン済みのユーザーは 403 を受け取る。
hasRole('ADMIN') 権限 ROLE_ADMIN。ROLE_ADMIN と書くと ArgumentError。
hasAnyRole([...]) いずれかのロール。それぞれプレフィックスなしで書く。
hasAuthority('SCOPE_read') 完全な名前で書いた権限。
hasAnyAuthority([...]) いずれかの権限。
access(manager) AuthorizationManager<RequestAuthorizationContext> が決めたもの。マネージャーはリクエストと、ルールのパターンのパス変数 (context.variables['id']) を受け取る。棄権 (null) は拒否になる。

ロールと権限のチェックは RoleHierarchy Bean を使い、hasRole は GrantedAuthorityDefaults Bean のプレフィックス (なければ ROLE_) を使います。AuthorizationManagers.anyOf と allOf はマネージャーを組み合わせます。

拒否されたリクエストが受け取るもの

呼び出し元 応答
ログインしていない、ページを求めるブラウザー ログインページへのリダイレクト。ページはログイン後のために保存される。
ログインしていない、プログラム (curl、JSON) WWW-Authenticate: Basic (リソースサーバーでは Bearer) 付きの 401。
ログインしていない、スクリプト (X-Requested-With: XMLHttpRequest) 単なる 401。ブラウザーのパスワードダイアログは表示されない。
ログイン済み、許可されていない ProblemDetail としての 403。

exceptionHandling((e) => e.authenticationEntryPoint(...).accessDeniedHandler(...)) でこれらの応答を変更できます。

経験則

Spring (Java) との対応

http.authorizeHttpRequests(auth -> auth
    .requestMatchers("/public/**").permitAll()
    .requestMatchers(HttpMethod.GET, "/api/books/**").permitAll()
    .requestMatchers("/users/{id}/**").access(new SelfOrAdmin())
    .anyRequest().authenticated());

呼び出しは同じですが、メソッドの指定には requestMatchersFor (オーバーロードがないため)、マッチャーには requestMatchersOf を使います。ここにないもの: hasIpAddress、正規表現のマッチャー、リクエストルールでの SpEL (access はマネージャーを取ります)、hasAllAuthorities (AuthorizationManagers.allOf を使ってください)。

関連項目