spring_boot_starter_flutter_security 0.4.3

Security for Spring Boot Flutter apps: the OAuth2 / OpenID Connect app login, secrets in the Keychain / Keystore, widgets that follow the logged-in user.

0.4.3

• The Windows (DPAPI) and Linux (libsecret) secret stores are tested against the real systems (test/desktop_secret_store_test.dart, CI's "Secret stores on Windows and Linux" jobs): reading, writing, keys(), deleteAll(), apps kept apart, the DPoP key kept across restarts.
• The web login, spa mode (spring.flutter.security.web.mode=spa: the browser logs in by itself, for apps without a server of their own; server stays the default). SpaOAuth2LoginService: login builds the registration's authorization request (PKCE S256, state, nonce; dpop_jkt with DPoP), keeps it in sessionStorage for the round trip only and navigates the page to the provider; restore finishes the login when the page comes back with code and state (the state, RFC 9207 iss and error checks of the native login, the code exchanged as a public client, the ID token and nonce checked, the user loaded), removes the answer from the address bar (history.replaceState) and the request from sessionStorage; an answer the tab did not ask for, or older than 10 minutes, logs nobody in; after a reload or in a new tab a top-level prompt=none trip to the provider brings back a user who logged in in this browser (a hint in localStorage, the registration id only; spring.flutter.security.web.silent-restore, true by default), login_required meaning nobody; logout forgets the tokens, revokes them (best effort) and ends the provider's session at its end_session_endpoint. Tokens in the tab's memory only (TabOAuth2AuthorizedClientService, which warns when a refresh did not rotate the refresh token). WebCryptoDPoPKey, the app's DPoPKey in spa mode (webCryptoDPoPKey): an ECDSA P-256 WebCrypto key made with extractable: false, its CryptoKey handles kept in IndexedDB, made at the first proof (LoadableDPoPKey); BrowserKeyVault and BrowserKeyPair put WebCrypto behind interfaces. SpaBrowserPage (the base address, history.replaceState, sessionStorage and localStorage as BrowserStorage; InMemoryBrowserStorage), all through dart:js_interop, no package. A registration with a client secret is refused (a browser cannot keep it); an unreachable token endpoint names CORS. Beans: spaBrowserPage, tabAuthorizedClientService, webCryptoDPoPKey, spaOAuth2LoginService; the start fails in spa mode without a registration. browserPage is a server-mode bean now.
• DPoP keys that survive a restart (RFC 9449): PlatformDPoPKey, the app's DPoPKey bean (platformDPoPKey, wherever a registration is configured, not on the web), ordered before the OAuth2 client's key of one run, which backs off. An EC P-256 key in the Secure Enclave on iOS and macOS (a Keychain key where there is no usable Secure Enclave), in the Android Keystore (StrongBox when there is one), signing in the platform (DER turned into R || S); on Windows and Linux SecretStoreDPoPKey, a key made in Dart and kept as a private JWK in the SecretStore (oauth2.dpop-key). Made at the first proof; a key gone (PlatformDPoPKeyException, no_key) is replaced at the next. DPoPKeyStorage says where the key is. The channel spring_boot_starter_flutter_security/dpop_key (dpopPublicJwk, dpopSign, dpopDelete).
• SecretStoreOAuth2AuthorizedClientService keeps DPoP tokens (it read Bearer only): the token type, and with its new dPoPKey the thumbprint of the key a DPoP token is bound to; tokens bound to another key (lost, deleted, replaced) are dropped when loaded, so the user logs in again at once. Records without a type read as Bearer.
• NativeOAuth2LoginService.logout() deletes the PlatformDPoPKey (new dPoPKey), so the next login gets a new key; restore() treats invalid_dpop_proof at the refresh as a refused login.
• The web login, server mode (backend-for-frontend, spring.flutter.security.web.mode=server, the default): OAuth2LoginService keeps its calls in a browser, where the app's server logs the user in with oauth2Login() and the page holds only an HttpOnly session cookie. ServerOAuth2LoginService: login navigates the page to the server's /oauth2/authorization/{registrationId} (and returns null), restore asks the server's user endpoint ({"name", "authorities", "registrationId", "attributes"}) and puts an OAuth2AuthenticationToken or a PreAuthenticatedAuthenticationToken into the context, logout posts the server's logout with the CSRF token and follows a {"logoutUrl"} answer or a Location on a 2xx (http(s) only). CsrfCookieHttpTransport copies the XSRF-TOKEN cookie into X-XSRF-TOKEN on unsafe requests to the server only; in a browser the package declares it as the httpTransport bean around fetch (with FetchCredentials.include for a server on another origin), before Feign's, and backs off for an application's own HttpTransport. BrowserPage (address, cookies, navigation; a bean, faked in tests), FlutterWebSecurityProperties (spring.flutter.security.web.mode, server-url, user-endpoint, logout-url, authorization-base-uri). Outside a browser nothing changes.
• Breaking: OAuth2LoginService is an interface (login returns Future<Authentication?>, restore Future<Authentication?>, authentication an Authentication?); the login of phones and desktops is NativeOAuth2LoginService (its constructor, user, sessionKey and the narrower OAuth2AuthenticationToken types are those of the former class). The module now comes before Feign's too.
• First version: the login of an app with OAuth 2.0 / OpenID Connect and the platform code of logins and secrets (a Flutter plugin with its own platform code, no community plugins), on the registrations, token endpoint clients and authorized clients of spring_boot_starter_oauth2_client:
  • OAuth2LoginService, the app login: login (authorization code with PKCE in the AuthorizationWindow, the state, iss, ID token and user info checks), restore at startup from the stored tokens, logout with token revocation (OAuth2TokenRevocationClient, RFC 7009) and RP-initiated logout. In a web page the server logs in (see above).
  • AuthorizationWindow and AuthorizationCancelledException. PlatformAuthorizationWindow, the window of Android, iOS and macOS: ASWebAuthenticationSession (custom schemes; https redirects on iOS 17.4 / macOS 14.4; preferEphemeralSession) and Custom Tabs with the redirect caught by the package's RedirectReceiverActivity, which an app that logs in declares with its scheme in its AndroidManifest.xml; one login at a time; other failures are AuthorizationWindowExceptions. LoopbackAuthorizationWindow, the window of Windows and Linux: the default browser and a one-shot server on 127.0.0.1 (RFC 8252 §7.3).
  • SecretStore and InMemorySecretStore. PlatformSecretStore, the app's SecretStore bean: the Keychain on iOS and macOS (generic passwords, this device only, not synced; the login keychain for macOS builds without a team), an AES-256-GCM key of the Android Keystore with the values in a private preferences file, DPAPI files on Windows and the Secret Service through libsecret on Linux (both through dart:ffi, nothing native to build). None on the web (an InMemorySecretStore that the login and the template never fill). Errors are PlatformSecretStoreExceptions.
  • SecretStoreOAuth2AuthorizedClientService, the app's OAuth2AuthorizedClientService: the tokens as JSON in the SecretStore, so the login survives a restart.
  • SecretTemplate, the app's own secrets as JSON objects under a namespace; it throws on the web.
  • The beans are registered unless the application declares its own, before the OAuth2 client's auto-configuration, so the authorized client service replaces the client's in-memory one.
• Depends on and re-exports spring_boot_starter_flutter, spring_boot_starter_oauth2_client and spring_security_core (the Windows and Linux stores use dart:ffi alone, no package:ffi).