
# DPoP

`Bearer` トークンは、持っている人なら誰でも使えます。DPoP トークン (RFC 9449) はクライアントの鍵ペアにバインドされています。すべてのトークンリクエストとすべての API 呼び出しは、秘密鍵で署名した短い JWT、つまり証明を運び、トークンはそれなしでは役に立ちません。登録の `dpop` プロパティでこれが有効になります。セキュリティスターターのリソースサーバーは両方の種類を受け入れます。

## 使う理由

アプリのトークンは、紛失したり侵害されたりしうるデバイスの上にあり、ネットワークやプロキシを通過します。Secure Enclave や Android Keystore に保持された鍵にバインドされたトークンは、それをコピーした人がリプレイすることはできません。Spring Security 7 にはクライアント側の DPoP がありません。これは追加されたものです。

## 例

```properties
# auto (デフォルト): 鍵がプログラムより長く残り (アプリの鍵)、
# プロバイダーのメタデータが dpop_signing_alg_values_supported に ES256 を列挙していれば有効。
spring.security.oauth2.client.registration.my-provider.dpop=auto

# true: 常に (手で設定したプロバイダー、または独自の鍵を持つサーバー)。
# false: Bearer トークン。
```

DPoP を使いたいサーバーは、再起動後も残る鍵を宣言します。

```dart
@Bean()
DPoPKey dPoPKey(KeyStore store) => SoftwareDPoPKey.fromJwk(store.read('dpop'));
```

## dpop プロパティ

| 値 | 意味 |
|---|---|
| `auto` (デフォルト) | 鍵がプログラムより長く残り (`DPoPKey.persistent`: Flutter のセキュリティパッケージのアプリの鍵)、検出されたプロバイダーのメタデータが `dpop_signing_alg_values_supported` に `ES256` を列挙していれば有効。 |
| `true` | 常に有効。再起動後も残る (そして、セッションを共有する複数のインスタンスがある場合は共有される) `DPoPKey` Bean を宣言する。 |
| `false` | `Bearer` トークン。 |

サーバーのデフォルトの鍵は一回の実行のためにメモリ上で作られるため、サーバーでは `auto` は `Bearer` トークンのままです。登録が `dpop=true` を指定しない限り、`oauth2Login()` には何も変わりません。DPoP を告知しないプロバイダーでは、どこでも `Bearer` になります。

## DPoP の登録が行うこと

- **トークンリクエスト** (`authorization_code`、`refresh_token`、`client_credentials`) は、トークンエンドポイントへの `POST` のための `DPoP` の証明を送ります。プロバイダーが `DPoP-Nonce` ヘッダー付きで `use_dpop_nonce` と応答すると、リクエストはその nonce でもう一度送られ、プロバイダーの最後の nonce が次の証明に入ります。
- `DPoP` (大文字小文字を問わない) の `token_type` は `TokenType.dpop` になります。プロバイダーはそれでも `Bearer` を発行することがあり (RFC 9449 が許しています)、その場合トークンは `Bearer` のままです。
- DPoP トークンのリフレッシュは常に証明を運びます。そのリフレッシュトークンもバインドされているためです。
- **Feign の呼び出し**は、`Authorization: DPoP <token>` と新しい証明 (`htm` はメソッド、`htu` はクエリとフラグメントを除いた URL、`ath` はトークンのハッシュ) を送ります。エラーデコーダーはエラー応答の `DPoP-Nonce` をサーバーごとに次の証明のために覚えておきます。`use_dpop_nonce` を受け取った呼び出しは繰り返されず、成功した応答の nonce は見られません。
- **ユーザーサービス**は、同じ方法で DPoP トークンをユーザー情報エンドポイントに送ります。nonce には一度応答します。
- **その他のリクエスト:** `OAuth2AccessTokenHeaders` がトークンの種類に応じたヘッダーを書きます ([認可済みクライアント](authorized-clients.md) を参照)。

## 鍵

鍵は `DPoPKey` Bean です: `algorithm` (`ES256`)、`publicJwk`、そして JOSE が求める生の `R || S` を返す `sign` (`ECDSA.transcodeSignatureToConcat` はプラットフォームの鍵の DER を変換します)。

| 鍵 | 置き場所 |
|---|---|
| `SoftwareDPoPKey` (スターターのデフォルト) | Dart で作られる ES256 の鍵。実行ごとに生成され、メモリに保持される。それにバインドされたトークンはプロセスとともに失われ、リフレッシュトークンも同様。再起動後はリフレッシュが失敗し、ユーザーは再びログインする。 |
| `SoftwareDPoPKey.fromJwk(...)` | `toJwk()` が保存した場所から復元される。`toJwk` は秘密鍵を持つ。決してログに出してはいけない。 |
| Flutter のセキュリティパッケージの鍵 | iOS と macOS では Secure Enclave か Keychain、Android Keystore、Windows と Linux ではその `SecretStore` の中の鍵。そのモジュールが先に来るため、こちらは引き下がる。 |
| `LoadableDPoPKey` | プラットフォームが応答して初めて公開部分がわかる鍵。`DPoPProofBuilder` はまずその `load()` を待つ。 |

スターターの中の何物も、鍵、証明、トークンをログに出しません。Feign の `headers` のログは、`Authorization` と同じく `DPoP` ヘッダーをマスクします。

## Spring (Java) との対応

Spring Security 7 にはクライアント側の DPoP がありません (spring-security#18228 が `ClientSettings.requireDpop` を提案しています)。`dpop` プロパティ、`DPoPMode`、`DPoPKey`、`SoftwareDPoPKey`、`DPoPProofBuilder`、そしてトークンクライアント、ユーザーサービス、Feign のインターセプターの DPoP の部分は、この移植独自のものです。`OAuth2AccessTokenResponse` は Spring Security 6.5 と同じく `token_type: DPoP` を読みます。まだないもの: Web での WebCrypto の鍵、`use_dpop_nonce` で応答された Feign の呼び出しのリトライ。

## 関連項目

- [サーバーでの DPoP にバインドされたトークン](../spring-boot-starter-security/dpop.md)
- [Feign の呼び出しのトークン](feign.md)
- [登録](registrations.md)
