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

# 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:

@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

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