Demonstrating Proof-of-Possession (DPoP)

Documentation Index

Fetch the complete documentation index at: https://auth0.generaltranslation.app/llms.txt

Use this file to discover all available pages before exploring further.

• クライアントの公開鍵 (jwk)。
• メソッド (htm) と URI (htu) を含む、アクセストークンリクエストを参照するペイロード。
• クライアントの秘密鍵を使用して作成された署名。
• リプレイ防止用の一意の ID (jti)。
• 各 API リクエストごとの、アクセストークンの base64url エンコードされた SHA-256 ハッシュ (ath)。
• オプション: パブリッククライアントの場合、クライアントアプリケーションが最近 DPoP Proof JWT を生成したことを示すための nonce クレーム。

• シングルページアプリケーション (SPA) とモバイルアプリケーション: パブリッククライアントである SPA やモバイルアプリケーションには、バックエンドサーバーのように クライアントシークレット を安全に保存できる、信頼された機密性の高い環境がありません。そのため、トークン窃取のリスクにさらされます。DPoP は、アクセストークンをクライアントアプリケーションの公開鍵にバインドし、DPoP Proof JWT を作成することで、このセキュリティ上の脆弱性に対処します。クライアントアプリケーションは、自身の秘密鍵で DPoP Proof JWT に署名し、それを認可リクエストで送信します。Auth0 認可サーバーは DPoP Proof JWT を検証し、有効であれば、発行するアクセストークンをクライアントの公開鍵にバインドします。
• サードパーティ API 連携: クライアントアプリケーションに統合された AI エージェントが、ユーザーに代わって DPoP Proof JWT を使用してサードパーティ API を呼び出す場合、リソースサーバー は、そのリクエストが不正な第三者ではなく AI エージェントから送信されていることを暗号的に検証できます。

1. Auth0 認可サーバーからアクセストークンを要求するとき、クライアントアプリケーションは一意の暗号鍵ペアを生成し、その公開鍵を用いて、自身が対応する秘密鍵を保持していることを証明します。
2. クライアントアプリケーションは DPoP Proof JWT を生成し、それを Auth0 認可サーバー上の /token エンドポイントに送信します。
3. Auth0 認可サーバーは DPoP Proof JWT を検証し、有効であればアクセストークンを発行し、それをクライアントの公開鍵にバインドします。
4. Customer API を呼び出す前に、クライアントアプリケーションは新しい DPoP Proof JWT を生成し、トークンに関連付けられた秘密鍵を保持していることを証明します。クライアントアプリケーションは、DPoP Proof JWT と送信者制約付きアクセストークンをリソースサーバーに送信します。
5. リソースサーバーは DPoP Proof JWT を検証し、トークンの正当な所有者、すなわち元のクライアントアプリケーションだけが保護されたリソースに正常にアクセスできるようにします。リフレッシュトークンからアクセストークンを要求する場合も、クライアントアプリケーションは新しい DPoP Proof JWT を生成し、リフレッシュトークンがクライアントの公開鍵にバインドされていることを保証します。

• 前提条件
• ステップ 1: クライアントアプリケーションが DPoP キーペアを生成する
• ステップ 2: クライアントアプリケーションが DPoP Proof JWT を作成する
• ステップ 3: クライアントアプリケーションが DPoP バインドトークンをリクエストする
• ステップ 4: Auth0 認可サーバーが DPoP Proof JWT を検証する
• ステップ 5: クライアントアプリケーションが DPoP バインドトークンと DPoP Proof JWT を使用して API を呼び出す
• ステップ 6: DPoP を使用したトークンのリフレッシュを処理する

• クライアント アプリケーションおよびリソース サーバーに対して sender constraining を構成 済みであること。

import { generateKeyPairSync, randomBytes } from 'node:crypto';
import jwt from 'jsonwebtoken';

// DPoP 鍵ペアを生成
const keyPair = generateKeyPairSync('ec', {
  namedCurve: 'P-256',
});

// トークンリクエスト用の DPoP Proof JWT を構築
const jti = randomBytes(16).toString('base64url');
const jwk = keyPair.publicKey.export({ format: 'jwk' });
const dpopHeader = jwt.sign({
    jti,
    htm: 'POST',
    htu: 'https://[TENANT]/oauth/token',
    iat: Date.now() / 1000,
  },
  keyPair.privateKey,
  {
    algorithm: 'ES256',
    header: {
      typ: 'dpop+jwt',
      jwk,
    },
  });

DPoP: {DPoP_proof_JWT_value}

POST /oauth/token HTTP/1.1
Host: auth.example.com
Content-Type: application/x-www-form-urlencoded
DPoP: {DPoP Proof JWT}
Authorization: Basic Y2xpZW50MTIzOm15c2VjcmV0
Cache-Control: no-cache
grant_type=client_credentials&client_id=client123

