
# DPoP

A `Bearer` token works for whoever holds it. A DPoP token (RFC 9449) is bound to a key pair of the client: every token request and every API call carries a short JWT, the proof, signed with the private key, and the token is useless without it. The `dpop` property of a registration switches it on; the security starter's resource server accepts both kinds.

## Why

An app's tokens live on a device that may be lost or compromised, and pass through networks and proxies. A token bound to a key kept in the Secure Enclave or the Android Keystore cannot be replayed by whoever copied it. Spring Security 7 has no DPoP on the client side; this is an addition.

## Example

```properties
# auto (the default): on when the key outlives the program (an app's) and the
# provider's metadata lists ES256 in dpop_signing_alg_values_supported.
spring.security.oauth2.client.registration.my-provider.dpop=auto

# true: always (a provider configured by hand, or a server with a key of its own).
# false: Bearer tokens.
```

A server that wants DPoP declares a key that survives restarts:

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

## The dpop property

| Value | Meaning |
|---|---|
| `auto` (default) | On when the key outlives the program (`DPoPKey.persistent`: the app keys of the Flutter security package) and the provider's discovered metadata lists `ES256` in `dpop_signing_alg_values_supported`. |
| `true` | Always. Declare a `DPoPKey` bean that survives restarts (and, with several instances sharing sessions, is shared). |
| `false` | `Bearer` tokens. |

A server's default key is made in memory for one run, so on a server `auto` keeps `Bearer` tokens: nothing changes for `oauth2Login()` unless a registration says `dpop=true`. Providers that do not announce DPoP get `Bearer` everywhere.

## What a DPoP registration does

- **Token requests** (`authorization_code`, `refresh_token`, `client_credentials`) send a `DPoP` proof for the `POST` to the token endpoint. When the provider answers `use_dpop_nonce` with a `DPoP-Nonce` header, the request goes once more with that nonce, and the provider's last nonce goes into the next proofs.
- A `token_type` of `DPoP` (any case) becomes `TokenType.dpop`. A provider may still issue `Bearer` (RFC 9449 allows it), and the token stays `Bearer`.
- The refresh of a DPoP token always carries a proof: its refresh token is bound too.
- **Feign calls** send `Authorization: DPoP <token>` and a fresh proof (`htm` the method, `htu` the URL without query and fragment, `ath` the token's hash). The error decoder remembers the `DPoP-Nonce` of an error answer per server for the next proofs; the call that got `use_dpop_nonce` is not repeated, and a nonce in a successful answer is not seen.
- **The user services** send DPoP tokens to the user-info endpoint the same way, a nonce answered once.
- **Other requests:** `OAuth2AccessTokenHeaders` writes the headers by the token's type (see [Authorized clients](authorized-clients.md)).

## The key

The key is the `DPoPKey` bean: `algorithm` (`ES256`), `publicJwk` and `sign`, which returns the raw `R || S` that JOSE wants (`ECDSA.transcodeSignatureToConcat` converts the DER of platform keys).

| Key | Lives |
|---|---|
| `SoftwareDPoPKey` (the starter's default) | An ES256 key made in Dart, generated for each run and kept in memory. Tokens bound to it die with the process, the refresh token too: after a restart the refresh fails and the user logs in again. |
| `SoftwareDPoPKey.fromJwk(...)` | Restored from where `toJwk()` stored it. `toJwk` holds the private key: never log it. |
| The Flutter security package's keys | The Secure Enclave or the Keychain on iOS and macOS, the Android Keystore, a key in its `SecretStore` on Windows and Linux. Its module comes first, so this one backs off. |
| `LoadableDPoPKey` | A key whose public part is known only once the platform answered; `DPoPProofBuilder` awaits its `load()` first. |

Nothing in the starter logs a key, a proof or a token, and Feign's `headers` log masks the `DPoP` header like `Authorization`.

## In Spring (Java)

Spring Security 7 has no client-side DPoP (spring-security#18228 proposes `ClientSettings.requireDpop`). The `dpop` property, `DPoPMode`, `DPoPKey`, `SoftwareDPoPKey`, `DPoPProofBuilder` and the DPoP parts of the token clients, user services and Feign interceptor are this port's. `OAuth2AccessTokenResponse` reads `token_type: DPoP` as Spring Security 6.5 does. Not here yet: a WebCrypto key on the web, the retry of a Feign call answered `use_dpop_nonce`.

## See also

- [DPoP-bound tokens on the server](../spring-boot-starter-security/dpop.md)
- [Tokens on Feign calls](feign.md)
- [Registrations](registrations.md)
