Demonstrating Proof-of-Possession (DPoP)

Auth0 で Demonstrating Proof-of-Possession (DPoP) を使用してアクセストークンに送信者制約を適用する方法を学びます。

Demonstrating Proof-of-Possession (DPoP) は、非対称暗号方式とアプリケーション層の アクセストークン、および JSON Web Tokens (JWT) を使用して、アクセストークンをクライアントに結び付ける、つまり 送信者制約 を適用するための OAuth 2.0 framework extension です。DPoP により、秘密キーを保持する、アクセストークンを要求したクライアントアプリケーションのみがそのトークンを使用できるようになります。これにより、盗まれたトークンの悪用を防止します。

DPoP は公開鍵/秘密鍵を使用して、署名付き JSON Web トークン (JWT) として DPoP Proof を作成します。DPoP Proof には次のものが含まれます。

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

クライアントアプリケーションは、アクセストークンrequestで DPoP Proof JWT を Auth0 の 認可サーバー に送信します。Auth0 Authorization Server が DPoP Proof JWT をvalidateした後、発行されたアクセストークンをクライアントの公開鍵に結び付けます。

​

一般的な利用例

代表的な DPoP の利用例をいくつか紹介します。

• Single Page Applications (SPAs) and mobile applications: 公開クライアントである SPA やモバイルアプリケーションには、バックエンドサーバーのような、クライアントシークレット を安全に保存できる信頼された機密環境がありません。そのため、トークン盗難に対して脆弱です。DPoP は、アクセストークンをクライアントアプリケーションの公開キーに結び付けて DPoP Proof JWT を作成することで、このセキュリティ脆弱性に対処します。クライアントアプリケーションは、自身の秘密キーで DPoP Proof JWT に署名し、認可リクエストで送信します。Auth0 Authorization Server は DPoP Proof JWT を検証し、有効であれば、発行するアクセストークンをクライアントの公開キーに結び付けます。
• Third-party API integrations: クライアントアプリケーションと連携した AI エージェントが、ユーザーに代わって DPoP Proof JWT を使用してサードパーティ API を呼び出す場合、リソースサーバー は、そのリクエストが権限のない第三者ではなく AI エージェントから送信されたものであることを、暗号学的に検証できます。

​

サポートされているアプリケーションのグラントタイプ

Auth0 は、DPoP を使用した送信者拘束向けに、次のアプリケーションのグラントタイプをサポートしています。

グラントタイプ	説明
authorization_code	認可コードグラント
client_credentials	クライアントクレデンシャルグラント
password	リソース所有者パスワードグラント
refresh_token	リフレッシュトークングラント
urn:ietf:params:oauth:grant-type:device_code	デバイス認可グラント
http://auth0.com/oauth/grant-type/password-realm	特定のレルムを指定できる、リソース所有者パスワードグラントに類似した拡張グラントを使用します
http://auth0.com/oauth/grant-type/passwordless/otp	パスワードレスグラントリクエスト
http://auth0.com/oauth/grant-type/mfa-oob	多要素認証アウトオブバンドグラントリクエスト
http://auth0.com/oauth/grant-type/mfa-otp	多要素認証 OTP グラントリクエスト
http://auth0.com/oauth/grant-type/mfa-recovery-code	多要素認証リカバリーコードグラントリクエスト
urn:ietf:params:oauth:grant-type:token-exchange	カスタムトークン交換グラントリクエスト
urn:okta:params:oauth:grant-type:webauthn	WebAuthn グラントリクエスト

​

仕組み

次のシーケンス図は、Auth0 DPoP フローの概要を示しています。

1. Auth0 Authorization Server にアクセストークンをリクエストする際、クライアントアプリケーションは一意の暗号鍵ペアを生成し、公開キーを使って対応する秘密キーを保有していることを証明します。
2. クライアントアプリケーションは DPoP Proof JWT を生成し、それを Auth0 Authorization Server の /token エンドポイントに送信します。
3. Auth0 Authorization Server は DPoP Proof JWT を検証し、有効であればアクセストークンを発行して、クライアントの公開キーに紐付けます。
4. Customer API を呼び出す前に、クライアントアプリケーションは新しい DPoP Proof JWT を生成し、トークンに紐付けられた秘密キーを保有していることを証明します。クライアントアプリケーションは、DPoP Proof JWT と sender-constrained アクセストークンをリソースサーバーに送信します。
5. リソースサーバーは DPoP Proof JWT を検証し、トークンの正当な所有者、つまり元のクライアントアプリケーションだけが、それを使って保護されたリソースに正常にアクセスできることを確認します。リフレッシュトークンからアクセストークンをリクエストする場合、クライアントアプリケーションは新しい DPoP Proof JWT を生成し、リフレッシュトークンがクライアントの公開キーに紐付けられるようにします。

