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

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

使う理由

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

Bean

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

プラットフォーム 秘密情報 ログインウィンドウ
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> の中で、自分のスキームとともにそれを宣言してください。

<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>

iOS と macOS

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

# 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)、なければ実行ファイルの名前です。自分の二つのアプリが同じものになりうる場合は設定してください。

# 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 とディープリンク を参照)。

<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 属性)。空の値はデフォルト。他のプラットフォームは無視する

関連項目