プライベート ステート トークンのデベロッパー ガイド

これまで、サードパーティ Cookie は、ユーザーのログイン ステータス、使用しているデバイスに関する情報、ユーザーが既知の信頼できるユーザーであるかどうかなど、ユーザーの状態に関する情報を保存して伝達するために使用されてきました。たとえば、ユーザーが SSO でログインしているかどうか、ユーザーが特定の種類の互換性のあるデバイスを所有しているかどうか、ユーザーが既知の信頼できるユーザーであるかどうかなどです。サードパーティ Cookie のサポートが終了するため、これらのユースケースの多くは他の方法でサポートする必要があります。

プライベート状態トークンは、ウェブ全体で情報を共有する方法を提供しますが、実際に共有できるデータ量を制御することで、プライバシーを保護します。

プライベート ステート トークン（以前はトラスト トークンと呼ばれていました）を使用すると、ユーザーの信頼度をあるコンテキストから別のコンテキストに伝えることができ、サイトはパッシブ トラッキングを行わずに不正行為を防止し、bot と人間を区別できます。

このドキュメントでは、プライベート ステート トークン（PST）の実装に関する技術的な詳細について説明します。概要については、PST の概要をご覧ください。

Private State Tokens の仕組み

PST で理解すべき重要な関係は、発行者と利用者の関係です。発行者と利用者は同じ会社に属していても構いません。

• 発行者 - ユーザーに関するシグナル（ユーザーがボットかどうかなど）を持ち、そのシグナルをユーザーのデバイスに保存されるトークンに埋め込みます（詳細は次のセクションを参照）。
• 利用者 - ユーザーに関するシグナルを持っていないが、ユーザーについて何かを知る必要があり（たとえば、そのユーザーがボットかどうかなど）、発行者からトークンを利用して、そのユーザーの信頼性を把握することを求めるエンティティ。

PST のすべてのインタラクションでは、発行者と利用者が協力してウェブ全体でシグナルを共有する必要があります。これらのシグナルは、個人を特定するのに十分な詳細情報を含まない粗い値です。

プライベート ステート トークンは自分に適しているか

信頼性に関する決定を行っており、その情報をコンテキスト間で利用できるようにしたい企業は、PST を活用できます。PST の潜在的なユースケースの詳細については、PST のユースケースに関するドキュメントをご覧ください。

トークンを発行して利用する

PST の実装は次の 3 つのフェーズで行われます。

1. トークンの発行
2. トークンを利用する
3. 利用記録の転送

最初のフェーズでは、トークンがブラウザに発行されます（通常はなんらかの検証後）。第 2 フェーズでは、別のエンティティが、発行されたトークンを読み取ってその値を読み取るリクエストを行います。最終フェーズでは、利用者はトークンに含まれていた値を含む利用レコード（RR）を受け取ります。そのユーザーの証明書として、さまざまな目的で利用できます。

トークン戦略を定義する

トークン戦略を定義するには、PST の主なコンセプト（トークンと利用記録）、変数、動作、制限事項を理解し、ユースケースでの潜在的な使用方法を検討する必要があります。

トークンと利用記録: 両者の関係

デバイスごとに、トップレベルのウェブサイトと発行者ごとに最大 500 個のトークンを保存できます。また、各トークンには、発行者がトークンの発行に使用した鍵を示すメタデータが含まれています。この情報は、引き換えプロセス中にトークンを引き換えるかどうかを判断するために使用できます。PST データは、ユーザーのデバイスのブラウザによって内部的に保存され、PST API からのみアクセスできます。

トークンが利用されると、利用記録（RR）がデバイスに保存されます。このストレージは、今後の利用のためのキャッシュとして機能します。デバイス、ページ、発行者ごとに、48 時間ごとに 2 つのトークンのみ利用できます。新しい利用リクエストでは、発行者にリクエストを送信するのではなく、可能な場合はキャッシュに保存された RR が使用されます。

