
# トークンとログインウィンドウ

アプリのログインは、プラットフォームに二つのものを求めます。再起動後もユーザーがログインしたままでいられるようにトークンのための安全な場所と、アプリがパスワードを見ることなく、そこでのユーザーの既存のログインが再利用される (シングルサインオン) ように、プロバイダーのページのためのシステムのログインウィンドウです。パッケージは、独自のプラットフォームのコードとして (他のプラグインなしで) 両方を持ち込み、それらを Bean にします。

## 使う理由

各プラットフォームには独自の安全なストレージと独自のログインウィンドウがあり、それぞれ独自のルールがあります。キーチェーンの項目のアクセス性、ハードウェアから決して出ない Android Keystore の鍵、DPAPI のユーザーごとの暗号化、ロックされた GNOME のキーリングです。Bean は、その違いを二つの小さなインターフェースの背後に隠します。各プラットフォームが必要とするわずかなセットアップの手順を、ここに列挙します。

## Bean

- **`PlatformSecretStore`**、アプリの `SecretStore` Bean: プラットフォームの安全なストレージで、キーによる文字列の `read`、`write`、`delete`、`keys`、`deleteAll`。Web では、この Bean は `InMemorySecretStore` で、ログインもテンプレートもそれを埋めることはありません。
- **`PlatformAuthorizationWindow`**、Android、iOS、macOS でのアプリの `AuthorizationWindow`: システムのログインウィンドウでプロバイダーのページを開き、戻ってくるリダイレクトを待ちます。ページを表示するのはシステムで、アプリが受け取るのはリダイレクトだけです。
- **`LoopbackAuthorizationWindow`**、Windows と Linux での `AuthorizationWindow`: デフォルトのブラウザーでページを開き、`127.0.0.1` 上の一回限りのサーバーでリダイレクトに応答します (リダイレクトのない五分間でログインはキャンセルされます)。待機を終わらせるのは、ログインの `state` を持つリクエストだけです。

`OAuth2LoginService` はそれらを自分で使います。独自の `SecretStore` や `AuthorizationWindow` の Bean を宣言するのは、それらを置き換える場合だけです。アプリ独自の秘密情報は、[SecretTemplate](secrets.md) を通して同じストアに入ります。

| プラットフォーム | 秘密情報 | ログインウィンドウ |
|---|---|---|
| iOS | キーチェーン: 汎用パスワード、このデバイスのみ、最初のロック解除の後、同期されない | `ASWebAuthenticationSession` |
| macOS | キーチェーン (ビルドがチームで署名されていればデータ保護キーチェーン、そうでなければログインキーチェーン) | `ASWebAuthenticationSession` |
| Android | Android Keystore の AES-256-GCM の鍵 (そこから決して出ない)。暗号化された値は private な設定ファイルに | Custom Tab (Custom Tabs がなければデフォルトのブラウザー) |
| Windows | DPAPI (現在のユーザー)。`%LOCALAPPDATA%\spring_secret_store\<app id>` にキーごとに一つのファイル | デフォルトのブラウザー。リダイレクトはループバックのサーバーで |
| Linux | `libsecret` を通した Secret Service (GNOME Keyring、KWallet)。アプリ ID の項目 | デフォルトのブラウザー。リダイレクトはループバックのサーバーで |
| Web | なし | なし: サーバーがログインする |

## Android: リダイレクトを宣言する

プロバイダーは、ブラウザーをアプリのリダイレクト URI (`neonbooks:/oauth2/callback`) に送ります。パッケージのアクティビティがそれを受け取ります。`android/app/src/main/AndroidManifest.xml` の `<application>` の中で、自分のスキームとともにそれを宣言してください。

```xml
<activity
    android:name="dev.farumazula.spring_boot_starter_flutter_security.RedirectReceiverActivity"
    android:exported="true">
    <intent-filter>
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <data android:scheme="neonbooks" />
    </intent-filter>
</activity>
```

- それがなければ、ログインはこのスニペットを示す `AuthorizationWindowException` (`redirect_not_configured`) ですぐに失敗します。
- 独自のスキームを選んでください (逆順のドメイン、`dev.neon.books`)。いずれにせよ、PKCE が別のアプリに受け取られたコードを役に立たなくします。
- 完了せずに戻ってきたユーザー (戻るボタン、タブを閉じる) はログインをキャンセルします: `AuthorizationCancelledException`。
- もう復号できない値 (別のスマートフォンで復元されたバックアップ) は削除され、ないものとして読まれます。ユーザーは再びログインします。

## iOS と macOS

独自スキームのリダイレクトにはセットアップは不要です。ログインは Safari のセッションを再利用し、iOS は「... wants to use ... to sign in」と尋ねます。`ephemeral-session` では、ウィンドウは Cookie を保持せず、何も尋ねません。プロンプトはなくなりますが、シングルサインオンもなくなります (ログインのたびにパスワードを求めます)。

