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
PlatformSecretStore, the app'sSecretStorebean:read,write,delete,keysanddeleteAllof strings by key, in the platform's secure storage. On the web the bean is anInMemorySecretStore, which the login and the template never fill.PlatformAuthorizationWindow, the app'sAuthorizationWindowon Android, iOS and macOS: opens the provider's page in the system's login window and waits for the redirect back. The system shows the page; the app gets only the redirect.LoopbackAuthorizationWindow, theAuthorizationWindowon Windows and Linux: opens the page in the default browser and answers the redirect on a one-shot server on127.0.0.1(five minutes without a redirect cancel the login). Only the request that carries the login'sstateends the wait.
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>
- Without it a login fails at once with an
AuthorizationWindowException(redirect_not_configured) that shows this snippet. - Pick a scheme of your own (reverse domain,
dev.neon.books); PKCE makes a code caught by another app useless anyway. - A user who comes back without finishing (back button, closing the tab) cancels the login:
AuthorizationCancelledException. - A value that no longer decrypts (a backup restored on another phone) is deleted and read as missing: the user logs in again.
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 |