
# 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

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

```text
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](../spring-core-dart-generator/flutter/web-dev-server.md).

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

- [The web: the server logs in](web-server-mode.md)
- [DPoP](dpop.md)
- [The web](../spring-boot-starter-flutter/web.md)
