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.
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":
- One proof: exactly one
DPoPheader, at most 8 KiB (invalid_requestotherwise). - The access token, as a
Bearertoken is (invalid_token); it must have acnf.jktclaim (invalid_dpop_proofotherwise, before the proof is read). - The proof (
invalid_dpop_proof):typisdpop+jwt;algis RS*, PS* or ES*, nevernoneor HS*;- the signature verifies with the public key of its own
jwkheader: an EC key on its curve, or an RSA key of 2 048 to 8 192 bits, without private members; htmis the request's method (case-sensitive);htuis the request's URL;iatis within 30 seconds of the server's clock;athis the hash of the access token;- the thumbprint of its key equals the token's
cnf.jkt.
- No replay: its
jtiwas not used before. It is recorded only now, for a proof that passed everything else.
Other rules:
- A token with
cnf.jktsent asBeareris refused (invalid_token), with or without aDPoPheader. - A token also bound to a client certificate (
cnf.x5t#S256) is refused, even with a valid proof. - A
DPoPheader next to an unboundBearertoken is ignored, as in Spring. - Requests with
Authorization: DPoPand 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), 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:
@Bean()
DPoPProofJwtDecoderFactory dPoPProofs(RedisJtiCache cache) =>
DPoPProofJwtDecoderFactory(
jtiCache: cache, // a DPoPProofJtiCache shared by the instances
clockSkew: const Duration(seconds: 30),
);
In Spring (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.