
# spring_boot_starter_security

`spring_boot_starter_security` は、`spring_boot_starter_web` で作った Web アプリケーションを保護します。コントローラーの手前にあるフィルターチェーンが、誰がどのエンドポイントを呼べるかを決め、ユーザーをログインさせ (フォームログイン、HTTP Basic、Bearer トークン、シングルサインオン)、ブラウザーのセッションを CSRF から守り、ブラウザーを安全に保つヘッダーを送ります。Spring Boot の `spring-boot-starter-security` の Dart への移植です。

## 使う理由

公開されていないエンドポイントを一つでも持つサーバーは、誰が呼んでいるかを知り、そのユーザーに許されないことを拒否し、他のサイトのページがユーザーのセッションを使えないようにし、安全なヘッダーを送らなければなりません。これらのチェックをすべてのコントローラーに書くと、間違えやすくなります。このスターターを使えば、チェックは一か所にまとまり、どのコントローラーよりも前に実行され、依存関係に加えた時点で有効になります。

## セットアップ

```yaml
# pubspec.yaml
dependencies:
  spring_boot_starter_security: ^0.9.0

dev_dependencies:
  build_runner: ^2.17.0
  spring_core_dart_generator: ^0.9.0
  spring_boot_starter_test: ^0.9.0     # MockMvc、springBootTest
  test: ^1.33.0
```

Web スターター、[spring_security_core](../spring-security-core/index.md) (ユーザー、パスワードハッシュ、Bean のメソッドの `@PreAuthorize`)、[spring_boot_starter_oauth2_client](../spring-boot-starter-oauth2-client/index.md) (シングルサインオンの登録) を取り込むため、この依存関係一つで足ります。インポートは `package:spring_boot_starter_security/spring_boot_starter_security.dart` 一つで、三つすべてを再エクスポートします。

## 例

```dart
import 'package:spring_boot_starter_security/spring_boot_starter_security.dart';

import 'spring_gen/main.spring.dart';

@Configuration()
class SecurityConfig {
  @Bean()
  SecurityFilterChain filterChain(HttpSecurity http) => http
      .authorizeHttpRequests((auth) => auth
          .requestMatchers('/public/**').permitAll()
          .requestMatchers('/api/admin/**').hasRole('ADMIN')
          // カタログは誰でも読める。変更にはログインが必要。
          .requestMatchersFor(HttpMethod.get, ['/api/books/**']).permitAll()
          .anyRequest().authenticated())
      .formLogin()
      .httpBasic()
      .build();

  // ユーザーとそのハッシュ化されたパスワード。
  @Bean()
  UserDetailsService users() => InMemoryUserDetailsManager([
        User.withUsername('ada').password('{argon2}\$argon2id\$v=19\$...').roles(['ADMIN']).build(),
      ]);
}

@RestController()
class MeController {
  @GetMapping('/me')
  String me(Authentication authentication) => authentication.name;
}

@SpringBootApplication()
void main(List<String> args) => runApplication(args);
```

```bash
curl -i localhost:8080/me
# HTTP/1.1 401 Unauthorized
# www-authenticate: Basic realm="Realm"

curl -u ada:secret localhost:8080/me
# ada
```

## デフォルトで安全

スターターを加えて何も設定しない場合、Spring Boot と同じく次のようになります。

- すべてのリクエストにログインが必要です。
- ページを求めるブラウザーは、生成されたログインページ `/login` にリダイレクトされます。プログラムや `curl` は `WWW-Authenticate: Basic` 付きの `401` を受け取ります。スクリプト (`X-Requested-With: XMLHttpRequest`) は単なる `401` を受け取るため、ブラウザーのパスワードダイアログは表示されません。
- ユーザーは `user` 一人で、そのパスワードは `spring.security.user.password`、設定されていなければ起動時にログに出るランダムなものです (開発専用)。
- CSRF 保護、セキュリティヘッダー、ルーターのルールによる CORS、`POST /logout` でのログアウトが有効です。
- ファイアウォールが、どのルールを見るよりも前に曖昧なパスを拒否します。

```properties
# 生成されたパスワードの代わりに開発用のユーザー。
spring.security.user.name=admin
spring.security.user.password=change-me
spring.security.user.roles=ADMIN
```

アプリケーションが独自のユーザーを持った時点で、デフォルトのユーザーは消えます。独自のユーザーとは、`UserDetailsService`、`AuthenticationProvider`、`AuthenticationManager`、`JwtDecoder` の Bean、JWT のプロパティ、または OAuth2 クライアントの登録です (`spring.security.user.name` か `.password` が設定されている場合を除きます)。

## 内容

設定:

- [フィルターチェーン](filter-chain.md): `SecurityFilterChain`、`HttpSecurity`、複数のチェーン、独自のフィルター。
- [リクエストのルール](authorize-http-requests.md): `authorizeHttpRequests`、マッチャー、`access(...)`。
- [フォームログインと HTTP Basic](form-login.md): 生成されるページ、独自のログインページ、ログアウト。
- [セッション](sessions.md): セッション固定、`stateless`、ユーザーごとの上限。
- [CSRF](csrf.md): フォーム、シングルページアプリ、Flutter Web のためのトークン。
- [ヘッダーと CORS](headers-and-cors.md): HSTS、CSP、フレームオプション、ルーターの CORS ルール。

トークンとシングルサインオン:

- [JWT リソースサーバー](jwt.md): アイデンティティプロバイダーからの Bearer トークン。
- [DPoP にバインドされたトークン](dpop.md): クライアントの鍵にバインドされたトークン。
- [シングルサインオン](oauth2-login.md): `oauth2Login()`、Google、Apple、OpenID Connect のログアウト。

使い方:

- [コントローラーで](controllers.md): `Authentication`、`@AuthenticationPrincipal`、メソッドセキュリティ。
- [テスト](testing.md): ユーザーとしての `MockMvc`、`csrf()`、`jwt()`。
- [ファイアウォールと制限](firewall.md): 拒否されるパスと、リクエストごとの処理量の上限。

リファレンス:

- [すべてのプロパティ](properties.md): スターターのすべてのキー。
- [Spring との違い](differences.md): Spring Security と動作が異なる点。

## Spring (Java) との対応

```java
@Bean
SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
  return http
      .authorizeHttpRequests(auth -> auth
          .requestMatchers("/public/**").permitAll()
          .requestMatchers("/api/admin/**").hasRole("ADMIN")
          .requestMatchers(HttpMethod.GET, "/api/books/**").permitAll()
          .anyRequest().authenticated())
      .formLogin(Customizer.withDefaults())
      .httpBasic(Customizer.withDefaults())
      .build();
}
```

重要な違い:

- `requestMatchers(HttpMethod, ...)` は `requestMatchersFor` です。Dart にはオーバーロードがありません。
- どのルールにも一致しないリクエストは拒否されます。
- CORS はデフォルトで、ルーターのルールによって有効です。
- セッションを作るのはログインだけです。CSRF トークンと保存されたリクエストは署名付きの Cookie です。
- すべての違いは [Spring との違い](differences.md) にあります。

## 関連項目

- [spring_security_core](../spring-security-core/index.md)
- [spring_boot_starter_web](../spring-boot-starter-web/index.md)
- [spring_boot_starter_oauth2_client](../spring-boot-starter-oauth2-client/index.md)
- [ビルドに含まれるもの](optimizations.md)
