Tokens and the login window

The app login needs two things from the platform: a safe place for its tokens, so the user stays logged in after a restart, and the system's login window for the provider's page, so the app never sees the password and the user's existing login there is reused (single sign-on). The package brings both, as its own platform code (no other plugin), and makes them beans.

Why

Each platform has its own secure storage and its own login window, with their own rules: a Keychain item's accessibility, an Android Keystore key that never leaves the hardware, DPAPI's per-user encryption, a locked GNOME keyring. The beans hide the differences behind two small interfaces; the few setup steps each platform needs are listed here.

The beans

OAuth2LoginService uses them by itself. Declare your own SecretStore or AuthorizationWindow bean only to replace them. The app's own secrets go to the same store through SecretTemplate.

Platform Secrets Login window
iOS Keychain: generic passwords, this device only, after the first unlock, not synced ASWebAuthenticationSession
macOS Keychain (the data protection keychain when the build is signed with a team, else the login keychain) ASWebAuthenticationSession
Android AES-256-GCM key in the Android Keystore (never leaves it), the encrypted values in a private preferences file Custom Tab (the default browser without Custom Tabs)
Windows DPAPI (current user), one file per key in %LOCALAPPDATA%\spring_secret_store\<app id> the default browser, the redirect on a loopback server
Linux the Secret Service (GNOME Keyring, KWallet) through libsecret, items of the app id the default browser, the redirect on a loopback server
Web none none: the server logs in

Android: declare the redirect

The provider sends the browser to the app's redirect URI (neonbooks:/oauth2/callback). An activity of the package catches it; declare it with your scheme in android/app/src/main/AndroidManifest.xml, inside <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 and macOS

Nothing to set up for a custom-scheme redirect. The login reuses Safari's session, and iOS asks "... wants to use ... to sign in". With ephemeral-session, the window keeps no cookies and asks nothing: no prompt, but no single sign-on (every login asks for the password).

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

On macOS, sign release builds with your team: a build signed only to run locally (the default of flutter run) cannot use the data protection keychain and falls back to the login keychain, whose items belong to the build that wrote them.

Linux: libsecret

The store loads libsecret-1.so.0 (libsecret-1-0 on Debian and Ubuntu, libsecret on Fedora and Arch) and needs a running Secret Service (GNOME Keyring, KWallet, KeePassXC). Without them every call throws a PlatformSecretStoreException; the tokens are never written to a plain file. While the keyring is locked, a call that needs a value fails with libsecret_locked rather than reading as missing, so the app never replaces a value it cannot see.

Windows and Linux: the app id

DPAPI and the Secret Service encrypt for the user, not the app: any program running as the same user can read the values. Between apps of this package, the values are kept apart by an app id: spring.flutter.security.application-id when set, else the app's own (on Windows <CompanyName>\<ProductName> of the runner's Runner.rc; on Linux the APPLICATION_ID of linux/CMakeLists.txt), else the executable's name. Set it when two of your apps could have the same.

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

Values of 0.4.x (kept under the executable's name) are moved to the app id once, at the first call after an update, so an update keeps the user logged in.

https redirects

A custom scheme can be claimed by any app; an https redirect on your own domain cannot.

Android (App Links, Android 6+): declare the package's activity with an intent filter for exactly the redirect's host and path, with android:autoVerify="true", and serve https://<domain>/.well-known/assetlinks.json with the app's package and the SHA-256 fingerprints of its signing keys (with Play App Signing, Google's key too). The login checks on Android 12+ that the host is verified, else it fails with redirect_not_verified. Give the login a path of its own. The navigation starter can write assetlinks.json for you (see The web and deep links).

<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 and macOS 14.4: ASWebAuthenticationSession catches an https callback for its own host and path. The app needs the associated domain with the webcredentials service (Xcode, Signing & Capabilities, Associated Domains: webcredentials:books.neon.example), and the domain serves apple-app-site-association with the app id. Older systems keep a custom scheme.

Errors

Error When
PlatformSecretStoreException The store failed; the message names the failure, never a value
AuthorizationCancelledException The user closed the login window
StateError A login is already running (one at a time)
AuthorizationWindowException Anything else of the window (redirect_not_configured, redirect_not_verified, ...)

The properties

Key Type Default Meaning
spring.flutter.security.ephemeral-session bool false iOS and macOS: the login window keeps no cookies of Safari; no prompt, no single sign-on. Android ignores it (a Custom Tab always shares the browser's cookies)
spring.flutter.security.application-id text the app's own id Windows and Linux: the name the app's secrets are kept under (Windows: the folder under %LOCALAPPDATA%\spring_secret_store, \ separates folders; Linux: the items' application attribute). A blank value is the default; other platforms ignore it

See also