
# 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's `SecretStore` bean: `read`, `write`, `delete`, `keys` and `deleteAll` of strings by key, in the platform's secure storage. On the web the bean is an `InMemorySecretStore`, which the login and the template never fill.
- **`PlatformAuthorizationWindow`**, the app's `AuthorizationWindow` on 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`**, the `AuthorizationWindow` on Windows and Linux: opens the page in the default browser and answers the redirect on a one-shot server on `127.0.0.1` (five minutes without a redirect cancel the login). Only the request that carries the login's `state` ends 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](secrets.md).

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

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

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

```yaml
# 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.

```yaml
# 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](../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 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

- [The app login](app-login.md)
- [SecretTemplate](secrets.md)
- [DPoP](dpop.md)