​

Auth0 で DPoP を使用してトークンに送信者拘束を適用する

次の図は、Auth0 で DPoP を使用してトークンに送信者拘束を適用するエンドツーエンドのフローを示しています。

以下のセクションでは、実装用のコードサンプルとともに、Auth0 での DPoP フローを順を追って説明します。

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

​

前提条件

開始する前に、次の点を確認してください。

• クライアントアプリケーションとリソースサーバーに対して、送信者拘束を設定していること。

​

ステップ1: クライアントアプリケーションがDPoPキーペアを生成する

DPoPでは、クライアントアプリケーションは非対称暗号のキーペアを生成する必要があります。Auth0は、ES256キーなどの楕円曲線暗号の使用をサポートしています。このキーペアはクライアントアプリケーションごとに固有のもので、たとえばハードウェアで保護されたキーストアに安全に保管する必要があります。

クライアントアプリケーションは秘密鍵を厳重に保持しつつ、ステップ2で「Proof of Possession」として機能するDPoP Proof JSON Web トークン (JWT) に公開鍵を含めます。

​

ステップ 2: クライアントアプリケーションが DPoP Proof JWT を作成する

Auth0 Authorization Server の /token エンドポイントに DPoP にバインドされたアクセストークンをリクエストする前に、クライアントアプリケーションは DPoP Proof JWT を作成する必要があります。DPoP Proof JWT は、クライアントの秘密キーで署名された JSON Web トークン (JWT) で、「Proof of Possession (所持証明) 」として機能します。

DPoP Proof JWT は、JWT ヘッダーと、トークンリクエストに関連するクレームを含むペイロードで構成されます。

​

JWTヘッダーのクレーム

DPoP Proof JWT クレーム	説明
typ	dpop+jwt に設定します。
alg	RS256 や ES256 などの非対称署名アルゴリズムです。
jwk	クライアントの公開キーを表す JSON Web Key (JWK) です。

​

JWT ペイロードクレーム

DPoP Proof JWT クレーム	説明
jti	リプレイ攻撃を防ぐための、JWT の一意の識別子です。
htm	DPoP 証明の対象となるリクエストの HTTP メソッドです。たとえば、トークンリクエストでは POST、API 呼び出しでは GET です。
htu	DPoP Proof JWT の対象となるリクエストの HTTP URI です。フラグメントとクエリパラメータは含みません。たとえば、https://api.example.com/data?param=1#section1 は https://api.example.com/data になります。
iat	JWT の作成時刻を表すタイムスタンプです。
ath	アクセストークンを使用する API 呼び出しでは、アクセストークンの SHA-256 ハッシュを base64url エンコードした値です。
nonce	nonce を必要とするパブリッククライアントでは、サーバーから提供される nonce 値です。

クライアントアプリケーションで DPoP Proof JWT を作成したら、Step 1 で生成した秘密キーを使って DPoP Proof JWT に署名します。

以下のコードサンプルは、クライアントアプリケーションで DPoP Proof JWT を作成して署名する方法を示しています。

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,
    },
  });

​

ステップ 3: クライアントアプリケーションが DPoP-bound token をリクエストする

クライアントアプリケーションが Auth0 Authorization Server の /token エンドポイントに access token をリクエストする際は、リクエストの HTTP ヘッダーに DPoP Proof JWT を含めます。

DPoP: {DPoP_proof_JWT_value}

以下は、DPoP Proof JWT が設定された DPoP HTTPヘッダーを含むアクセストークンリクエストの例です。

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

クライアントアプリケーションで DPoP バインド アクセストークンをリクエストする方法を実装するには、次のコードサンプルを使用します。このサンプルでは、以下を行います。

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);

​

パブリッククライアント

