
# DPoP

`Bearer` トークンは、それを持つ誰にでも使えます。DPoP (RFC 9449) では、プロバイダーがトークンをアプリの鍵ペアに結び付けます。すべてのトークンリクエストとすべての API の呼び出しが、鍵で署名された短いプルーフを持つので、アプリからコピーされたトークン (ログ、バックアップ、プロキシ) はデバイスなしでは役に立ちません。登録の `dpop` がそう指定すると、OAuth2 クライアントがそれを行います。このパッケージは、各プラットフォームが持つ最も安全な場所にある鍵をそれに与えます。

## 使う理由

鍵はトークンと同じだけ生きなければならず (そうでなければ再起動のたびに新しいログインが必要になります)、アプリ自身のコードから決して読めてはなりません。スマートフォンでは、それはハードウェアを意味します。Secure Enclave や Android Keystore は、鍵を見せることなく署名します。

## 例

```yaml
spring:
  security:
    oauth2:
      client:
        registration:
          keycloak:
            client-id: neon-app
            redirect-uri: dev.neon.books:/oauth2/callback
            dpop: auto      # auto (デフォルト): プロバイダーが告知している場合。true: 常に。false: 決して
```

他には何も要りません。トークンのクライアント、ユーザーサービス、Feign のインターセプターは、自分で `DPoPKey` Bean を使います。

## 鍵の置き場所

パッケージは、アプリの `DPoPKey` Bean (`platformDPoPKey`、`PlatformDPoPKey`) を宣言します。それは起動時ではなく、最初のプルーフのときに作られます。

| プラットフォーム | 鍵の置き場所 | 署名するもの |
|---|---|---|
| iOS、macOS | Secure Enclave (EC P-256、永続、`<bundle id>.spring_dpop_key` のタグ付き、最初のロック解除の後、このデバイスのみ) | Secure Enclave |
| 使える Secure Enclave のない iOS、macOS | 同じタグと保護を持つ、キーチェーンのソフトウェアの鍵 | システムの Security フレームワーク |
| Android | Android Keystore (EC P-256)。スマートフォンにあれば StrongBox、なければ Trusted Execution Environment | Keystore |
| Windows、Linux | Dart で作られ、`SecretStore` に private JWK として保持される鍵 (`oauth2.dpop-key`) | アプリ (`SecretStoreDPoPKey`) |
| Web、spa モード | IndexedDB の取り出せない WebCrypto の鍵 ([spa モード](web-spa-mode.md) を参照) | ブラウザー |
| Web、サーバーモード | なし: ページはトークンを保持しない | |

`PlatformDPoPKey.storage` は、鍵がどこに置かれたかを示します (`secureEnclave`、`keychain`、`strongBox`、`trustedEnvironment`、`software`、`secretStore`)。鍵の素材、プルーフ、トークンがログに出ることはありません。

## 鍵を失ったとき

鍵がデバイスを離れることはありません。別のスマートフォンで復元されたアプリ、再インストールされた Android アプリ、消去された Keystore には鍵がありません。保存されたトークンはその鍵のサムプリントを持つので、読み込み時に捨てられ、`restore()` はログインを見つけず、ユーザーは再びログインします。キーチェーンの項目がアプリより長く生きる iOS では、インストールごとに ID が付きます。再インストール後の最初の起動で保存された値と鍵が取り除かれるので、再インストールされたアプリが前回のユーザーを再びログインさせることはありません。アップデートでそれらが失われることはありません。

## ログアウト

`logout()` は、トークンを取り消して忘れた後に鍵を削除します。次のログインは新しい鍵を作るので、デバイス上の二つのログインを鍵で結び付けることはできません。`SecretStore.deleteAll()` はデスクトップの鍵 (ストアの値) を取り除きますが、Secure Enclave や Keystore のものは取り除きません。それらには `PlatformDPoPKey.delete()` を呼んでください。

## 独自の呼び出しと WebSocket のハンドシェイク

Feign のインターセプターは、`Authorization: DPoP <token>` とプルーフを自分で送ります。フレームワークが行わないリクエストでは、OAuth2 クライアントの `OAuth2AccessTokenHeaders` が、トークンの種類に応じてヘッダーを書きます。WebSocket のハンドシェイクでは、プルーフの `htu` は `ws(s)` の URL の `http(s)` の形です。

```dart
// アプリのハンドシェイクのインターセプター (spring_boot_starter_websocket)。
@Component()
class ChatHandshake implements WebSocketHandshakeInterceptor {
  ChatHandshake(this._tokens, this._dPoPKey);

  final OAuth2AuthorizedClientManager _tokens;
  final DPoPKey? _dPoPKey;

  @override
  Future<void> apply(WebSocketHandshake handshake) async {
    final user = SecurityContextHolder.getContext().authentication;
    if (user == null) return;
    final client = await _tokens.authorize(
      OAuth2AuthorizeRequest.withClientRegistrationId('keycloak')
          .principal(user)
          .build(),
    );
    final headers = await OAuth2AccessTokenHeaders(dPoPKey: _dPoPKey).of(
      client!.accessToken,
      method: 'GET',
      url: handshake.url,
    );
    headers.forEach(handshake.headers.set);
  }
}
```

ブラウザーは WebSocket のハンドシェイクにヘッダーを設定できません。サーバーモードのページは、それとともにセッション Cookie を送ります。

アプリは、鍵を別の場所に保持するために独自の `DPoPKey` Bean を宣言できます。その場合パッケージのものは身を引きます (そして `logout()` はアプリの鍵に触れません)。

## プロパティ

| キー | 型 | デフォルト | 意味 |
|---|---|---|---|
| `spring.security.oauth2.client.registration.<id>.dpop` | `auto`、`true`、`false` | `auto` | `auto` は、プロバイダーのメタデータが DPoP を告知している場合 (Keycloak、Okta、Auth0 など) にトークンを結び付ける。`true` は常に、`false` は決して |

## Spring (Java) との対応

Spring Security 7 は、リソースサーバーでだけ DPoP のトークンを受け付けます。クライアント側の DPoP はなく、Java にはアプリもありません。

## 関連項目

- [アプリのログイン](app-login.md)
- [spa モード](web-spa-mode.md)
- [トークンとログインウィンドウ](tokens-and-login-window.md)
