
# サーバーなしの Web: spa モード

独自のサーバーを持たない Web アプリもあります。他者の API や、プロバイダーのトークンを受け付ける API を、ブラウザーから直接呼びます。そのようなアプリは、PKCE を使うパブリッククライアントとしてブラウザー自身からログインし、トークンをページに保持します: `spring.flutter.security.web.mode=spa`。アプリにサーバーがある場合は常に `server` を選んでください。そこではトークンがページに届くことは決してなく、このモードはそれを約束できません。

## 使う理由

サーバーがなければ、ページがトークンを保持しなければなりません。spa モードは、その露出をブラウザーが許す限り小さく保ちます。トークンはタブのメモリーだけに (ストレージには決して置かない)、それらを DPoP で結び付けるためのページが取り出せない鍵、どのブラウザーでも動くリロード後のサイレントログイン、開発用の既製の Content Security Policy です。アプリのコードは引き続き同じです。`login`、`restore`、`logout` です。

## 例

```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}/'     # アプリ自身のページ: そのオリジンとベース href
            dpop: auto
        provider:
          keycloak:
            issuer-uri: https://id.neon.books/realms/neon
```

## プロパティ

| キー | 型 | デフォルト | 意味 |
|---|---|---|---|
| `spring.flutter.security.web.mode` | `server`、`spa` | `server` | `spa`: ブラウザーがログインする。登録がなければアプリは起動時に止まる |
| `spring.flutter.security.web.silent-restore` | bool | `true` | リロードの後や新しいタブで、以前このブラウザーで誰かがログインしていれば、`restore()` は `prompt=none` でページをプロバイダーに送り、ログインした状態で (または `login_required`: 誰もいない、で) 戻ってくる |

## 仕組み

`SpaOAuth2LoginService` は、spa モードでの `OAuth2LoginService` Bean です。

1. `login('keycloak')` は認可リクエストを組み立て (PKCE の `S256`、`state`、`nonce`。DPoP があれば鍵のサムプリントを `dpop_jkt` として。これがコードを鍵に結び付けます)、それをタブの `sessionStorage` に保持し、ページをプロバイダーに遷移させます。結果は `null` で、アプリはそこで止まります。
2. プロバイダーは `code` と `state` とともにブラウザーを送り返し、アプリは再び起動し、`restore()` がネイティブのログインのチェック (`state`、RFC 9207 の `iss`、プロバイダーの `error`、PKCE のベリファイアで交換されるコード、ID トークンの issuer、audience、時刻、`nonce`、ユーザー情報の subject) でログインを完了させます。ユーザーは `SecurityContextHolder` に入ります。`code` と `state` はアドレスバーから消え、アプリ独自のパラメーターとルートは残ります。このタブが求めなかった応答、または 10 分より古い応答は、誰もログインさせません。拒否されたログインは、`restore()` から `OAuth2AuthenticationException` を投げます。
3. `logout()` はトークンを忘れ、コンテキストをクリアし、`LogoutSuccessEvent` を発行し、プロバイダーが `revocation_endpoint` を持っていればトークンを取り消し (ベストエフォート)、プロバイダーのセッションを終わらせます。すべてのタブがそれを共有しているので、`endSession` が何を言っても終わらせます。

## リロードの後: サイレントログイン

トークンはリロードで失われます。戻る方法は三つ検討されました。メモリーのリフレッシュトークン (これも失われる)、`prompt=none` の隠れた iframe (サードパーティーのコンテキストでプロバイダーの Cookie が必要で、Safari、Firefox、プライベートモードはそれをブロックする)、`prompt=none` のトップレベルのリダイレクトです。パッケージは三つ目を採用しています。どのブラウザーでも動くからです。

ページが応答なしで起動し、以前このブラウザーで誰かがログインしていた場合、`restore()` は `prompt=none` でそれをプロバイダーに送り、`null` を返します。次の起動で、他のログインと同じようにそのログインを完了させます。`login_required` (または `interaction_required`、`consent_required`、`account_selection_required`) は、誰もログインしていないことを意味します。エラーもなく、二度目の試行もありません。以前に誰かがログインしていたかどうかは `localStorage` のヒント (登録 ID だけで、トークンは決して含まない) なので、一度もログインしたことのない訪問者がこの往復をすることはありません。`silent-restore: false` でこれを無効にします。