1. 新しいトークンが発行されます（発行者、サイト、デバイスごとに最大 500 個）。
2. すべてのトークンは、デバイス上のトークン ストア（Cookie ストアと同様）に保存されます。
3. 有効な RR が見つからない場合は、発行後に新しい RR を生成できます（48 時間ごとに最大 2 個）。
4. RR は有効期限まで有効とみなされ、ローカル キャッシュとして使用されます。
5. 新しい利用呼び出しはローカル キャッシュにヒットします（新しい RR は生成されません）。

ユースケースを定義したら、RR の有効期間を慎重に定義する必要があります。これは、ケースで RR を使用できる回数を定義するためです。

戦略を定義する前に、次の重要な動作と変数を理解しておいてください。

サンプル事例

シナリオ 1: RR の有効期間が 24 時間未満（t=t）で、48 時間の期間内に複数回利用された場合。

シナリオ 2: RR の有効期間が 24 時間で、48 時間の期間内に複数回利用された場合。

シナリオ 3: RR の有効期間が 48 時間で、48 時間の期間内に複数回利用された場合。

デモの実施

PST を導入する前に、デモで設定することをおすすめします。

このデモを実行すると、ブラウザはデモ発行者サーバーとデモ利用サーバーを使用してトークンを提供および使用します。

技術的な注意事項

次の手順を実施すると、デモが最適に実行されます。

• フラグ付きで Chrome を実行する前に、すべての Chrome インスタンスを停止してください。
• Windows マシンで実行している場合は、Chrome の実行可能バイナリにパラメータを渡す方法について こちらのガイドをご覧ください。
• デモ アプリケーションを使用しているときに、[アプリケーション] > [ストレージ] > [プライベート状態トークン] で Chrome DevTools を開き、デモ発行元によって発行または利用されたトークンを確認します。

導入を設定する

このセクションでは、PST の発行者または利用者になるための要件について説明します。

発行者になる

発行者は PST において重要な役割を果たします。トークンに値を割り当てて、ユーザーがボットかどうかを判断します。発行元として PST の使用を開始するには、発行元の登録プロセスを完了して登録する必要があります。

発行者になるには、発行者のウェブサイトの運営者が、GitHub リポジトリで「New PST Issuer」テンプレートを使用して新しい問題を開く必要があります。リポジトリのガイダンスに沿って問題を記入します。エンドポイントが検証されると、このリポジトリに統合され、Chrome サーバーサイド インフラストラクチャがこれらの鍵の取得を開始します。

発行元サーバー

発行者と利用者は PST の主要なアクターであり、サーバーとトークンは PST の主要なツールです。トークンについては、すでに GitHub のドキュメントで詳細を提供していますが、PST サーバーについてさらに詳しく説明します。PST の発行者として設定するには、まず発行サーバーを設定する必要があります。

環境をデプロイする: 発行者サーバー

トークン発行者サーバーを実装するには、HTTP エンドポイントを公開する独自のサーバーサイド アプリケーションを構築する必要があります。

発行者コンポーネントは、発行者サーバーとトークン発行者の 2 つのメイン モジュールで構成されています。

すべてのウェブ向けアプリケーションと同様に、発行者サーバーに追加の保護レイヤを設けることをおすすめします。

1. 発行者サーバー: この実装例では、発行サーバーは Node.js サーバーで、Express フレームワークを使用して発行者 HTTP エンドポイントをホストします。GitHub のサンプルコードをご覧ください。

2. トークン発行元: 発行元暗号コンポーネントには特定の言語は必要ありませんが、このコンポーネントのパフォーマンス要件により、トークンを管理するために Boring SSL ライブラリを使用する C 実装を例として提供しています。GitHub で発行者のコード例とインストールに関する詳細を確認する

3. 鍵: トークン発行者コンポーネントは、カスタム EC 鍵を使用してトークンを暗号化します。これらの鍵は保護され、安全なストレージに保存される必要があります。

発行者サーバーの技術要件