1. 署名済みの DPoP Proof JWT を使用して DPoP HTTP ヘッダーを設定します。
2. 署名済みの DPoP Proof JWT を含む DPoP HTTP ヘッダーを、アクセストークンリクエストで /token エンドポイントに送信します。
3. Auth0 認可サーバーからのレスポンスを処理します。

// /oauth/token エンドポイントへリクエストを送信
// [...] を実際の grant_type、client_id、テナント URL に置き換えてください
const response = await fetch('https://[TENANT]/oauth/token', {
    method: 'POST',
    body: new URLSearchParams({
      grant_type: '...',
      client_id: '...',
      // その他のボディパラメータをここに記述
    }),
    headers: {
      "Content-Type": "application/x-www-form-urlencoded",
      // DPoP ヘッダーを追加
      dpop: dpopHeader
    }
  });

// Auth0 認可サーバーからのレスポンスを処理
const result = await response.json();
console.log('Initial token request result:', result);

{
  error: 'use_dpop_nonce',
  error_description: '認証サーバーはDPoP証明にnonceが必要です'
}

import { generateKeyPairSync, randomBytes } from 'node:crypto';
import jwt from 'jsonwebtoken';

// DPoP鍵ペアを生成
const keyPair = generateKeyPairSync('ec', {
  namedCurve: 'P-256',
});

/**
 * DPoP Proof JWTを生成するヘルパー関数。
 * @param {string} method - HTTPメソッド(例: 'POST'、'GET')。
 * @param {string} url - リクエストの完全なURL。
 * @param {string} [nonce] - サーバーからのオプションのDPoP-Nonce値。
 * @param {string} [accessToken] - 'ath'クレーム用にハッシュ化するオプションのアクセストークン。
 * @returns {string} 署名されたDPoP Proof JWT。
 */
function generateDPoPHeader(method, url, nonce) {
  const jti = randomBytes(16).toString('base64url');
  const jwk = keyPair.publicKey.export({ format: 'jwk' });
  return jwt.sign({
      jti,
      htm: method,
      htu: url,
      iat: Date.now() / 1000,
      nonce
    },
    keyPair.privateKey,
    {
      algorithm: 'ES256',
      header: {
        typ: 'dpop+jwt',
        jwk,
      },
    });
  }

// 初回はnonceなしでアクセストークンをリクエスト 
async function getTokens(nonce) {
  const response = await fetch('https://[TENANT]/oauth/token', {
      method: 'POST',
      body: new URLSearchParams({
        grant_type: '...',
        client_id: '...',
        // その他のボディパラメータをここに記述
      }),
      headers: {
        "Content-Type": "application/x-www-form-urlencoded",
        dpop: generateDPoPHeader('POST', 'https://[TENANT]/oauth/token', nonce),
      }
    });

  const result = await response.json();
  return { response, result };
}

// 初回のトークンリクエスト時にはnonceがない
let { response, result } = await getTokens(); 
console.log('初回トークンリクエスト結果:', result);

if (response.status === 400 && result.error === 'use_dpop_nonce') {
  const nonce = response.headers.get('dpop-nonce');

  console.log('受信したnonce:', nonce);

  // nonceを使用して再試行
  ({ response, result } = await getTokens(nonce)); 

  console.log('受信したトークン:', result);
}

• Extracts the DPoP Proof JWT, its public key, and signature.
• Verifies the signature using the provided public key.
• Validates the htm, htu, jti, and iat claims.
• If valid, it issues an access token. The Auth0 Authorization Server includes a confirmation claim, cnf, in the access token. The cnf claim contains the thumbprint (hash) of the public key taken from the DPoP Proof JWT. By including it in the access token, the Auth0 Authorization Server binds the access token to that specific public key, or “sender-constrains” the access token.
• Sets the token_type in the Authorization header to DPoP instead of Bearer in the token response. Traditionally, when the access token is passed in the Authorization header, it is set to Bearer. However, because we’re passing an access token bound to a public key using DPoP, it is set to DPoP instead.
• The Auth0 Authorization Server then issues the DPoP sender-constrained access token to your client application.

1. 次のクレームを含む新しい DPoP Proof JWT を生成します。

• htm クレームは、GET や POST などの、API リクエストの HTTP メソッドです。
• htu クレームは、API リクエストの URI です。
• ath クレームは、ステップ 3 で受け取った DPoP バインド済みアクセストークンの base64url エンコードされた SHA-256 ハッシュです。

2. クライアントの秘密鍵を使用して、新しい DPoP Proof JWT に暗号学的に署名します。
3. DPoP 認証スキームを使用して、Authorization ヘッダーに DPoP バインド済みアクセストークンを含めます。

// DPoP スキームは、認可サーバーから受信した token_type と一致します
Authorization: DPoP {access_token}

4. 新しく生成された DPoP Proof JWT を DPoP HTTP ヘッダーに含めます。

DPoP: {new_dpop_proof_jwt}

