
# LoginSession と共有インターフェース

クライアントアプリケーション (Flutter アプリ、コマンドラインツール) のユーザーは一度に一人で、何らかのプロバイダーがログインさせます。OAuth 2.0 / OpenID Connect のプロバイダー、Supabase のような BaaS、独自のログインなどです。ログインの方法は違っても、アプリケーションの他の部分が必要とするものは同じです。`spring_security_core` は、その共通部分をインターフェースだけで持っています。プロバイダーやプラットフォームのコードはないので、Dart が動く場所ならどこでも使えます。

## 使う理由

ユーザーのトークンを付ける HTTP クライアント、ユーザーの名前を表示するウィジェット、ルートのガードは、どのプロバイダーがユーザーをログインさせたかを知るべきではありません。`LoginSession` に対して書けば、一度書くだけで済みます。そしてプロバイダーのログインは、Flutter に依存せずに、トークンを保管し (`SecretStore`)、ログインページを開けます (`AuthorizationWindow`)。プラットフォームの実装は別のパッケージにあります。

## 例

```dart
// Adds the user's token to a request, whatever logged the user in.
final class UserTokenHeaders {
  UserTokenHeaders(this.session);

  final LoginSession session;

  Future<Map<String, String>> headers() async {
    final token = await session.accessToken();
    return {if (token != null) 'authorization': 'Bearer $token'};
  }
}
```

## インターフェース

| 型 | 何であるか |
|---|---|
| `LoginSession` | 現在のログイン。誰がログインしているか、リクエストのためのトークン、前回の実行のログイン、ログアウト。 |
| `SecretStore` | ログインのトークンを実行と実行の間に保管する場所。キーごとの文字列。`InMemorySecretStore` は、テストと、安全なストレージのないプラットフォームのためのもの。 |
| `AuthorizationWindow` | システムのログインウィンドウに表示するプロバイダーのログインページと、戻ってくるリダイレクト。ユーザーが閉じると `AuthorizationCancelledException` を投げる。 |
| `OAuth2Token` | すべての OAuth 2.0 トークンが持つもの: `tokenValue`、`issuedAt`、`expiresAt`。 |
| `sha256Digest(bytes)`、`pkceS256Challenge(verifier)` | SHA-256 と、PKCE (RFC 7636) の `S256` コードチャレンジ。OAuth2 クライアントの上に作られていないログインのため。 |

これらはインターフェースと関数だけです。このパッケージは、それらの Bean を宣言しません。

## LoginSession

| メンバー | 意味 |
|---|---|
| `Authentication? get authentication` | 今ログインしている人、または `null`。読んでもリクエストは発生しない。 |
| `bool get isLoggedIn` | `authentication` が `null` でなく、認証済みであるかどうか。 |
| `Stream<Authentication?> get authenticationChanges` | 変更のたびのユーザー。ログイン、ユーザーのデータを変えた更新、そしてログアウトまたはプロバイダーが拒否した更新の後の `null`。ブロードキャストのストリームで、新しい購読者に現在の値を繰り返さないので、先に `authentication` を読むこと。 |
| `Future<String?> accessToken()` | 期限切れが近くないアクセストークン。誰もログインしていなければ `null`。期限が近いトークンは先に更新され、同時の呼び出しは一つの更新を共有する。 |
| `Future<Authentication?> restore()` | 実装が保管している場所から、前回の実行のログインを戻す。必要ならトークンを更新する。ログインがなかった、またはもう使えない場合は `null`。 |
| `Future<void> logout()` | ログインを終える。トークンは忘れられ (プロバイダーができる場合は取り消され)、セキュリティコンテキストは空になり、`authenticationChanges` は `null` を報告する。 |

実装が約束すること:

