
# Web: サーバーがログインする

ブラウザーにはトークンのための安全な場所がありません。メモリー、`localStorage`、IndexedDB は、ページに入り込んだどのスクリプトからも読めます。そのため、ブラウザーでは、Spring Security が任意の Web ページに対して行うのと同じく、アプリ自身のサーバーがユーザーをログインさせます。`spring_boot_starter_security` の `oauth2Login()` は、コンフィデンシャルクライアントとして認可コードフローを実行し、トークンをセッションに保持し、ブラウザーには `HttpOnly` のセッション Cookie だけを与えます。これは Backend for Frontend のパターンで、Web アプリにとって最も強い選択であり、デフォルト (`spring.flutter.security.web.mode=server`) です。

## 使う理由

アプリのコードはスマートフォンと同じままです。`login('keycloak')`、`restore()`、`logout()`、`PrincipalBuilder`、Feign クライアントです。`kIsWeb` も、コードの中のプロバイダーもありません。登録 ID はサーバーのもので、Web ではアプリは独自の登録を持ちません。

## 例

```yaml
# lib/resources/application-web.yml
spring:
  flutter:
    security:
      web:
        mode: server                       # デフォルト
        server-url: https://api.neon.books # ページと API がオリジンを共有するなら省略する
        user-endpoint: /api/me
        logout-url: /api/logout
```

サーバーの「誰がログインしているか」のエンドポイント (`spring_boot_starter_security`):

```dart
// サーバー上の GET /user。セッション Cookie 付き。
@RestController()
class UserController {
  @GetMapping('/user')
  Map<String, Object?> user(Authentication authentication) => {
    'name': authentication.name,
    'authorities': [
      for (final authority in authentication.authorities) authority.authority,
    ],
    if (authentication is OAuth2AuthenticationToken) ...{
      'registrationId': authentication.authorizedClientRegistrationId,
      'attributes': authentication.principal.attributes,
    },
  };
}
```

## プロパティ

| キー | 型 | デフォルト | 意味 |
|---|---|---|---|
| `spring.flutter.security.web.mode` | `server`、`spa` | `server` | `server`: アプリのサーバーがログインする。`spa`: ブラウザーが自分でログインする ([spa モード](web-spa-mode.md) を参照) |
| `spring.flutter.security.web.server-url` | 絶対 `http(s)` URL、クエリなし | ページのオリジン | アプリのサーバー。あればそのコンテキストパスも含む。別のオリジンにある場合、それへのリクエストは Cookie を持ち、サーバーはそれを許可しなければならない (クレデンシャル付きの CORS) |
| `spring.flutter.security.web.user-endpoint` | パスまたは絶対 URL | `/user` | セッション Cookie 付きの `GET`: 誰がログインしているか |
| `spring.flutter.security.web.logout-url` | パスまたは絶対 URL | `/logout` | CSRF トークン付きの `POST` |
| `spring.flutter.security.web.authorization-base-uri` | パスまたは絶対 URL | `/oauth2/authorization` | サーバーがログインを始める場所。その後に `/{registrationId}` が続く (Spring の `authorizationEndpoint().baseUri()`) |

キーはブラウザーでだけ読まれます (`web` プラットフォームのプロファイル)。`application-web.yml` に置いてください。不正な値は、キーの名前とともに起動時にアプリを止めます。

## 仕組み

`ServerOAuth2LoginService` は、ブラウザーでの `OAuth2LoginService` Bean です。

1. `login('keycloak')` は、ページを `<server-url>/oauth2/authorization/keycloak` に遷移させ、`null` を返します。サーバーはブラウザーをプロバイダーへ送り、ログインの後にアプリへ送り返します (その `defaultSuccessUrl` へ。サーバーの設定からで、リクエストのパラメーターからでは決してありません)。アプリは再び起動します。
2. 起動時の `restore()` は、セッション Cookie とともにユーザーのエンドポイントに問い合わせ、ユーザーを `SecurityContextHolder` に置き (そのため `PrincipalNotifier`、`PrincipalBuilder`、`@PreAuthorize` がそれを見ます)、`AuthenticationSuccessEvent` を発行します。誰もログインしていない場合 (`401`、`403`、`204`、ログインページへのリダイレクト) は `null` です。サーバーに到達できない、または別の何かを応答した場合は、警告とともに `null` です。
3. `logout()` は、CSRF トークンとともにログアウトの URL に POST し、コンテキストをクリアし、`LogoutSuccessEvent` を発行します。サーバーがプロバイダーのログアウトページで応答した場合、ページはそこへ行き、プロバイダーはそのセッションを終わらせ、ブラウザーを送り返します。

## ユーザーのエンドポイント

Spring には標準の「私は誰か」のエンドポイントがないので、サーバーがそれを宣言します (上記)。その応答:

```json
{
  "name": "ada",
  "authorities": ["ROLE_USER", "OIDC_USER", "SCOPE_profile"],
  "registrationId": "keycloak",
  "attributes": {"email": "ada@neon.books"}
}
```

