
# DPoP にバインドされたトークン

Bearer トークンは、期限が切れるまで、持っている人なら誰でも使えます。DPoP にバインドされたトークン (RFC 9449) は、クライアントだけが持つ鍵にバインドされています。クライアントはリクエストごとに、その鍵で署名した短い JWT、つまり証明を送ります。そのため盗まれたトークンだけでは役に立ちません。リソースサーバーのチェーンは、何も設定せずに両方の種類のトークンを受け入れます。

## 使う理由

トークンは漏れます。ログから、侵害されたプロキシから、デバイスから。クライアントが保持する鍵 (デバイスのセキュアストレージにある Flutter アプリの鍵) にバインドされたトークンは、それをコピーした人がリプレイすることはできません。Keycloak、Okta、Auth0、Spring Authorization Server はそうしたトークンを発行します。その `cnf.jkt` クレームは、クライアントの鍵のサムプリント (RFC 7638) です。

## 例

設定は不要です。`oauth2ResourceServer((s) => s.jwt())`、または `issuer-uri` / `jwk-set-uri` プロパティは、Spring Security 6.5 と同じく DPoP にバインドされたトークンを受け入れます。

```http
GET /api/orders HTTP/1.1
Authorization: DPoP eyJhbGciOiJSUzI1NiIs...
DPoP: eyJ0eXAiOiJkcG9wK2p3dCIsImFsZyI6IkVTMjU2IiwiandrIjp7...
```

成功すると、リクエストは `Bearer` トークンの場合と同じ `JwtAuthenticationToken` を持ちます。ルール、スコープ、`@AuthenticationPrincipal() Jwt`、`@PreAuthorize` はそのまま動き、`jwt.jwkThumbprint` が `cnf.jkt` を返します。

## チェックされること

どの失敗も `WWW-Authenticate: DPoP error="...", algs="RS256 ... ES512"` 付きの `401` になります。

1. **証明は一つ:** `DPoP` ヘッダーはちょうど一つで、最大 8 KiB です (そうでなければ `invalid_request`)。
2. **アクセストークン**は `Bearer` トークンと同じようにチェックされます (`invalid_token`)。`cnf.jkt` クレームを持たなければなりません (そうでなければ、証明を読む前に `invalid_dpop_proof`)。
3. **証明** (`invalid_dpop_proof`):
   - `typ` が `dpop+jwt` である。
   - `alg` が RS*、PS*、ES* のいずれかで、`none` や HS* ではない。
   - 署名が、自身の `jwk` ヘッダーの公開鍵で検証できる。その曲線上の EC 鍵、または 2 048 から 8 192 ビットの RSA 鍵で、秘密のメンバーを持たないもの。
   - `htm` がリクエストのメソッドである (大文字小文字を区別)。
   - `htu` がリクエストの URL である。
   - `iat` がサーバーの時計から 30 秒以内である。
   - `ath` がアクセストークンのハッシュである。
   - その鍵のサムプリントがトークンの `cnf.jkt` と等しい。
4. **リプレイなし:** その `jti` が以前に使われていない。他のすべてを通過した証明についてだけ、この時点で記録されます。

その他のルール:

- `cnf.jkt` を持つトークンを `Bearer` として送ると、`DPoP` ヘッダーの有無にかかわらず拒否されます (`invalid_token`)。
- クライアント証明書にもバインドされたトークン (`cnf.x5t#S256`) は、有効な証明があっても拒否されます。
- バインドされていない `Bearer` トークンの隣の `DPoP` ヘッダーは、Spring と同じく無視されます。
- `Authorization: DPoP` と証明を持つリクエストには、CSRF トークンが不要です。

## htu の URL

`htu` は、リクエストがサーバーに届いたときの URL と比較されます。スキーム、ホスト (`Host` ヘッダー)、ポートはサーバーから見えるもので、パスは RFC 3986 の正規化 (スキームとホストの大文字小文字、デフォルトポート、パーセントエンコーディング) の後のものです。クエリとフラグメントは無視されます。

TLS を終端するプロキシの背後では、サーバーには `http` に見え、Web スターターが転送ヘッダーを読むまで `https://...` 向けの証明は拒否されます。スキームを引き継ぐ ([リバースプロキシの背後で](../spring-boot-starter-web/server/reverse-proxy.md) を参照) か、アプリケーションで TLS を終端してください (`server.ssl.*`)。

## リプレイ対策

使われた証明の ID は、Spring と同じく、その期間の 5 秒後 (`iat` + 30 秒 + 5 秒) までメモリに保持されます。全体で最大 100 000 個、クライアントの鍵ごとに最大 1 000 個です。

- 記録された ID は、パージで取り除かれるまで拒否されます。ストアがいっぱいになると、古い ID が期限切れになるまで新しい証明が拒否されます (早く忘れられることはありません)。
- 記録されるのは、トークンがバインドされた鍵で署名された証明だけです。そのため、有効なトークンを一つ持つクライアントが、でっち上げた鍵の証明でストアを埋めることはできません。
- それぞれ別の鍵にバインドされた多くのトークンを得るクライアントは、それでもストアを埋められます。そこでの防御は、アイデンティティプロバイダーのトークンリクエストの制限、またはクォータ付きの共有ストアです。

### 複数のインスタンス

ロードバランサーの背後に複数のインスタンスがある場合、証明が別のインスタンスでリプレイされる可能性があります。`DPoPProofJwtDecoderFactory` Bean を通じて、共有ストアを与えてください。共有ストアは各 ID を与えられた `expiresAt` まで保持し、それまで拒否します。

```dart
@Bean()
DPoPProofJwtDecoderFactory dPoPProofs(RedisJtiCache cache) =>
    DPoPProofJwtDecoderFactory(
      jtiCache: cache,                     // インスタンス間で共有される DPoPProofJtiCache
      clockSkew: const Duration(seconds: 30),
    );
```

## Spring (Java) との対応

```java
http.oauth2ResourceServer(o -> o.jwt(Customizer.withDefaults()).dPoP(Customizer.withDefaults()));
```

差分テスト (攻撃を含む 32 のリクエスト) で Spring Security 7.1 と比較すると、応答は Spring のものと同じです。違い: DPoP はデフォルトで有効です (Spring 7.1 では `dPoP(...)` が必要)。`htu` は正規化の後、クエリを除いて比較されます (Spring はテキストを比較します)。`htm` は大文字小文字を区別します (Spring は区別しません)。DPoP のリクエストには CSRF トークンが不要です (Spring が除外するのは `Bearer` だけです)。鍵は `jti` を記録する前に `cnf.jkt` と比較され、`jti` は 5 秒長く保持されます。Spring のリソースサーバーと同じく、`DPoP-Nonce` のチャレンジはありません。

## 関連項目

- [JWT リソースサーバー](jwt.md)
- [CSRF](csrf.md)
