The web without a server: spa mode

Some web apps have no server of their own: they call the APIs of others, or an API that accepts the provider's tokens, straight from the browser. Such an app logs in from the browser itself, as a public client with PKCE, and holds the tokens in the page: spring.flutter.security.web.mode=spa. Choose server whenever the app has a server: there no token ever reaches the page, which this mode cannot promise.

Why

Without a server, the page must hold tokens. Spa mode keeps that exposure as small as a browser allows: tokens in the tab's memory only (never storage), a key the page cannot export to bind them with DPoP, a silent login after a reload that works in every browser, and a Content Security Policy ready for development. The app's code is still the same: login, restore, logout.

Example

# lib/resources/application-web.yml
spring:
  flutter:
    security:
      web:
        mode: spa
        silent-restore: true
  security:
    oauth2:
      client:
        registration:
          keycloak:
            client-id: neon-web
            scope: openid,profile,email
            redirect-uri: '{baseUrl}/'     # the app's own page: its origin and base href
            dpop: auto
        provider:
          keycloak:
            issuer-uri: https://id.neon.books/realms/neon

The properties

Key Type Default Meaning
spring.flutter.security.web.mode server, spa server spa: the browser logs in. Without a registration the app stops at startup
spring.flutter.security.web.silent-restore bool true After a reload or in a new tab, restore() sends the page to the provider with prompt=none when someone logged in in this browser before, and comes back logged in (or with login_required: nobody)

How it works

SpaOAuth2LoginService is the OAuth2LoginService bean in spa mode:

  1. login('keycloak') builds the authorization request (PKCE S256, a state, a nonce; with DPoP the key's thumbprint as dpop_jkt, which binds the code to the key), keeps it in the tab's sessionStorage and navigates the page to the provider. The result is null: the app stops there.
  2. The provider sends the browser back with code and state; the app starts again, and restore() finishes the login with the checks of the native login (the state, the iss of RFC 9207, the provider's error; the code exchanged with the PKCE verifier; the ID token's issuer, audience, times and nonce; the user info's subject). The user goes into the SecurityContextHolder. The code and state leave the address bar; the app's own parameters and route stay. An answer this tab did not ask for, or older than 10 minutes, logs nobody in. A refused login throws an OAuth2AuthenticationException from restore().
  3. logout() forgets the tokens, clears the context, publishes a LogoutSuccessEvent, revokes the tokens when the provider has a revocation_endpoint (best effort), and ends the provider's session: every tab shares it, so it ends whatever endSession says.

After a reload: the silent login

The tokens are gone with a reload. Three ways back were weighed: a refresh token in memory (lost too); a hidden iframe with prompt=none (needs the provider's cookie in a third-party context, which Safari, Firefox and private modes block); a top-level redirect with prompt=none. The package takes the third: it works in every browser.

When the page starts without an answer and someone logged in in this browser before, restore() sends it to the provider with prompt=none and returns null; at the next start it finishes that login like any other. login_required (or interaction_required, consent_required, account_selection_required) means nobody is logged in: no error, no second try. Whether someone logged in before is a hint in localStorage (only the registration id, never a token), so a visitor who never logged in never makes the trip. silent-restore: false turns it off.

What is kept where

What Where Why
access, refresh and ID tokens the tab's memory never localStorage, sessionStorage or IndexedDB, where any script of the origin, later, would find them
the authorization request (state, nonce, PKCE verifier) sessionStorage, from login() until the page is back the page leaves for the provider and starts again; the verifier is useless without the code
the hint "logged in with keycloak" localStorage the silent login after a reload; no secret
the DPoP key IndexedDB, as a non-extractable CryptoKey usable, never readable

Refresh tokens stay in memory too, and the provider must rotate them (Keycloak: "Revoke Refresh Token"; Auth0 and Okta: "Refresh Token Rotation"). A refresh that comes back with the same refresh token logs a warning, once per registration.

DPoP with a key the page cannot read

With dpop=auto (on when the provider offers ES256) or dpop=true, the tokens are bound to WebCryptoDPoPKey: an ECDSA P-256 key made by the browser's WebCrypto with extractable: false, kept in the origin's IndexedDB so a reload uses the same key. Every login, the silent one too, makes a new key before it leaves for the provider, so a login's tokens are never bound to a key a script could have planted. No script can export the key. WebCrypto needs a secure context: https, or http://localhost in development.

What the provider must offer

A public client (no secret) with PKCE, whose redirect URI is the app's page and whose post-logout redirect URI is the app; the page's origin allowed (CORS) on the token, user info and revocation endpoints (Keycloak: the client's "Web origins"; Auth0: "Allowed Web Origins"; Okta: a "Trusted Origin"). A registration with a client secret is refused at login(). When the token endpoint refuses the page (CORS), the login fails with a message that points to server mode.

The Content Security Policy

In spa mode the generator gives flutter run a ready policy, with the hosts the login fetches from in connect-src:

default-src 'self'; script-src 'self' 'wasm-unsafe-eval' https://www.gstatic.com;
style-src 'self' 'unsafe-inline'; img-src 'self' data: blob:;
font-src 'self' https://fonts.gstatic.com;
connect-src 'self' https://www.gstatic.com https://fonts.gstatic.com <the providers>;
worker-src 'self' blob:; object-src 'none'; base-uri 'self'; form-action 'self';
frame-ancestors 'none'

List the APIs the app calls in spring.flutter.web.dev-server.content-security-policy-connect-src, or set the whole policy with spring.flutter.web.dev-server.content-security-policy. Build for production with flutter build web --csp, and send the same policy from the web server as the Content-Security-Policy header of index.html. In debug runs hot reload evaluates code, which the policy forbids: set content-security-policy-report-only: true in a development profile. See The web dev server.

What it protects, and what not

DPoP makes a stolen token useless elsewhere: every request needs a proof only the page's key signs. PKCE and state stop forged and stolen answers; the tokens never touch storage. What it cannot stop: a script running in the page acts as the user while it runs (it can call the APIs and ask the browser to sign; it cannot carry the key away). Keep foreign scripts out of index.html, and send a Content Security Policy.

In Spring (Java)

Spring has no browser side of a login: Spring Security's answer for browsers is oauth2Login() on a server, which is the server mode here.

See also