Admin Console DPoP Sessions

Summary

The Keymate Admin Console uses a Backend-for-Frontend (BFF) architecture that binds administrative sessions to cryptographic keys using DPoP (RFC 9449). Key pairs are generated server-side, stored in encrypted session storage, and used to create DPoP proofs for every API request. The browser never handles tokens or keys directly, providing strong protection against session hijacking and token theft.

Why It Exists

Administrative sessions carry elevated privileges. If an attacker steals an admin session token, they can perform privileged operations across the platform. DPoP-bound sessions ensure that even if a token is intercepted, it cannot be used without the corresponding private key, which remains server-side and never leaves the backend.

Where It Fits in Keymate

The Admin Console sits between the administrator's browser and the Keymate platform APIs. Its BFF layer handles all authentication and authorization flows, including DPoP key management, proof generation, and token binding. The gateway validates these proofs using the DPoP Enforcement Model.

Boundaries

This page covers how the Admin Console manages DPoP-bound sessions in the BFF layer. It does not cover:

• Gateway-level DPoP proof validation (see DPoP Enforcement Model)
• DPoP integration for custom client applications
• Identity provider DPoP configuration

How It Works

Key Generation at Login

When an administrator initiates a login flow, the BFF generates an ECDSA P-256 key pair and exports both keys in JWK format for session persistence. The BFF then calculates the JWK thumbprint (dpop_jkt) and includes it in the authorization URL sent to the identity provider. This binds the authorization code to the specific key pair, preventing code interception attacks.

Token Exchange with DPoP Proof

When the identity provider redirects back with an authorization code, the BFF creates a DPoP proof for the token endpoint request. The identity provider validates the proof and issues an access token with a cnf.jkt claim matching the client's public key thumbprint. The BFF stores the token and keys in server-side session storage.

Per-Request Proof Generation

For every subsequent API request, the BFF:

1. Reads the access token and key pair from session storage
2. Creates a fresh DPoP proof JWT containing the HTTP method, target URI, access token hash (ath), and a unique identifier (jti)
3. Sends both the Authorization: DPoP <token> header and the DPoP: <proof> header
4. The gateway validates the proof and verifies the token binding before processing the request

Automatic Retry

If the gateway rejects a DPoP proof (for example, due to a clock skew or transient validation error), the BFF automatically retries the request once with a fresh proof. A retry guard prevents infinite retry loops.

Token Refresh

When the access token expires, the BFF uses the refresh token with a fresh DPoP proof to obtain a new access token. The same key pair is reused for the entire session lifetime, maintaining the binding without re-authentication.

Security Properties

Property	Mechanism
Key isolation	Private keys stored in server-side session storage, never sent to the browser
Token binding	Access tokens bound to key pair via cnf.jkt claim
Proof freshness	Each proof contains a unique jti, current timestamp, and request-specific htm/htu
Session scope	Key pair lifetime matches session lifetime
Rollback capability	DPoP can be disabled via configuration flag for instant rollback

Diagram

Example Scenario

Scenario

An administrator logs into the Admin Console to manage authorization policies. The BFF handles DPoP transparently.

Input

• Actor: Administrator (admin@example.com)
• Resource: Admin Console login flow
• Action: Authenticate and access platform APIs
• Context: DPoP is enabled in the Admin Console configuration

Expected Outcome

• Granted
• Why: The BFF generates a key pair at login, binds the authorization code via dpop_jkt, exchanges the code with a DPoP proof, and attaches fresh proofs to every subsequent API request. The gateway validates each proof and verifies the token binding.

Common Misunderstandings

• The browser handles DPoP keys — The browser has no access to DPoP keys or tokens. All cryptographic operations happen in the BFF. The browser communicates with the BFF using session cookies only.
• DPoP adds visible steps for administrators — DPoP is transparent to the end user. The login flow and API interactions look identical whether DPoP is enabled or disabled.
• A stolen session cookie enables token replay — Even if a session cookie is stolen, the attacker cannot replay API requests from a different context because the gateway validates DPoP proofs that are bound to specific HTTP methods and URIs.

warning

DPoP session binding relies on the security of the server-side session store. Ensure that the session store is configured with authentication and network isolation to prevent unauthorized access to stored key material.

Design Notes / Best Practices

• The Admin Console uses ES256 (ECDSA with P-256) for DPoP key pairs, providing strong security with compact proof sizes.
• Key pairs are cached in memory to avoid repeated cryptographic import operations on every request.
• DPoP can be toggled via an environment variable, enabling instant rollback if issues arise during deployment.

tip

Monitor DPoP-related error metrics in the gateway to detect proof validation failures that may indicate configuration issues or attack attempts targeting admin sessions.

Related Use Cases

• Protecting administrative sessions in compliance-sensitive environments
• Preventing session hijacking for privileged platform operations
• Meeting regulatory requirements for admin access token binding

Related Docs

DPoP Enforcement Model

How the gateway validates DPoP proofs and enforces token binding.

Replay, Downgrade & Abuse Protection

Replay and downgrade detection mechanisms.

OAuth Client Security

Client lifecycle and credential governance.

Security Overview

Central entry point for Keymate security capabilities.