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

  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:

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.

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.

See also