Generate Proof

Generate proof for DPoP token exchange.

When to use: Use this when building a non-browser client or testing DPoP flows without a real frontend.

Prerequisites

Protect Your API page.

Client Flow Diagram

5-Line Core

Essential code to generate proof for DPoP token.

from gl_iam.client.dpop import DPoPClient

client = DPoPClient()
proof = client.create_proof(method, url, access_token)

Step-by-Step

1

Generate Key

create generate_key.py (demo key generation, in prod environment the key should be stored in client side, e.g. for browser we can use IndexedDB):

import json
import os
from gl_iam.client.dpop import DPoPClient
from cryptography.hazmat.primitives import serialization

def main():
    # Generate a new key pair
    client = DPoPClient()

    # Create keys directory if it doesn't exist
    keys_dir = "keys"
    os.makedirs(keys_dir, exist_ok=True)

    # Save private key (PEM format)
    # HACK: DPoPClient doesn't expose private key serialization.
    # Verify compatibility when upgrading gl-iam.
    private_key_pem = client._private_key.private_bytes(
        encoding=serialization.Encoding.PEM,
        format=serialization.PrivateFormat.PKCS8,
        encryption_algorithm=serialization.NoEncryption(),
    )
    with open(f"{keys_dir}/private_key.pem", "wb") as f:
        f.write(private_key_pem)

    # Save JWK (public key)
    with open(f"{keys_dir}/jwk.json", "w") as f:
        json.dump(client.jwk, f, indent=2)

    print("=" * 50)
    print("DPoP Key Generated")
    print("=" * 50)
    print(f"\nJWK Thumbprint: {client.jwk_thumbprint}")
    print("\nFiles saved:")
    print(f"  - {keys_dir}/private_key.pem")
    print(f"  - {keys_dir}/jwk.json")
    print("\nIMPORTANT: Use the SAME key for both:")
    print("  1. Requesting DPoP-bound token from Keycloak")
    print("  2. Creating DPoP proofs for protected resources")
    print("=" * 50)

if __name__ == "__main__":
    main()

2

Create Proof

create create_proof.py (making sure it uses the same key generated by generate_key.py):

import sys
import json
from cryptography.hazmat.primitives import serialization
from gl_iam.client.dpop import DPoPClient

def load_client():
    """Load a DPoPClient from persisted key files."""
    try:
        with open("keys/private_key.pem", "rb") as f:
            private_key = serialization.load_pem_private_key(f.read(), password=None)
        with open("keys/jwk.json", "r") as f:
            jwk = json.load(f)
    except FileNotFoundError as e:
        print("Error: Required key file(s) not found.")
        if e.filename:
            print(f"Missing file: {e.filename}")
        print(
            "Please run generate_key.py to generate the key files before running create_proof.py."
        )
        sys.exit(1)

    # Recreate client from loaded key
    # HACK: DPoPClient doesn't support loading existing keys yet.
    # Verify compatibility when upgrading gl-iam.
    client = DPoPClient()
    client._private_key = private_key
    client.jwk = jwk
    return client

def main():
    if len(sys.argv) < 3:
        print("Usage: python create_proof.py <http_method> <url> [access_token]")
        print("\nExamples:")
        print(
            '  python create_proof.py POST "http://localhost:8080/realms/dpop-demo/protocol/openid-connect/token"'
        )
        print(
            '  python create_proof.py GET "http://localhost:8000/api/protected" "eyJ..."'
        )
        sys.exit(1)

    http_method = sys.argv[1]
    http_url = sys.argv[2]
    access_token = sys.argv[3] if len(sys.argv) > 3 else None

    client = load_client()
    proof = client.create_proof(http_method, http_url, access_token)
    print(proof)

if __name__ == "__main__":
    main()

3

Test The Code

Use this generated proof for accessing protected resource in Protect Your API page.

# Generate your DPoP key pair
uv run generate_key.py

# Get DPoP-bound token
DPOP_PROOF=$(uv run create_proof.py POST "http://localhost:8080/realms/dpop-demo/protocol/openid-connect/token")
TOKEN=$(curl -s -X POST "http://localhost:8080/realms/dpop-demo/protocol/openid-connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "DPoP: $DPOP_PROOF" \
  -d "client_id=dpop-client" \
  -d "client_secret=dpop-secret" \
  -d "grant_type=password" \
  -d "username=[e-mail]" \
  -d "password=user123" | jq -r '.access_token')

Proof Structure Table

Claim	Purpose
htm	HTTP method
htu	HTTP URL
jti	Replay prevention
ath	Access token hash
iat	Freshness

Common Pitfalls

Pitfall	Why It Happens	How to Fix
Generating a new key for every request	DPoP keys are misunderstood as per-request instead of per-client	Generate the key once and persist it; reuse the same key for token requests and API calls
Using different keys for token request and API access	Token binding (cnf.jkt) ties the token to a specific public key	Always use the same private key that was used when requesting the access token
Reusing the same DPoP proof	DPoP proofs are one-time use and include jti	Generate a new proof for every HTTP request
Missing ath claim for resource requests	ath is optional for token requests but required for resource access	Include the access token when calling create_proof() for API requests
Incorrect HTTP method or URL in proof	Proofs bind to exact htm and htu values	Ensure the method and URL exactly match the outgoing HTTP request
Forgetting to handle nonce challenges	Some servers require nonce-based replay protection	On 401 + DPoP-Nonce, regenerate the proof including the nonce and retry
Treating DPoP as a browser-only feature	DPoP is often assumed to be frontend-only	Non-browser clients must explicitly manage key storage and proof generation

Production Notes

This proof-generation flow is for demonstration purposes only. In production, DPoP private keys must be generated, stored, and used inside a secure browser or mobile keystore.

Persisting keys to disk and accessing private key material directly—as shown in this example—is not appropriate for real clients and is used here solely to make the DPoP flow explicit.

Guidelines for Production Deployments

• Enable DPoP Only on HTTPS Endpoints Use HTTPS to transmit DPoP proofs and tokens securely via HTTP headers, preventing interception and replay attacks.

• Decide on DPoP Requirement During migration, support both bearer and DPoP tokens. For production, set:

  DPoPConfig(enabled=True, required=True)

  This setting helps fully prevent bearer-token replay attacks.

• Enable Nonce Protection for High-Security APIs Use nonce enforcement for an extra replay protection layer, especially for:

  • Financial operations

  • Privileged admin APIs

  • Internet-facing services

• Separate DPoP from Authorization DPoP ensures token possession but not permission. Continuously enforce:

  • Role checks

  • Organization membership

  • Resource-level authorization

• Monitor and Log DPoP Validation Failures Look out for potential issues such as:

  • Client misconfiguration

  • Replay attempts

  • Token theft attempts Ensure these events are observable in production logs and metrics.

• Thoroughly Test with Real Clients Beyond Python scripts for testing and CI, validate production readiness using:

  • Browser-based clients

  • Mobile apps

  • Real HTTP stacks with retries and concurrency

---

Found an issue on this page? Report it on our feedback form.