- `name` は必須です。`authorities` (文字列、または Jackson が Spring の `GrantedAuthority` を書くときの `{"authority": "..."}` オブジェクト)、`registrationId`、`attributes` は省略可能で、その他のメンバーは無視されます。
- `registrationId` があれば、ユーザーは `OAuth2AuthenticationToken` です。なければ (サーバーのフォームログイン) `PreAuthenticatedAuthenticationToken` です。どちらの場合も、プリンシパルは属性を持つ `OAuth2User` です。
- 権限はサーバーのもので、そのまま使われます (ブラウザーに `GrantedAuthoritiesMapper` はありません)。

パッケージはそのようなコントローラーを提供しません。サーバーがページにどのユーザーデータを見せるかは、サーバーが決めることです。

## ログアウトの応答

アプリはスクリプトのリクエスト (`fetch`) でログアウトし、それはプロバイダー (別のオリジン) へのリダイレクトをたどれません。そのため、サーバーのログアウトの成功ハンドラーは、二つの方法のいずれかでプロバイダーのログアウトの URL を応答し、ページはそこへ行きます。

- `{"logoutUrl": "https://id.neon.books/...logout?..."}` を持つ `200`。
- `202 Accepted` のような、`Location` ヘッダーを持つ `2xx` (別のオリジンのサーバーでは、CORS の設定で `Location` を公開してください)。

その他の成功 (`204`、リダイレクト) は、サーバーのセッションだけを終わらせます。たどられるのは `http` と `https` の URL だけです。`403` は CSRF トークンがなかったことを意味します。それでもアプリはローカルでログアウトします。

## Cookie と CSRF トークン

ブラウザーでは、パッケージは `httpTransport` Bean を宣言します。`CsrfCookieHttpTransport` で包まれたブラウザーの `fetch` で、サーバーの `XSRF-TOKEN` Cookie を、そのサーバーへの `POST`、`PUT`、`PATCH`、`DELETE` のリクエストの `X-XSRF-TOKEN` ヘッダーにコピーします。別のオリジンには決してコピーしません。サーバーが別のオリジンにある場合、`ServerCredentialsHttpTransport` は Cookie をサーバーのオリジンにだけ送るので、`Access-Control-Allow-Origin: *` で応答する公開 API は動き続け、ユーザーの Cookie を見ることはありません。独自の `HttpTransport` を宣言するアプリはそれを保ち、`CsrfCookieHttpTransport` で包んだ `ServerCredentialsHttpTransport.forPage(page: page, server: server)` で同じものを組み立てます。

## サーバー側

`spring_boot_starter_security` で:

- `defaultSuccessUrl('<the web app>', alwaysUse: true)` を持つ `oauth2Login()`。
- ページが読める Cookie の CSRF トークン: `CsrfTokenRequestAttributeHandler` を持つ `CookieCsrfTokenRepository.withHttpOnlyFalse()` と、すべての応答で Cookie を書くフィルター。
- 別のオリジンのサーバーでは: `allowCredentials: true` (決して `*` ではない) でページのオリジンに対する CORS と、許可されたヘッダーの中の `X-XSRF-TOKEN`。ページとサーバーは一つのサイトに置きます (`app.neon.books` と `api.neon.books`)。ブラウザーはサードパーティーの Cookie を捨てるからです。
- 上記のユーザーのエンドポイントとログアウトの応答。

開発中は、開発サーバーのプロキシがページと API を一つのオリジンに置きます。`spring.flutter.web.dev-server.proxy` で `/api/` を転送してください ([Web](../spring-boot-starter-flutter/web.md) を参照)。

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

トークンがブラウザーに届くことはありません。ページに注入されたスクリプトがそれを盗むことはできません。セッション Cookie は `HttpOnly` です。CSRF トークンは、他のサイトがブラウザーにそれ付きのリクエストを送らせるのを止めます。それでも、注入されたスクリプトは、ページが開いている間はユーザーとして振る舞えます。Flutter はキャンバスに描画し、データを HTML に変えることはないので、古典的な DOM のインジェクションはほぼなくなりますが、`index.html` の外部のスクリプト (アナリティクス、タグマネージャー)、サプライチェーン、ユーザーの HTML を使う `HtmlElementView`、同じオリジンの他のコンテンツは残ります。それらを入れないようにし、Content Security Policy を送ってください。

## Spring (Java) との対応

このモードは `oauth2Login()` そのものです。Spring にはそのクライアント側がありません。ページの側はページに任されています (Angular は `XSRF-TOKEN` Cookie を自分で読みます。「私は誰か」のエンドポイントはアプリケーションのものです)。

## 関連項目

- [spa モード](web-spa-mode.md)
- [spring_boot_starter_security](../spring-boot-starter-security/index.md)
- [アプリのログイン](app-login.md)