プロトコルに従って、発行者サーバーに少なくとも 2 つの HTTP エンドポイントを実装する必要があります。

• キーコミットメント（/.well-known/private-state-token/key-commitment など）: このエンドポイントは、サーバーが正当であることを確認するために、ブラウザが暗号化公開鍵の詳細を取得できる場所です。
  • GitHub のコードサンプル
  • デモをご覧ください
• トークンの発行（例: /.well-known/private-state-token/issuance）: すべてのトークン リクエストが処理されるトークン発行エンドポイント。このエンドポイントは、トークン発行者コンポーネントの統合ポイントになります。
  • GitHub のコードサンプル
  • デモを見る

前述のように、このサーバーはトラフィックの増加が予想されるため、スケーラブルなインフラストラクチャ（クラウド環境など）を使用してデプロイし、需要の変動に応じてバックエンドを調整できるようにすることをおすすめします。

カード発行会社のサーバーに呼び出しを送信する

新しいトークンを発行するために、発行者のスタックにウェブサイトのフェッチ呼び出しを実装します。

 // issuer request
    await fetch("/.well-known/private-state-token/issuance", {
      method: "POST",
      privateToken: {
        version: 1,
        operation: "token-request"
      }
    });

コード例を参照してください。

Redeemer サーバー

独自のサーバーサイド アプリケーションを構築して、トークン利用サービスを実装する必要があります。これにより、発行者が送信するトークンを読み取ることができます。次の手順では、トークンを利用する方法と、それらのトークンに関連付けられている利用記録を読み取る方法について説明します。

発行者と利用者を同じサーバー（またはサーバーのグループ）で実行することもできます。

利用サーバーの技術要件

プロトコルに従って、リディーマー サーバー用に少なくとも 2 つの HTTP エンドポイントを実装する必要があります。

• /.well-known/private-state-token/redemption: すべてのトークン利用が処理されるエンドポイント。このエンドポイントは、トークン利用コンポーネントが統合される場所になります。
  • GitHub のサンプルコード
  • デモ

Redeemer サーバーに呼び出しを送信する

トークンを利用するには、以前に発行されたトークンを利用するために、ウェブサイトの取得呼び出しをリディーマー スタックに実装する必要があります。

    // redemption request
    await fetch("/.well-known/private-state-token/redemption", {
      method: "POST",
      privateToken: {
        version: 1,
        operation: "token-redemption",
        refreshPolicy: "none"
      }
    });

コードサンプルを参照してください。

トークンを交換した後、別のフェッチ呼び出しを行うことで、交換記録（RR）を送信できます。

    // attach redemption records from the issuers to the request
    await fetch("<DESTINATION_RESOURCE>", {
      method: "POST",
      privateToken: {
        version: 1,
        operation: "send-redemption-record",
        issuers: [<ISSUER_DOMAIN>]
      }
    });

コードサンプルを参照してください。

実装をデプロイする

実装をテストするには、まず発行呼び出しが行われるウェブページに移動し、ロジックに従ってトークンが作成されていることを確認します。バックエンドで、呼び出しが仕様どおりに行われたことを確認します。次に、利用呼び出しが行われるウェブページに移動し、ロジックに従って RR が作成されていることを確認します。

実世界でのデプロイ

特定のユースケースに該当するターゲット ウェブサイトを選択することをおすすめします。

• 月間訪問者数が少ない場合（月間 100 万人未満）: まず、少数のユーザーに API をデプロイすることから始めます。
• 所有と制御: 必要に応じて、複雑な承認なしで実装をすばやく無効にできます。
• 発行者は 1 つのみ: テストを簡素化するために、トークンの量を制限します。
• 2 人以下の利用者に制限する: 問題が発生した場合のトラブルシューティングを簡素化する必要があります。

権限に関するポリシー

正しく機能させるには、PST API をトップレベル ページと、API を使用するすべてのサブリソースで使用できるようにする必要があります。

