
# リクエストのルール

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

## 使う理由

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

## 例

```dart
@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(...))` でこれらの応答を変更できます。

## 経験則

- **デフォルトで拒否する。** `anyRequest().authenticated()` か `denyAll()` で終えてください。どのルールにも一致しないリクエストはいずれにせよ拒否されますが、明示しましょう。
- **具体的なものを先に。** 最初の一致が優先されます: `/api/**` より前に `/api/admin/**`。
- **ログインページには全員が届くようにする。** ログインページが必要とするエラーと静的リソースも同様です。
- **ユーザーに依存するデータ (「自分の注文」) をルールだけに頼らない。** サービスでメソッドセキュリティを使うか、クエリでチェックしてください。

## Spring (Java) との対応

```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` を使ってください)。

## 関連項目

- [フィルターチェーン](filter-chain.md)
- [メソッドセキュリティ](../spring-security-core/method-security.md)
- [@RequestMapping](../spring-boot-starter-web/controllers/request-mapping.md)
