Replay, Downgrade & Abuse Protection

Summary

Keymate protects DPoP-bound token flows against three classes of attack: proof replay (reusing a previously valid DPoP proof), scheme downgrade (presenting a DPoP-bound token with a Bearer authorization scheme), and abuse through stale or malformed proofs. These protections use distributed JTI tracking, timestamp validation, and fail-closed enforcement to ensure that token binding cannot be bypassed.

Why It Exists

DPoP proof validation alone does not prevent all token abuse scenarios. An attacker who captures a valid proof could replay it within its validity window. An attacker who obtains a DPoP-bound token could attempt to use it as a regular Bearer token, bypassing the proof requirement. Keymate addresses these gaps with dedicated detection and enforcement mechanisms.

Where It Fits in Keymate

These protections operate within the gateway's DPoP enforcement layer, complementing the core DPoP Enforcement Model. They execute as part of proof validation and token binding checks before any authorization decision.

Boundaries

This page covers replay protection, downgrade detection, and abuse prevention mechanisms. It does not cover:

• Core DPoP proof validation (see DPoP Enforcement Model)
• Admin Console session-level DPoP (see Admin Console DPoP Sessions)

How It Works

Replay Protection

Each DPoP proof contains a jti (JWT ID) claim that must be unique. Keymate tracks used JTI values in a distributed cache to detect and reject replayed proofs.

Mechanism:

1. After the gateway validates a DPoP proof's structure and signature, it checks the jti value against a distributed cache
2. The cache operation is atomic — it writes the JTI and checks for prior existence in a single operation, eliminating time-of-check-to-time-of-use (TOCTOU) race conditions
3. If the JTI already exists in the cache, the proof is a replay and the request is rejected
4. If the JTI is new, it is stored in the cache with a time-to-live (TTL) that exceeds the proof acceptance window

Cache TTL calculation:

The JTI cache TTL must be at least as long as the maximum proof acceptance window. With a default maximum proof age of 120 seconds and a future tolerance of 5 seconds, the minimum TTL is 125 seconds. Keymate uses a default TTL of 150 seconds to provide a safety margin.

Downgrade Detection

A downgrade attack occurs when an attacker obtains a DPoP-bound token (one that contains a cnf.jkt claim) and presents it using the standard Bearer authorization scheme, attempting to bypass DPoP proof validation.

Keymate detects downgrade attempts at two points:

1. At the gateway edge — When a request uses the Bearer scheme, the gateway inspects the access token for a cnf.jkt claim. If present, the token was issued as DPoP-bound and must be presented with a valid DPoP proof. The request is rejected as a downgrade attempt.

2. After token introspection — For opaque tokens that cannot be inspected locally, the gateway checks the introspection response for a cnf claim. If the introspected token has a cnf.jkt but the request used the Bearer scheme, a downgrade is detected and the request is rejected.

Timestamp Validation

DPoP proofs include an iat (issued at) claim that the gateway validates against configurable time boundaries:

Parameter	Default	Purpose
Maximum age	120 seconds	Rejects proofs that are too old
Future tolerance	5 seconds	Accommodates minor clock skew without accepting proofs from the future

Proofs outside this window are rejected regardless of signature validity.

Fail-Closed Enforcement

If the distributed JTI cache is unavailable, the gateway rejects all DPoP requests rather than allowing them through without replay protection. This fail-closed behavior prevents attackers from exploiting infrastructure failures to bypass replay detection.

The cache client uses a retry strategy with configurable backoff before declaring the cache unavailable:

Parameter	Default
Initial backoff	1000 ms
Maximum backoff	1000 ms
Maximum attempts	3

Error Responses

Error Code	Cause
DPOP_REPLAY_DETECTED	A proof with the same jti was already used
DPOP_DOWNGRADE_DETECTED	A DPoP-bound token was presented with the Bearer scheme
DPOP_PROOF_INVALID	Proof failed structural, signature, or timestamp validation

All error responses return HTTP 401 status.

Diagram

Example Scenario

Scenario

An attacker intercepts a valid DPoP proof and attempts to replay it against the same API endpoint.

Input

• Actor: Attacker replaying captured proof
• Resource: /api/v1/users
• Action: GET request with replayed DPoP proof (same jti as a previous request)
• Context: The original request was processed 30 seconds ago

Expected Outcome

• Denied
• Why: The jti from the replayed proof already exists in the distributed cache. The atomic cache check detects the duplicate and rejects the request with DPOP_REPLAY_DETECTED.

Common Misunderstandings

• Replay protection depends on proof expiration alone — Timestamp validation and JTI uniqueness are complementary controls. Timestamp validation limits the window; JTI uniqueness prevents reuse within that window.
• Downgrade detection only works with JWT tokens — Keymate detects downgrades for both JWT and opaque tokens. JWT tokens are checked at the gateway edge; opaque tokens are checked after introspection.
• Cache failures silently bypass replay protection — Keymate uses fail-closed behavior. Cache unavailability results in request rejection, not permissive bypass.

warning

If the distributed cache is persistently unavailable, all DPoP requests will be rejected. Ensure that the cache infrastructure has appropriate redundancy and monitoring.

Design Notes / Best Practices

• Set the JTI cache TTL to at least 25 seconds more than the maximum proof age plus future tolerance to account for network delays and processing time.
• Monitor dpop.validation.replay_detected and dpop.validation.downgrade_detected metrics to detect attack patterns.
• The atomic cache operation eliminates TOCTOU vulnerabilities that could allow replay in high-concurrency environments.

tip

Keymate records structured audit log events for every replay detection, downgrade detection, and proof validation failure, enabling forensic analysis and incident response.

Related Use Cases

• Detecting token theft attempts in production environments
• Meeting compliance requirements for proof-of-possession enforcement
• Auditing DPoP validation outcomes for security investigations

Related Docs

DPoP Enforcement Model

Core DPoP proof validation and token binding.

Admin Console DPoP Sessions

DPoP-bound session management in the Admin Console.

OAuth Client Security

Client lifecycle and credential governance.

Security Overview

Central entry point for Keymate security capabilities.