Skip to main content

DPoP Enforcement Model

Summary​

The DPoP enforcement model binds access tokens to the cryptographic key of the requesting client, ensuring that stolen tokens cannot be used without the corresponding private key. Keymate validates DPoP proofs at the gateway layer per RFC 9449, checking proof structure, signature, claims, and token binding before forwarding requests to upstream services. This model provides defense-in-depth against token exfiltration, replay attacks, and downgrade attempts.

Why It Exists​

Bearer tokens are vulnerable to theft and replay. If an attacker intercepts a bearer token, they can use it from any device or network. DPoP (Demonstrating Proof-of-Possession, RFC 9449) mitigates this by requiring clients to prove possession of a private key that is cryptographically bound to the token at issuance time. Keymate adopts this standard to strengthen its zero-trust authorization posture.

Where It Fits in Keymate​

DPoP enforcement operates at the gateway layer, which is the first point of contact for incoming API requests. The gateway validates DPoP proofs before any authorization decision occurs. After successful validation, the gateway normalizes the request for downstream processing, ensuring that DPoP complexity is contained at the edge and does not propagate through the platform.

Boundaries​

This page covers the DPoP proof validation model and token binding mechanism at the gateway layer. It does not cover:

How It Works​

Proof Validation​

When a request arrives with a DPoP header and an Authorization: DPoP <token> scheme, the gateway validates the DPoP proof JWT against the following checks per RFC 9449 Section 4.3:

CheckDescription
JWT structureThe proof must be a valid signed JWT
typ headerMust be dpop+jwt
alg headerMust use an allowed asymmetric algorithm (RS256, RS384, RS512, ES256, ES384, ES512, PS256, PS384, PS512)
jwk headerMust contain a public JWK with no private key material
SignatureMust be valid against the embedded public key
jti claimMust be present and unique (used for replay protection)
htm claimMust match the HTTP method of the request
htu claimMust match the HTTP URI of the request (scheme-independent comparison)
iat claimMust be within an acceptable time window (default: not older than 120 seconds, not more than 5 seconds in the future)
ath claimMust match the base64url-encoded SHA-256 hash of the access token

If any check fails, the gateway rejects the request with an appropriate error response.

Token Binding​

After successful proof validation, the gateway verifies that the DPoP proof was created by the same key that the token was bound to at issuance time. This binding is established through the cnf (confirmation) claim in the access token:

  1. The identity provider issues the access token with a cnf.jkt claim containing the SHA-256 JWK thumbprint (RFC 7638) of the client's public key
  2. The gateway computes the JWK thumbprint from the proof's embedded public key
  3. The gateway compares the computed thumbprint with the cnf.jkt claim from the access token
  4. If the thumbprints do not match, the request is rejected with a binding mismatch error

This two-layer check ensures that only the holder of the original private key can use the token, even if the token is intercepted in transit.

Scheme Normalization​

After successful DPoP validation, the gateway normalizes the authorization scheme from DPoP to Bearer for downstream processing. This means:

  • DPoP proof validation is contained at the gateway edge
  • Downstream services receive standard Bearer tokens
  • Authorization decisions proceed without DPoP-specific logic

Fail-Closed Behavior​

Keymate's DPoP enforcement follows a fail-closed design. If the replay protection cache is unavailable, requests are rejected rather than allowed through without replay checking. This prevents attackers from exploiting infrastructure failures to bypass token binding.

Diagram​

Example Scenario​

Scenario​

A client application authenticates with Keycloak and receives a DPoP-bound access token. It then makes an API request through the Keymate gateway.

Input​

  • Actor: Client application (acme-portal)
  • Resource: /api/v1/users
  • Action: GET request with DPoP proof
  • Context: Access token contains cnf.jkt matching the client's key pair

Expected Outcome​

  • Granted
  • Why: The DPoP proof is structurally valid, the signature verifies against the embedded public key, the JTI is unique, the method and URI match, the timestamp is within the acceptable window, and the JWK thumbprint matches the cnf.jkt claim in the access token.

Common Misunderstandings​

  • DPoP replaces mTLS — DPoP and mTLS address different layers. DPoP binds tokens to application-level keys; mTLS authenticates the transport-level identity. Keymate can use both together for defense-in-depth.
  • DPoP proofs are reusable — Each DPoP proof is a single-use JWT. Replaying a proof triggers rejection via JTI uniqueness checking.
  • DPoP requires client-side changes only — DPoP requires coordinated support: the identity provider must issue tokens with cnf.jkt claims, the gateway must validate proofs, and the client must generate and attach proofs to every request.
warning

DPoP does not protect against key compromise. If an attacker obtains the client's private key, they can generate valid proofs. Protect private keys with appropriate storage mechanisms (for example, server-side session storage rather than browser-accessible storage).

Design Notes / Best Practices​

  • Configure the iat maximum age to balance security and clock skew tolerance. The default of 120 seconds accommodates typical clock drift without allowing stale proofs.
  • Use ES256 (ECDSA with P-256) for DPoP key pairs when possible. It offers strong security with compact proof sizes.
  • Monitor DPoP validation metrics (proof invalid, binding mismatch, replay detected, downgrade detected) to detect attack patterns.
tip

Keymate provides OpenTelemetry metrics and structured audit logs for all DPoP validation outcomes, enabling real-time monitoring and incident investigation.

  • Protecting administrative API sessions from token theft
  • Securing machine-to-machine communication with sender-constrained tokens
  • Meeting compliance requirements for token binding in regulated environments

Replay, Downgrade & Abuse Protection

How Keymate prevents proof replay and scheme downgrade attacks.

Admin Console DPoP Sessions

DPoP-bound session management in the Admin Console.

OAuth Client Security

Client lifecycle and scope governance.

Security Overview

Central entry point for Keymate security capabilities.