```yaml
# lib/resources/application-ios.yml
spring:
  flutter:
    security:
      ephemeral-session: true
```

macOS では、リリースビルドを自分のチームで署名してください。ローカルで実行するためだけに署名されたビルド (`flutter run` のデフォルト) はデータ保護キーチェーンを使えず、ログインキーチェーンにフォールバックします。その項目はそれを書いたビルドのものです。

## Linux: libsecret

ストアは `libsecret-1.so.0` (Debian と Ubuntu では `libsecret-1-0`、Fedora と Arch では `libsecret`) を読み込み、動いている Secret Service (GNOME Keyring、KWallet、KeePassXC) を必要とします。それらがなければ、すべての呼び出しが `PlatformSecretStoreException` を投げます。トークンが素のファイルに書かれることは決してありません。キーリングがロックされている間、値を必要とする呼び出しは、ないものとして読む代わりに `libsecret_locked` で失敗するので、アプリが見えない値を置き換えることはありません。

## Windows と Linux: アプリ ID

DPAPI と Secret Service は、アプリではなくユーザーのために暗号化します。同じユーザーとして動くどのプログラムも値を読めます。このパッケージのアプリの間では、値はアプリ ID で分けられます。設定されていれば `spring.flutter.security.application-id`、なければアプリ自身のもの (Windows ではランナーの `Runner.rc` の `<CompanyName>\<ProductName>`、Linux では `linux/CMakeLists.txt` の `APPLICATION_ID`)、なければ実行ファイルの名前です。自分の二つのアプリが同じものになりうる場合は設定してください。

```yaml
# lib/resources/application-desktop.yml
spring:
  flutter:
    security:
      application-id: NEON\Books
```

0.4.x の値 (実行ファイルの名前の下に保持されていたもの) は、アップデート後の最初の呼び出しで一度だけアプリ ID に移されるので、アップデートしてもユーザーはログインしたままです。

## https のリダイレクト

独自スキームはどのアプリも主張できますが、自分のドメインの `https` のリダイレクトはそうできません。

**Android (App Links、Android 6+):** リダイレクトのホストとパスにちょうど一致するインテントフィルターを、`android:autoVerify="true"` とともに持つパッケージのアクティビティを宣言し、アプリのパッケージとその署名鍵の SHA-256 フィンガープリント (Play App Signing では Google の鍵も) を持つ `https://<domain>/.well-known/assetlinks.json` を配信してください。ログインは Android 12+ でホストが検証されていることをチェックし、そうでなければ `redirect_not_verified` で失敗します。ログインには独自のパスを与えてください。ナビゲーションのスターターは `assetlinks.json` を代わりに書けます ([Web とディープリンク](../spring-boot-starter-flutter-navigation/web-and-deep-links.md) を参照)。

```xml
<activity
    android:name="dev.farumazula.spring_boot_starter_flutter_security.RedirectReceiverActivity"
    android:exported="true">
    <intent-filter android:autoVerify="true">
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <data android:scheme="https" />
        <data android:host="books.neon.example" />
        <data android:path="/oauth2/callback" />
    </intent-filter>
</activity>
```

**iOS 17.4 と macOS 14.4:** `ASWebAuthenticationSession` は、自身のホストとパスへの `https` のコールバックを受け取ります。アプリには `webcredentials` サービスの関連付けられたドメイン (Xcode の Signing & Capabilities の Associated Domains: `webcredentials:books.neon.example`) が必要で、ドメインはアプリ ID を持つ `apple-app-site-association` を配信します。古いシステムは独自スキームのままです。

## エラー

| エラー | 発生するとき |
|---|---|
| `PlatformSecretStoreException` | ストアが失敗した。メッセージは失敗を示し、値は決して示さない |
| `AuthorizationCancelledException` | ユーザーがログインウィンドウを閉じた |
| `StateError` | ログインがすでに実行中 (一度に一つ) |
| `AuthorizationWindowException` | ウィンドウのその他すべて (`redirect_not_configured`、`redirect_not_verified` など) |

## プロパティ

| キー | 型 | デフォルト | 意味 |
|---|---|---|---|
| `spring.flutter.security.ephemeral-session` | bool | `false` | iOS と macOS: ログインウィンドウは Safari の Cookie を保持しない。プロンプトなし、シングルサインオンなし。Android は無視する (Custom Tab は常にブラウザーの Cookie を共有する) |
| `spring.flutter.security.application-id` | テキスト | アプリ自身の ID | Windows と Linux: アプリの秘密情報が保持される名前 (Windows: `%LOCALAPPDATA%\spring_secret_store` の下のフォルダー。`\` はフォルダーを区切る。Linux: 項目の `application` 属性)。空の値はデフォルト。他のプラットフォームは無視する |

## 関連項目

- [アプリのログイン](app-login.md)
- [SecretTemplate](secrets.md)
- [DPoP](dpop.md)
