DPoP (v6.7)

DPoP (RFC 9449, OAuth 2.0 Demonstrating Proof of Possession) binds the tokens to a key pair held by the client, so that a stolen token cannot be replayed by someone who does not hold the private key.

1) Dependency

You need to use the following module: pac4j-dpop.

Example (Maven dependency):

<dependency>
    <groupId>org.pac4j</groupId>
    <artifactId>pac4j-dpop</artifactId>
    <version>${pac4j.version}</version>
</dependency>

The DPoP support relies on the Nimbus JOSE + JWT and OAuth 2.0 SDK with OpenID Connect extensions libraries, which this module brings, even for the OAuth clients.

2) Client support

To enable DPoP, add the DPoPHttpInterceptor to the OAuth or OIDC configuration.

Example (OpenID Connect):

OidcConfiguration config = new OidcConfiguration();
config.setHttpInterceptor(new DPoPHttpInterceptor());

Example (OAuth):

OAuth20Configuration config = new OAuth20Configuration();
config.setHttpInterceptor(new DPoPHttpInterceptor());

The same interceptor handles both protocols: it adds a DPoP proof to every request sent to the OAuth server or to the OpenID provider (pushed authorization, token and UserInfo requests).

The authorization scheme follows the token type returned by the server: DPoP for a DPoP-bound access token, or Bearer if the server issues an unbound access token. Adding a proof does not turn a Bearer token into a DPoP-bound token.

The proofs are signed by a key pair saved in the web session and generated on first use: the tokens are bound to it, and the following requests (UserInfo, refresh) prove its possession. A web session is thus required: without a web context or a session store, the interceptor fails. One key pair is kept per signature algorithm in the session, so clients using different algorithms do not overwrite each other’s keys.

The signature algorithm is ES256 by default and can be changed, for ES384, ES512, RS256, RS384, RS512, PS256, PS384 or PS512:

config.setHttpInterceptor(new DPoPHttpInterceptor().setJwsAlgorithm(JWSAlgorithm.PS256));

A server may require its own nonce in the proofs. In that case, it refuses the request with the use_dpop_nonce error and provides the nonce in the DPoP-Nonce header of its response: the interceptor saves this nonce in the web session and the request is sent again, once, with a new proof carrying it.

The nonce is then added to all the proofs sent to this server, and replaced whenever the server provides a new one, in any response. One nonce is kept per server, as the authorization server and the resource server (UserInfo or profile endpoint) each provide their own.

The proofs sent and the nonces received are logged raw on the PROTOCOL_MESSAGE.DPOP logger, at DEBUG level. The private key is never logged:

logging.level.PROTOCOL_MESSAGE.DPOP=DEBUG

A proof is logged as the JWT sent. To read its header and its claims, decoded, enable the TRACE level on the interceptor:

logging.level.org.pac4j.dpop.http.DPoPHttpInterceptor=TRACE

The requests and the responses carrying them are logged by the PROTOCOL_MESSAGE.OAUTH and PROTOCOL_MESSAGE.OIDC loggers (a request sent again is logged twice). The PROTOCOL_MESSAGE.DPOP logger is a child of PROTOCOL_MESSAGE, which enables the messages of all protocols at once. Messages are logged as they travel: enable these logs to diagnose, not permanently in production.

3) Server support

The server side of DPoP (validating the proof of an incoming request and checking that the access token is bound to its key) is not available yet.