トークン リクエスト オペレーションは private-state-token-issuance ディレクティブによって制御されます。オペレーション token-redemption と send-redemption-record は、private-state-token-redemption ディレクティブによって制御されます。Chrome 132 以降では、これらのディレクティブの許可リストはデフォルトで *（すべてのオリジン）に設定されています。つまり、この機能は、トップレベル ページ、同一オリジンの iframe、クロスオリジンの iframe で、明示的な委任なしで利用できます。

サイトの特定のページで PST トークンの発行または利用をオプトアウトするには、各ページの Permissions-Policy ヘッダーに private-state-token-issuance=() と private-state-token-redemption=() を含めます。

Permissions-Policy ヘッダーを使用して、PST へのサードパーティ アクセスを制御することもできます。ヘッダー オリジン リストのパラメータとして、self と、API へのアクセスを許可するオリジンを使用します。たとえば、自分のオリジンと https://example.com を除くすべてのブラウジング コンテキストで PST の使用を完全に無効にするには、次の HTTP レスポンス ヘッダーを設定します。

Permissions-Policy:private-state-token-issuance=(self "https://example.com"),private-state-token-redemption=(self "https://example.com")

すべてのクロスオリジン リソースに対して API を有効にするには、オリジン リストを * に設定します。

Permissions Policy を使用してプライバシー サンドボックスの機能を制御する方法を学習するか、Permissions Policy の詳細をご覧ください。

トラブルシューティング

Chrome DevTools の [Network] タブと [Application] タブで PST を検査できます。

[ネットワーク] タブで次の操作を行います。

[アプリケーション] タブで次の操作を行います。

詳しくは、DevTools との統合をご覧ください。

クライアントのベスト プラクティス

ウェブサイトの重要な機能が特定のトークン発行者に依存している場合は、それらを優先します。他のスクリプトを読み込む前に、これらの優先発行者に対して hasPrivateToken(issuer) を呼び出します。これは、特典の利用に失敗する可能性を防ぐうえで重要です。

トップレベルあたりの発行者の数は2 つに制限されており、サードパーティ スクリプトが hasPrivateToken(issuer) を呼び出して、優先する発行者を優先しようとする場合もあります。そのため、サイトが想定どおりに動作するように、重要な発行者を事前に保護してください。

  // Prioritize your critical token issuer.
  document.hasPrivateToken('https://critical-issuer.example')
    .then(hasToken => {
      if (hasToken) {
        // Use the token or perform actions based on its availability.
      } else {
        // Handle the case where the token is not available.
      }
    });

  // Load third-party scripts or secure another token issuer (up to two in total).

サーバーのベスト プラクティスとトラブルシューティング

発行者サーバーと利用サーバーが効果的に動作するように、次のベスト プラクティスを実装して、PST のアクセス、セキュリティ、ロギング、トラフィックに関する問題が発生しないようにすることをおすすめします。

• エンドポイントでは、TLS 1.3 または 1.2 を使用して強力な暗号化を適用する必要があります。
• インフラストラクチャは、トラフィック量の変動（急増を含む）に対応できる状態である必要があります。
• 鍵が保護され、アクセス制御ポリシー、鍵管理戦略、事業継続計画に沿って安全に保管されていることを確認します。
• スタックにオブザーバビリティ指標を追加して、本番環境に移行した後も使用状況、ボトルネック、パフォーマンスの問題を把握できるようにします。

詳細

1. デベロッパー ドキュメントを確認します。
   1. まず、概要を読んで、PST とその機能を把握します。
   2. PST の紹介動画を視聴します。
   3. PST のデモをお試しください。
   4. また、API の説明もご覧ください。
   5. API の現在の仕様の詳細を確認する。
2. GitHub の問題または W3C の呼び出しを使用して、会話に参加してください。
3. 用語について詳しくは、プライバシー サンドボックスの用語集をご覧ください。
4. 「オリジン トライアル」や「Chrome フラグ」などの Chrome のコンセプトについて詳しくは、goo.gle/cc で公開されている短い動画や記事をご覧ください。