## 何がどこに保持されるか

| 何を | どこに | 理由 |
|---|---|---|
| アクセストークン、リフレッシュトークン、ID トークン | タブのメモリー | オリジンのどのスクリプトでも後から見つけられる `localStorage`、`sessionStorage`、IndexedDB には決して置かない |
| 認可リクエスト (`state`、`nonce`、PKCE のベリファイア) | `sessionStorage`。`login()` からページが戻ってくるまで | ページはプロバイダーへ去って再び起動する。ベリファイアはコードなしでは役に立たない |
| ヒント「`keycloak` でログインした」 | `localStorage` | リロード後のサイレントログインのため。秘密ではない |
| DPoP の鍵 | IndexedDB。取り出せない `CryptoKey` として | 使えるが、決して読めない |

**リフレッシュトークン** もメモリーにとどまり、プロバイダーはそれをローテーションしなければなりません (Keycloak: 「Revoke Refresh Token」。Auth0 と Okta: 「Refresh Token Rotation」)。同じリフレッシュトークンで戻ってくる更新は、登録ごとに一度だけ警告をログに出します。

## ページが読めない鍵による DPoP

`dpop=auto` (プロバイダーが ES256 を提供していれば有効) または `dpop=true` では、トークンは `WebCryptoDPoPKey` に結び付けられます。ブラウザーの WebCrypto が `extractable: false` で作る ECDSA P-256 の鍵で、リロードでも同じ鍵を使うようにオリジンの IndexedDB に保持されます。サイレントのものも含むすべてのログインは、プロバイダーへ去る前に新しい鍵を作るので、ログインのトークンがスクリプトが仕込んだかもしれない鍵に結び付けられることはありません。どのスクリプトもその鍵を取り出せません。WebCrypto にはセキュアなコンテキストが必要です。`https`、または開発中は `http://localhost` です。

## プロバイダーが提供しなければならないもの

PKCE を使うパブリッククライアント (シークレットなし) で、そのリダイレクト URI がアプリのページであり、ログアウト後のリダイレクト URI がアプリであるもの。トークン、ユーザー情報、取り消しのエンドポイントで、ページのオリジンが許可されていること (CORS) (Keycloak: クライアントの「Web origins」。Auth0: 「Allowed Web Origins」。Okta: 「Trusted Origin」)。クライアントシークレットを持つ登録は `login()` で拒否されます。トークンエンドポイントがページを拒否した場合 (CORS)、ログインは `server` モードを示すメッセージで失敗します。

## Content Security Policy

spa モードでは、ジェネレーターは `flutter run` に、ログインが fetch するホストを `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'
```

アプリが呼ぶ API を `spring.flutter.web.dev-server.content-security-policy-connect-src` に列挙するか、`spring.flutter.web.dev-server.content-security-policy` でポリシー全体を設定してください。本番向けには `flutter build web --csp` でビルドし、Web サーバーから `index.html` の `Content-Security-Policy` ヘッダーとして同じポリシーを送ってください。デバッグ実行ではホットリロードがコードを評価しますが、ポリシーはそれを禁じます。開発用のプロファイルで `content-security-policy-report-only: true` を設定してください。[Web 開発サーバー](../spring-core-dart-generator/flutter/web-dev-server.md) を参照してください。

## 保護するものとしないもの

DPoP は、盗まれたトークンを他の場所で役に立たなくします。すべてのリクエストに、ページの鍵だけが署名するプルーフが必要だからです。PKCE と `state` は、偽造された応答や盗まれた応答を止めます。トークンがストレージに触れることはありません。止められないもの: ページの中で動くスクリプトは、動いている間はユーザーとして振る舞えます (API を呼び、ブラウザーに署名を求めることはできますが、鍵を持ち去ることはできません)。`index.html` に外部のスクリプトを入れないようにし、Content Security Policy を送ってください。

## Spring (Java) との対応

Spring にはログインのブラウザー側がありません。ブラウザーに対する Spring Security の答えはサーバー上の `oauth2Login()` で、ここではそれが `server` モードです。

## 関連項目

- [Web: サーバーがログインする](web-server-mode.md)
- [DPoP](dpop.md)
- [Web](../spring-boot-starter-flutter/web.md)
