私密状态令牌开发者指南

过去，第三方 Cookie 一直用于存储和传递有关用户状态的信息，例如用户的登录状态、有关其所用设备的信息，或者用户是否是已知且受信任的。例如，用户是否已通过 SSO 登录、用户是否拥有某种类型的兼容设备，或者用户是否是已知且受信任的用户。随着第三方 Cookie 支持被弃用，许多此类用例将需要通过其他方式来支持。

Private State Token 提供了一种在网络上共享信息的方式，但通过控制实际可共享的数据量，以保护隐私的方式进行。

私密状态令牌（以前称为“信任令牌”）可将用户身份的真实性从一个上下文传递到另一个上下文，同时帮助网站打击欺诈行为并将机器人与真人区分开来，而无需进行被动跟踪。

本文档概述了实现私密状态令牌 (PST) 的技术细节。如需查看更高级别的概要，请参阅 PST 概览。

Private State Tokens 的运作方式

在 PST 中，需要了解的关键关系是发行方与兑换方之间的关系。 发行方和兑换方可以是同一公司。

• 签发者 - 这些实体拥有关于用户的某些信号（例如，相应用户是否为机器人），并将该信号嵌入到存储在用户设备上的令牌中（更多详情请参阅后续部分）。
• 兑换方 - 这些实体可能没有关于用户的信号，但需要了解用户的一些信息（例如，该用户是否为机器人），并请求从签发方兑换令牌，以了解该用户的可信度。

每次 PST 互动都需要发行方和兑换方共同在整个网络中共享信号。这些信号是粗略的值，不够详细，无法识别个人。

私密状态令牌是否适合我？

如果公司正在做出信任决策，并希望在各种情境中都能使用相关信息，那么可能会受益于 PST。如需详细了解 PST 的潜在使用场景，请参阅我们关于 PST 使用场景的文档。

发放和兑换令牌

PST 实现分为三个阶段：

1. 发放令牌
2. 兑换令牌
3. 兑换记录转发

在第一阶段，系统会向浏览器发放令牌（通常在进行某种验证之后）。在第二阶段，另一实体将请求兑换已签发的令牌，以读取该令牌中的值。在最后阶段，兑换方会收到一个兑换记录 (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 可执行二进制文件。
• 使用演示应用时，在 Applications > Storage > Private State Tokens 下打开 Chrome 开发者工具，查看演示发行方签发或兑换的令牌。

为采用进行设置

本部分介绍了成为 PST 发行方或兑换方的要求。

成为发卡机构

发卡机构在 PST 中发挥着关键作用。它们会为令牌分配值，以确定用户是否为机器人。如果您想以签发者的身份开始使用 PST，则需要完成签发者注册流程进行注册。

如需申请成为发行方，发行方网站的运营者必须使用“New PST Issuer”（新 PST 发行方）模板在 GitHub 代码库上提交新的问题。按照代码库中的指南填写问题。 端点经过验证后，将合并到此代码库中，Chrome 服务器端基础架构将开始提取这些密钥。

发卡机构服务器

对于 PST 而言，发行者和兑换者是关键角色；服务器和令牌是关键工具。虽然我们已在 GitHub 文档中提供了一些有关令牌的详细信息，但我们仍想提供有关 PST 服务器的更多详细信息。如需设置成为 PST 的发行方，您需要先设置发行服务器。

部署环境：签发者服务器

如需实现令牌颁发者服务器，您需要构建自己的公开 HTTP 端点的服务器端应用。

发行方组件由两个主要模块组成：(1) 发行方服务器和 (2) 令牌发行方。

与所有面向 Web 的应用一样，我们建议您为签发者服务器添加一层额外的保护。

1. 签发者服务器：在我们的示例实现中，签发者服务器是一个 Node.js 服务器，它使用 Express 框架来托管签发者 HTTP 端点。您可以查看 GitHub 上的示例代码。

2. 令牌签发者：签发者加密组件不需要任何特定语言，但由于此组件的性能要求，我们提供了一个 C 实现作为示例，该实现使用 Boring SSL 库来管理令牌。您可以在 GitHub 上找到签发者代码示例以及有关安装的更多信息

3. 密钥：令牌签发者组件使用自定义 EC 密钥来加密令牌。这些密钥必须受到保护并存储在安全存储空间中。

针对发卡机构服务器的技术要求

根据协议，您需要在签发者服务器中实现至少两个 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"
      }
    });

查看代码示例。

兑换服务器

您需要通过构建自己的服务器端应用来实现令牌兑换服务。这样，您就可以读取签发者发送的令牌。以下步骤概述了如何兑换令牌，以及如何读取与这些令牌关联的兑换记录。

您可以选择在同一服务器（或一组服务器）中运行签发者和兑换者。

兑换服务器的技术要求

根据该协议，您需要为兑换服务器实现至少两个 HTTP 端点：

• /.well-known/private-state-token/redemption：将处理所有令牌兑换的端点。此端点将是令牌兑换器组件的集成位置
  • GitHub 上的示例代码
  • 演示

向兑换服务器发送调用

如需兑换令牌，您需要向兑换方堆栈实现网站提取调用，以便兑换之前发放的令牌。

    // 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 部署到小规模受众群体
• 您拥有并掌控这些数据：如有必要，您可以快速停用该实现，无需复杂的审批流程
• 不超过一个发行方：限制令牌数量，以简化测试。
• 兑换者不超过 2 人：您需要简化问题排查流程，以防出现问题。

“权限”政策

为了正常运行，PST API 必须可供顶级网页和使用该 API 的任何子资源使用。

令牌请求操作由 private-state-token-issuance 指令控制。token-redemption 和 send-redemption-record 操作由 private-state-token-redemption 指令控制。在 Chrome 132 及更高版本中，这些指令的许可名单默认设置为 *（所有来源）。这意味着，顶级网页、同源 iframe 和跨源 iframe 无需明确的委托即可使用该功能。

您可以在每个网页的 Permissions-Policy 标头中添加 private-state-token-issuance=() 和 private-state-token-redemption=()，选择停用网站上特定网页的 PST 令牌发放或兑换功能。

您还可以使用 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，请将来源列表设置为 *。

了解如何使用权限政策控制 Privacy Sandbox 功能，或深入了解权限政策。

问题排查

您可以在 Chrome 开发者工具的“网络”和“应用”标签页中检查 PST。

在“网络”标签页中：

在“应用”标签页上：

详细了解此开发者工具集成。

客户最佳实践

如果网站的关键功能依赖于某些令牌签发者，请优先考虑这些令牌签发者。在加载任何其他脚本之前，请先针对这些首选发卡机构调用 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 explainer，详细了解相关信息。
   5. 详细了解该 API 的当前规范。
2. 您可以使用 GitHub 问题或 W3C 通话参与讨论。
3. 如需详细了解任何术语，请参阅 Privacy Sandbox 词汇表。
4. 如需详细了解 Chrome 概念（例如“源试用”或“Chrome 标志”），请查看 goo.gle/cc 中提供的短视频和文章。