DPoP

OAuth 2.0 Demonstrating Proof-of-Possession

Demonstrating Proof-of-Possession (DPoP) is a protocol-level security mechanism defined in RFC 9449.

It ensures that an access token alone is no longer sufficient to access a resource server. Instead, each request must also include a cryptographic proof showing possession of a private key held by the client.

As a result, access tokens become much less sensitive: if a token leaks, it cannot be replayed from another device or context without the corresponding private key.

The protocol also provide replay attack protection.

DPoP is supported by Keycloak and an increasing number of other identity providers and resource server stacks.

---

Enabling DPoP

oidc-spa exposes a single configuration option to control DPoP behavior:

• "auto": enable DPoP only if supported by the authorization server, otherwise fall back to classic Bearer tokens (Recommended)

• "enforced": require DPoP support; oidc-spa will refuse to start if the authorization server does not support it. See support history in Keycloak.

DPoP isn't enabled by default like PKCE is because many resource servers still can’t validate DPoP-bound tokens. We keep things working out of the box with older backends, until DPoP support becomes a baseline expectation for resource servers.

Vite Plugin

If you're in a Vite project, the recomended approach is to use oidc-spa's Vite plugin.

vite.config.ts

import { defineConfig } from "vite";
import { oidcSpa } from "oidc-spa/vite-plugin";

export default defineConfig({
    plugins: [
        // ...
        oidcSpa({
            browserRuntimeFreeze: { enabled: true, /*exclude: [...]*/ }, //Recommended
            DPoP: { enabled: true, mode: "auto" }
        })
    ]
});

Manual

NOTE: If your app talks to different resource servers and one resource server does not suppor DPoP yet, you can opt out from DPoP on a client by client basis by using createOidc({ disableDPoP: true }).

---

What does enabling DPoP require?

Enabling DPoP in oidc-spa does not require changes elsewhere in your stack:

• Identity Provider (Keycloak or other) No configuration change is required. With mode: "auto", If the authorization server supports DPoP, oidc-spa will detect and use it. Note that Microsoft EntraID does not support DPoP yet.

• Frontend codebase No changes are required. Authenticated requests continue to use Authorization: Bearer <access_token> and are automatically upgraded at runtime.

• Backend API / resource server No code changes are required. Just make sure your backend stack can validate and decode DPoP-bound access tokens. This is supported by Spring Security, and of course by oidc-spa/server. There is nothing to “enable” on the resource server side. If your RS supports DPoP, correct OAuth 2.0 token validation will reject DPoP-bound tokens when the DPoP proof is missing or invalid. If your RS does not support DPoP, calls will simply fail, so there is no false sense of security.

In other words, this configuration option is the only change required to securely enable DPoP support across your stack.

How it works

When DPoP is enabled, oidc-spa automatically upgrades authenticated HTTP requests sent by your application.

You continue sending requests as usual:

Request headers (written by your code)

Authorization: Bearer <access_token>

At runtime, oidc-spa transparently transforms the request into:

Request headers (sent over the wire)

Authorization: DPoP <access_token>
DPoP:          <DPoP proof JWT>

In addition, oidc-spa automatically:

• tracks and reuses DPoP nonces issued by resource servers

• retries requests when a nonce is required

To achieve this transparently, oidc-spa installs fetch() and XMLHttpRequest interceptors:

• via the Vite plugin, or

• during the execution of oidcEarlyInit()

From your application’s point of view, nothing changes: you keep using Authorization: Bearer <access_token>, and oidc-spa handles DPoP internally.