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:
login('keycloak')builds the authorization request (PKCES256, astate, anonce; with DPoP the key's thumbprint asdpop_jkt, which binds the code to the key), keeps it in the tab'ssessionStorageand navigates the page to the provider. The result isnull: the app stops there.- The provider sends the browser back with
codeandstate; the app starts again, andrestore()finishes the login with the checks of the native login (thestate, theissof RFC 9207, the provider'serror; the code exchanged with the PKCE verifier; the ID token's issuer, audience, times andnonce; the user info's subject). The user goes into theSecurityContextHolder. Thecodeandstateleave 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 anOAuth2AuthenticationExceptionfromrestore(). logout()forgets the tokens, clears the context, publishes aLogoutSuccessEvent, revokes the tokens when the provider has arevocation_endpoint(best effort), and ends the provider's session: every tab shares it, so it ends whateverendSessionsays.
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.