シングルページアプリケーション (SPA) やモバイルアプリなどのパブリッククライアントが DPoP にバインドされたアクセストークンをリクエストする場合、client secret やその他のクライアント認証パラメーターは使用できません。この場合、RFC 9449 に従い、Auth0 はクライアントアプリケーションが DPoP Proof JWT を直近で生成したことを確認するため、DPoP HTTP header に nonce 値が含まれていることを求めます。これは想定どおりの動作であり、認可サーバーが DPoP proof の新しさを確認し、その proof を使用できる時間を限定できるようにするためです。

パブリッククライアントが /token request を行う際に、DPoP HTTP header に nonce 値を含めない場合、Auth0 は HTTP 400 コードと、次のようなエラーメッセージを返します。

{
  error: 'use_dpop_nonce',
  error_description: '認証サーバーはDPoP証明にnonceを要求しています'
}

Auth0 は、レスポンスヘッダーに DPoP-Nonce ヘッダーを含めます。これは、DPoP specification で定義されている標準の「challenge-response」フローに従ったものです。DPoP-Nonce ヘッダーの値を使用して DPoP proof を再生成し (Step 2 と同様) 、その値を含む nonce クレームを追加したうえで、/token エンドポイントへのリクエストを再送信する必要があります。

次のコードサンプルは、パブリッククライアントから nonce クレームを含む /token リクエストを送信し、その後再試行する際のエンドツーエンドのフローを示しています。

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,
      },
    });
  }

// 最初はノンスなしでアクセストークンをリクエストする 
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 };
}

// 最初のトークンリクエスト時はノンスがない
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)); 

  console.log('Tokens received:', result);
}

​

ステップ 4: Auth0 Authorization Server が DPoP Proof JWT を検証する

Auth0 Authorization Server はトークンリクエストを受信すると、次の処理を行います。

• DPoP Proof JWT、その公開キー、署名を抽出します。
• 提供された公開キーを使用して署名を検証します。
• htm、htu、jti,、iat の各クレームを検証します。
• 有効であれば、アクセストークンを発行します。Auth0 Authorization Server は、確認用クレーム cnf をアクセストークンに含めます。cnf クレームには、DPoP Proof JWT から取得した公開キーの thumbprint (ハッシュ) が含まれます。これをアクセストークンに含めることで、Auth0 Authorization Server はそのアクセストークンを特定の公開キーに関連付けます。つまり、アクセストークンを “sender-constrains” します。
• トークンレスポンスでは、Authorization ヘッダーの token_type を Bearer ではなく DPoP に設定します。通常、アクセストークンを Authorization ヘッダーで渡す場合、token_type は Bearer に設定されます。しかし、ここでは DPoP を使用して公開キーに関連付けられたアクセストークンを渡すため、代わりに DPoP に設定されます。
• その後、Auth0 Authorization Server は DPoP sender-constrained アクセストークンをクライアントアプリケーションに発行します。

​

ステップ 5: クライアントアプリケーションが DPoP-bound token と DPoP Proof JWT を使用して API を呼び出す

DPoP を強制するリソースサーバーに対する API 呼び出しごとに、クライアントアプリケーションは DPoP-bound access token と新しい DPoP Proof JWT の両方を提示する必要があります。

DPoP は、すべての API リクエストで DPoP Proof JWT を必須にすることで、秘密キーを保持するクライアントアプリケーションだけがアクセストークンを使用できるようにします。

新しい API リクエストでは、クライアントアプリケーションは次のことを行います。

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

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

2. クライアントの秘密キーを使って、新しい DPoP Proof JWT に暗号学的に署名します。

3. DPoP 認証スキームを使用して、Authorization ヘッダーに DPoP-bound access token を含めます。

// DPoP スキームは認可サーバーから受け取った token_type に合わせます
Authorization: DPoP {access_token}

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

DPoP: {new_dpop_proof_jwt}

DPoP HTTPヘッダーには、追加のathクレームを含める必要があります。athクレームは、発行されたアクセストークンのSHA256ハッシュをbase64urlエンコードしたものです。

リソースサーバーは次の処理を行います。