- **セキュリティコンテキストと歩調を合わせます。** 報告する `authentication` は、現在の[セキュリティコンテキスト](security-context.md)のものです。そのため、`@PreAuthorize` とコンテキストを読むコードは、同じユーザーを見ます。
- **拒否された更新は、ユーザーをログアウトさせます。** `accessToken()` は `null` で完了し、`authenticationChanges` は `null` を報告します。行えなかった更新 (ネットワークがない) は、エラーで完了し、誰もログアウトさせません。
- **ログアウトはプロバイダーに左右されません。** プロバイダーに伝えられなくても、ユーザーはここでログアウトされます。
- **トークンは資格情報です。** ログに出さず、実行と実行の間は `SecretStore` にだけ保管します。

ユーザーがどうログインするか (パスワード、ワンタイムコード、プロバイダーのページ) は、このインターフェースにはありません。各プロバイダー自身の型が持っています。

実装: Supabase スターターの [`SupabaseAuth`](../spring-boot-starter-supabase/auth.md)。Flutter セキュリティスターターの OAuth 2 ログイン (`OAuth2LoginService`) は独自の型で、このインターフェースは実装していません。

## SecretStore

```dart
abstract interface class SecretStore {
  Future<String?> read(String key);
  Future<void> write(String key, String value);
  Future<void> delete(String key);
  Future<Set<String>> keys();
  Future<void> deleteAll();
}
```

`InMemorySecretStore` は値をマップに保持します。アプリケーションが停止すると消えます。[spring_boot_starter_flutter_security](../spring-boot-starter-flutter-security/tokens-and-login-window.md) には、プラットフォームの安全なストレージ (Keychain、Keystore) の上の `PlatformSecretStore` があり、それをアプリケーションの `SecretStore` の Bean として宣言します。

## AuthorizationWindow

```dart
abstract interface class AuthorizationWindow {
  Future<Uri> authorize({
    required Uri redirectUri,
    required Uri Function(Uri redirectUri) authorizationUri,
  });
}
```

`authorize` は、ウィンドウが実際に使うリダイレクトアドレス (デスクトップのウィンドウは、ループバックアドレスの空いているポートを使うことがあります) に対して `authorizationUri` が作るアドレスを開き、戻ってきたリダイレクトで完了します。ユーザーが閉じたウィンドウは、`AuthorizationCancelledException` を投げます。プラットフォームのウィンドウは `spring_boot_starter_flutter_security` にあります。

## OAuth2Token

`OAuth2Token` は、Spring の同じ名前のインターフェースです。OAuth2 クライアントのアクセストークン、リフレッシュトークン、ID トークン (`AbstractOAuth2Token`) と、セキュリティスターターの `Jwt` がこれを実装します。そのため、コードはどれに対しても `tokenValue` と `expiresAt` を尋ねられます。サーバーのリクエストの Bearer トークンは、次のように見つけます。

```dart
final credentials = SecurityContextHolder.getContext().authentication?.credentials;
if (credentials is OAuth2Token) {
  forward(credentials.tokenValue);
}
```

## 以前の場所

`SecretStore`、`InMemorySecretStore`、`AuthorizationWindow`、`AuthorizationCancelledException` は、`spring_boot_starter_flutter_security` からここに移りました。そのパッケージは今もそれらをエクスポートしているので、そのパッケージをインポートするアプリケーションは何も変える必要がありません。

## Spring (Java) との対応

Spring には `LoginSession`、`SecretStore`、`AuthorizationWindow` がありません。Spring Security がログインさせるのはサーバーのユーザーで、リクエストごとに一人です。その OAuth 2.0 クライアントは、ユーザーと登録ごとにトークンを保持します (`OAuth2AuthorizedClientManager`)。`OAuth2Token` は `org.springframework.security.oauth2.core.OAuth2Token` です。

## 関連項目

- [セキュリティコンテキスト](security-context.md)
- [認証](authentication.md)
- [Supabase: クライアントアプリケーションでのサインイン](../spring-boot-starter-supabase/auth.md)
- [spring_boot_starter_flutter_security](../spring-boot-starter-flutter-security/index.md)
