
# セキュリティコンテキスト

すべてのセキュリティチェックは、`SecurityContextHolder` が保持するセキュリティコンテキストから現在のユーザーを読みます。コードがユーザーを受け渡すことはありません。呼び出しスタックの奥深くにあるサービスはホルダーに尋ね、リクエストのユーザー (サーバーでは) やアプリのユーザー (Flutter では) を受け取ります。

## 使う理由

ユーザーをパラメーターとしてすべての層に渡すのは面倒で、忘れやすいものです。グローバル変数に保持するのは、多くのリクエストが同時に動くサーバーでは誤りです。Spring はスレッドごとに保持します。Dart はスレッドが一つで、`await` のたびにリクエストを切り替えるため、コンテキストは `Zone` ごとに保持されます。各リクエストは、`await` の後でも自分のユーザーだけを見ます。

## 例

```dart
// 誰が呼んでいるかを、どこでも読める。
final authentication = SecurityContextHolder.getContext().authentication;
print(authentication?.name);

// Flutter アプリがユーザーをログインさせ、結果を保持する。
final result = await authenticationManager.authenticate(
  UsernamePasswordAuthenticationToken.unauthenticated(name, password),
);
SecurityContextHolder.setContext(SecurityContextImpl(result));

// ...そしてログアウトする。
SecurityContextHolder.clearContext();

// 夜間のジョブが、システムユーザーとして保護されたサービスを呼ぶ。
await SecurityContextHolder.runWithContext(
  () => reports.rebuildAll(),
  SecurityContextImpl(
    UsernamePasswordAuthenticationToken.authenticated(
      'system',
      null,
      [SimpleGrantedAuthority('ROLE_ADMIN')],
    ),
  ),
);
```

## ホルダー

| 呼び出し | 働き |
|---|---|
| `SecurityContextHolder.getContext()` | 現在のコンテキスト。なければ空のものが作られるため、結果が `null` になることはない。 |
| `SecurityContextHolder.setContext(context)` | `context` を、現在のスコープの中でだけ現在のものにする。 |
| `SecurityContextHolder.clearContext()` | 現在のコンテキストを取り除く。ログアウト。 |
| `SecurityContextHolder.runWithContext(body, [context])` | `body` を独自のコンテキスト (省略すれば空) で実行し、その戻り値を返す。 |
| `SecurityContextHolder.setContextHolderStrategy(strategy)` | ストラテジーを置き換える。必要になることはまれ。 |

`SecurityContext` は `authentication` を一つ保持し、誰もログインしていなければ `null` です。ログイン時は、現在のコンテキストを変更するより、新しい `SecurityContextImpl` を保存してください。コンテキストのオブジェクトは他のコードと共有されていることがあります。

## スコープ

デフォルトのストラテジー `ZoneSecurityContextHolderStrategy` は、サーバーにも Flutter アプリにも適しています。

- **各 `runWithContext` のスコープは独自のコンテキストを持ちます。** それは `body` と、`body` が始めるすべてのもの (`await`、タイマー、ストリーム) の中で現在のものになり、その後は消えます。内部で行った変更 (ログイン、`clearContext`) は内部にとどまります。二つのリクエストのように同時に動くスコープが混ざることはありません。
- **サーバーでは**、セキュリティスターターが各リクエストを独自のスコープで実行します。
- **どのスコープの外でも**、プログラム全体に一つのコンテキストがあります。Flutter アプリでは、それがログイン中のユーザーです。
- **サーバーでは、どのスコープの外で設定した認証も残り続けます。** リクエストの外で動くすべてのコード (スケジュールされた処理、タイマー、リスナー) が、そのユーザーとして動くことになります。ストラテジーの `onProgramWideAuthentication` は、そこに認証が設定されるたびに、その場所とともに知らされ、`programWideAuthentication` は今そこにいるユーザーです。セキュリティスターターはこれを通じて WARN をログに出し、ヘルスにも表示できます ([spring_boot_starter_security](../spring-boot-starter-security/index.md) を参照)。拒否されるものはありません。Spring にこのような報告はありません。

`GlobalSecurityContextHolderStrategy` は、すべてに対して一つのコンテキストを保持します。これを使うと、`runWithContext` は `body` が戻るとすぐに以前のコンテキストを戻します。`async` の本体の場合は最初の `await` の時点です。同期的なプログラムでだけ使ってください。

## Authentication

| メンバー | 意味 |
|---|---|
| `name` | ユーザーの名前。 |
| `principal` | ユーザー。パスワードログイン後は `UserDetails`、Bearer トークンでは `Jwt`、シングルサインオン後は `OAuth2User`。 |
| `credentials` | パスワードまたはトークン。ログイン後に消去され、式からは決して読めない。 |
| `authorities` | `GrantedAuthority` のリスト: `ROLE_ADMIN`、`SCOPE_orders.read`。 |
| `isAuthenticated` | チェック済みかどうか。 |

`UsernamePasswordAuthenticationToken.unauthenticated(name, password)` はログインのリクエストで、`UsernamePasswordAuthenticationToken.authenticated(principal, credentials, authorities)` はログイン済みのユーザーです。`AnonymousAuthenticationToken` は、ログインのない Web リクエストの匿名ユーザーです。

## ログインとログアウトの受信

ストラテジーを、`SecurityContextChangedListener` を持つ `ListeningSecurityContextHolderStrategy` で包みます。`setContext` と `clearContext` のたびに、前後のコンテキストを持つ `SecurityContextChangedEvent` がリスナーに渡されます。

```dart
class LoginAudit implements SecurityContextChangedListener {
  @override
  void securityContextChanged(SecurityContextChangedEvent event) =>
      print('now: ${event.newContext?.authentication?.name}');
}

// 起動時に一度。
SecurityContextHolder.setContextHolderStrategy(
  ListeningSecurityContextHolderStrategy(
    SecurityContextHolder.getContextHolderStrategy(),
    [LoginAudit()],
  ),
);
```

見えるのはホルダーを通じて行われた変更だけです。コンテキストのオブジェクトの `authentication` をその場で変更するコードは通知しません。`runWithContext` のスコープの中の変更も報告されます。

`spring_boot_starter_flutter_security` は、ウィジェットがログイン中のユーザーに追従するよう、これを行います。

## Spring (Java) との対応

```java
Authentication authentication = SecurityContextHolder.getContext().getAuthentication();
```

名前は Spring Security のものです。コンテキストはスレッドごとではなく `Zone` ごとに保持され、ユーザーとして処理を実行するには、`DelegatingSecurityContextRunnable` の仲間の代わりに `runWithContext` を使います。

## 関連項目

- [認証](authentication.md)
- [メソッドセキュリティ](method-security.md)
- [テスト](testing.md)