• APIリクエストを受信し、アクセストークン、DPoP Proof JWT、公開キー、署名を抽出します。
• jwkヘッダー内の公開キーを使用して、DPoP Proof JWTの署名を検証します。
• htm、htu、jti、iat、athの各クレームを検証します。
• DPoP Proof JWTのjwkヘッダーで示された公開キーが、アクセストークン内のcnf.jktクレームによってアクセストークンに関連付けられた公開キーと一致することを検証します。

jtiのリプレイ保護の実装はリソースサーバーの責任です。すべてのAuth0 SDKsがデフォルトでjtiのリプレイ保護を強制するわけではありません。

すべてのチェックに成功した場合、リソースサーバーはリクエストを認可します。そうでない場合は、リクエストを拒否し、アクセスを拒否します。

次のコードサンプルでは、DPoPを使用してAuth0からアクセストークンをリクエストし、その後、DPoPにバインドされたアクセストークンを使用して/userinfoエンドポイントを呼び出します。

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());

​

ステップ 6: DPoP を使用してトークンの更新を処理する

DPoP にバインドされたアクセストークンの有効期限が切れた場合は、新しいアクセストークンを取得するために リフレッシュトークン を使用できます。リフレッシュトークンのリクエストには、元のトークンリクエストで使用したものと同じキーペアで生成した DPoP Proof JWT が必要です。

以下では、Auth0 における DPoP を使用したリフレッシュトークンのフローについて説明します。

クライアントアプリケーションは次を行います。

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

Auth0 認可サーバーは次を行います。

• DPoP Proof JWT を検証し (ステップ 4 と同様) 、新しい DPoP バインドアクセストークンを発行します。

​

重要な考慮事項

クライアントアプリケーションに DPoP を実装する際は、次の点を考慮してください。

• 秘密キーのセキュリティ: DPoP 実装の安全性はクライアントの秘密キーの安全性に依存するため、不正アクセスから保護する必要があります。秘密キーは、ハードウェアに裏打ちされた領域で生成および保管し、エクスポート不可に設定する必要があります。
• リプレイ保護 (jti** と dpop-nonce):** DPoP Proof JWT の jti クレームは、/userinfo エンドポイントなどの保護されたリソースに対するリプレイ攻撃の防止に役立ちます。Auth0 Authorization Server はレスポンスで DPoP-Nonce HTTP ヘッダーを返し、公開クライアントはリプレイ保護を強化するために、後続の DPoP Proof JWT にこれを nonce クレームとして含める必要があります。
• レート制限: DPoP のチャレンジレスポンスフローでは、最初のリクエストの後にサーバーから提供された nonce を使って再試行が必要になる場合があるため、各やり取りは実質的に Auth0 テナントのレート制限 に対して 2 回のリクエストとしてカウントされます。アプリケーションのリクエスト量がこのオーバーヘッドを考慮していることを確認してください。
• エラー処理: invalid_dpop_proof や use_dpop_nonce など、Auth0 Authorization Server またはリソースサーバーから返される DPoP 固有のエラーを処理するロジックは、お客様側で実装する必要があります。
• クライアントの種類: クライアントシークレットを安全に保管できない Single Page Applications (SPAs) やモバイルアプリなどの公開クライアントには DPoP を使用してください。機密クライアントには、クライアントシークレットを持つバックエンドサービスなどが含まれます。DPoP はセキュリティをさらに強化しますが、これらにはすでに他の sender-constraining の仕組みがあります。
• パフォーマンス: API 呼び出しごとに DPoP Proof JWT を生成して署名すると、わずかなオーバーヘッドが追加されるため、クライアントアプリケーションの暗号処理が効率的であることを確認してください。
• キーのローテーション: セキュリティを強化するために、DPoP のキー ペアをローテーションする strategy を実装してください。同じセッションでは必ず同じキー ペアを使用してください。
• 永続化: セッションを維持し、DPoP-bound access token を再利用する必要があるクライアントアプリケーション (長期間利用される SPA など) では、アプリケーションの再読み込み後も、最初に生成したキー ペアを安全に保存し、再取得できるようにしてください。新しいキー ペアが生成されたり、別のキー ペアが使用されたりすると、DPoP-bound access token は元のペアの公開キーに暗号学的に結び付けられているため無効になります。たとえば、ブラウザーの IndexedDB やモバイルアプリの安全なストレージにキー ペアを保存できます。

​

詳細はこちら

• 送信者制約を設定する