• API リクエストを受信し、アクセストークン、DPoP JWT プルーフ、公開鍵、および署名を抽出します。
• jwk ヘッダーに含まれる公開鍵を使用して、DPoP Proof JWT の署名を検証します。
• htm、htu、jti、iat、ath クレームを検証します。
• DPoP Proof JWT の jwk ヘッダーで示されている公開鍵が、アクセストークン内の cnf.jkt クレームを介してアクセストークンにバインドされている公開鍵と一致することを確認します。

import { generateKeyPairSync, randomBytes, createHash } from 'node:crypto';
import jwt from 'jsonwebtoken';

const keyPair = generateKeyPairSync('ec', {
  namedCurve: 'P-256',
});

function hashToken(token) {
  return createHash('sha256').update(token).digest('base64url');
}

function generateDPoPHeader(method, url, nonce, accessToken) {
  const jti = randomBytes(16).toString('base64url');
  const jwk = keyPair.publicKey.export({ format: 'jwk' });
  return jwt.sign({
      jti,
      htm: method,
      htu: url,
      iat: Date.now() / 1000,
      nonce,

      // オプションでアクセストークンハッシュを含む `ath` クレームを含める
      ...(accessToken ? { ath: hashToken(accessToken) } : {}),
    },
    keyPair.privateKey,
    {
      algorithm: 'ES256',
      header: {
        typ: 'dpop+jwt',
        jwk,
      },
    });
  }

async function getTokens(nonce) {
  const response = await fetch('https://[TENANT]/oauth/token', {
      method: 'POST',
      body: new URLSearchParams({
        grant_type: '...',
        client_id: '...',
        // その他のボディパラメータ
      }),
      headers: {
        "Content-Type": "application/x-www-form-urlencoded",
        dpop: generateDPoPHeader('POST', 'https://test1.local.dev.auth0.com/oauth/token', nonce),
      }
    });

  const result = await response.json();
  return { response, result };
}

// 初回実行時はnonceがない
let { response, result } = await getTokens(); 
console.log('Initial token request result:', result);

if (response.status === 400 && result.error === 'use_dpop_nonce') {
  const nonce = response.headers.get('dpop-nonce');
  console.log('Received nonce:', nonce);
  ({ response, result } = await getTokens(nonce)); // nonceを使って再試行
  console.log('Tokens received:', result);
}

// DPoPを使って /userinfo を呼び出す
const userInfoResponse = await fetch('https://[TENANT]/userinfo', {
  method: 'GET',
  headers: {
    // DPoP認可スキームを使ってアクセストークンを渡す
    Authorization: `DPoP ${result.access_token}`,

    // DPoPヘッダーを含める(今回はアクセストークンハッシュ付き)
    dpop: generateDPoPHeader('GET', 'https://[TENANT]/userinfo', nonce, result.access_token),
  },
});

console.log('User info response status:', userInfoResponse.status);
console.log('User info result:', await userInfoResponse.json());

• Auth0 認可サーバーの /token エンドポイントにリフレッシュトークンリクエストを送信します。
• リフレッシュトークンリクエスト用の DPoP Proof JWT を生成します（[htm を POST、htu を トークンエンドポイントの URI とする点が、ステップ 2と同様です）。
• DPoP HTTP ヘッダーに DPoP Proof JWT を含めます。

• DPoP Proof JWT を（ステップ 4と同様に）検証し、新しい DPoP によってバインドされたアクセストークンを発行します。

• Private key security: The security of your DPoP implementation depends on the security of your client’s private key, so you must protect it from unauthorized access. Private keys should be generated and stored in a hardware-backed medium and marked as non-exportable.
• Replay protection (jti** and dpop-nonce):** The jti claim in the DPoP Proof JWT helps prevent replay attacks for protected resources, such as the /userinfo endpoint. The Auth0 Authorization Server currently does not check jti reuse on the /userinfo endpoint. The Auth0 Authorization Server issues a DPoP-Nonce HTTP header in its response, which public clients must include as a nonce claim in subsequent DPoP Proof JWTs for enhanced replay protection.
• Error handling: You are responsible for implementing logic to handle DPoP-specific errors from the Auth0 Authorization Server or resource server, such as invalid_dpop_proof or use_dpop_nonce.
• Client types: Use DPoP for public clients, such as Single Page Applications (SPAs) or mobile apps that cannot securely store a client secret. For confidential clients, such as backend services with client secrets, DPoP adds a layer of security, but they already have other sender-constraining mechanisms.
• Performance: Because generating and signing DPoP Proof JWTs for every API call adds a small overhead, ensure your client application’s cryptographic operations are efficient.
• Key rotation: Implement a strategy for rotating your DPoP key pairs for enhanced security. Make sure you use the same key pair for the same session.
• Persistence: For client applications that need to maintain a session and reuse DPoP-bound access tokens, such as long-lived SPAs, securely persist and retrieve the original generated key pair across application reloads. If a new key pair is generated or a different key pair is used, the DPoP-bound access token becomes invalid, as it is cryptographically tied to the public key of the original pair. You can persist the key pair, for example, in a browser’s IndexedDB or a mobile app’s secure storage.

• Sender Constraining の構成