
# DPoP-bound tokens

A bearer token works for whoever holds it, until it expires. A DPoP-bound token (RFC 9449) is bound to a key that only the client has: with each request the client sends a short JWT signed with that key, the proof, so a stolen token alone is useless. A resource server chain accepts both kinds of tokens with nothing to configure.

## Why

Tokens leak: in logs, in a compromised proxy, from a device. A token bound to a key the client keeps (a Flutter app's key in the device's secure storage) cannot be replayed by whoever copied it. Keycloak, Okta, Auth0 and Spring Authorization Server issue such tokens; their `cnf.jkt` claim is the thumbprint (RFC 7638) of the client's key.

## Example

Nothing to configure: `oauth2ResourceServer((s) => s.jwt())`, or the `issuer-uri` / `jwk-set-uri` properties, accept DPoP-bound tokens, as in Spring Security 6.5.

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

On success the request has the same `JwtAuthenticationToken` as with a `Bearer` token: rules, scopes, `@AuthenticationPrincipal() Jwt` and `@PreAuthorize` work unchanged, and `jwt.jwkThumbprint` gives the `cnf.jkt`.

## What is checked

Any failure is a `401` with `WWW-Authenticate: DPoP error="...", algs="RS256 ... ES512"`:

1. **One proof:** exactly one `DPoP` header, at most 8 KiB (`invalid_request` otherwise).
2. **The access token,** as a `Bearer` token is (`invalid_token`); it must have a `cnf.jkt` claim (`invalid_dpop_proof` otherwise, before the proof is read).
3. **The proof** (`invalid_dpop_proof`):
   - `typ` is `dpop+jwt`;
   - `alg` is RS*, PS* or ES*, never `none` or HS*;
   - the signature verifies with the public key of its own `jwk` header: an EC key on its curve, or an RSA key of 2 048 to 8 192 bits, without private members;
   - `htm` is the request's method (case-sensitive);
   - `htu` is the request's URL;
   - `iat` is within 30 seconds of the server's clock;
   - `ath` is the hash of the access token;
   - the thumbprint of its key equals the token's `cnf.jkt`.
4. **No replay:** its `jti` was not used before. It is recorded only now, for a proof that passed everything else.

Other rules:

- A token with `cnf.jkt` sent as `Bearer` is refused (`invalid_token`), with or without a `DPoP` header.
- A token also bound to a client certificate (`cnf.x5t#S256`) is refused, even with a valid proof.
- A `DPoP` header next to an unbound `Bearer` token is ignored, as in Spring.
- Requests with `Authorization: DPoP` and a proof need no CSRF token.

## The URL in htu

`htu` is compared with the URL the request reached the server with: scheme, host (the `Host` header) and port as the server sees them, and the path, after RFC 3986 normalization (case of scheme and host, default port, percent-encoding), query and fragment ignored.

Behind a proxy that terminates TLS, the server sees `http`, and proofs for `https://...` are refused until the web starter reads forwarded headers: pass the scheme through (see [Behind a reverse proxy](../spring-boot-starter-web/server/reverse-proxy.md)), or terminate TLS in the application (`server.ssl.*`).

## Replay protection

The ids of used proofs are kept in memory until 5 seconds after their window (`iat` + 30 s + 5 s), at most 100 000 in all and 1 000 per client key, as in Spring.

- A recorded id is refused until a purge drops it; when the store is full, new proofs are refused until old ids expire (never forgotten early).
- Only proofs signed with the key their token is bound to are recorded, so a client with one valid token cannot fill the store with proofs of keys it makes up.
- A client that gets many tokens, each bound to another key, could still fill it; the identity provider's limits on token requests, or a shared store with quotas, are the defence there.

### Several instances

With several instances behind a load balancer, a proof could be replayed on another one. Give them a shared store, which keeps each id until the `expiresAt` it is given and refuses it until then, through a `DPoPProofJwtDecoderFactory` bean:

```dart
@Bean()
DPoPProofJwtDecoderFactory dPoPProofs(RedisJtiCache cache) =>
    DPoPProofJwtDecoderFactory(
      jtiCache: cache,                     // a DPoPProofJtiCache shared by the instances
      clockSkew: const Duration(seconds: 30),
    );
```

## In Spring (Java)

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

Compared with Spring Security 7.1 by a differential test (32 requests, the attacks included), the answers are Spring's. Differences: DPoP is on by default (Spring 7.1 needs `dPoP(...)`); `htu` is compared after normalization and without its query (Spring compares the text); `htm` is case-sensitive (Spring ignores case); DPoP requests need no CSRF token (Spring exempts `Bearer` only); the key is compared with `cnf.jkt` before the `jti` is recorded, and the `jti` is kept 5 seconds longer. No `DPoP-Nonce` challenges, as in Spring's resource server.

## See also

- [JWT resource servers](jwt.md)
- [CSRF](csrf.md)
