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
- Token requests (
authorization_code,refresh_token,client_credentials) send aDPoPproof for thePOSTto the token endpoint. When the provider answersuse_dpop_noncewith aDPoP-Nonceheader, the request goes once more with that nonce, and the provider's last nonce goes into the next proofs. - A
token_typeofDPoP(any case) becomesTokenType.dpop. A provider may still issueBearer(RFC 9449 allows it), and the token staysBearer. - 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 (htmthe method,htuthe URL without query and fragment,aththe token's hash). The error decoder remembers theDPoP-Nonceof an error answer per server for the next proofs; the call that gotuse_dpop_nonceis 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:
OAuth2AccessTokenHeaderswrites the headers by the token's type (see Authorized clients).
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.