此页面由 Cloud Translation API 翻译。

私密状态令牌开发者指南

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

私密状态令牌提供了一种在网络上共享信息的方法，但它以保护隐私的方式控制实际可以共享的数据量。

私密状态令牌（以前称为“信任令牌”）允许在不同情境之间传递对用户真实性的信任，同时帮助网站打击欺诈行为并将机器人与真人区分开来，而无需被动跟踪。

本文档简要介绍了实现私密状态令牌 (PST) 的技术详情。如需更简要地了解相关信息，请参阅 PST 概览。

适用于 PST 的学习流程。 — PST 学习流程：此流程由多个步骤组成，从了解 API 开始，到定义您自己的令牌策略（更多与产品或业务相关的活动）。之后，技术阶段就是在本地环境中实现演示，然后将其应用于实际用例。

私密状态令牌的工作原理

在 PST 中，要了解的关键关系是发卡机构和兑换者之间的关系。发行者和兑换者可以属于同一家公司。

颁发者 - 这些实体具有一些关于用户的信号（例如，用户是否为聊天机器人），并将该信号嵌入到用户设备上存储的令牌中（如需了解详情，请参阅下一部分）。
兑换者 - 此类实体可能没有用户的信号，但需要了解相关信息（例如，用户是否为机器人），并请求兑换颁发者提供的令牌，以了解用户的可信度。

每次 PST 互动都要求发卡机构和兑换者共同合作，以在整个网络上共享信号。这些信号是粗略的值，不够详细，无法用于识别个人。

私密状态令牌适合我吗？

正在做出信任决策并希望跨上下文提供相关信息的公司可以受益于 PST。如需详细了解 PST 的潜在用例，请参阅我们关于 PST 用例的文档。

发放和兑换令牌

PST 的实现分为三个阶段：

颁发令牌
兑换令牌
兑换记录转发

在第一阶段，令牌将发放给浏览器（通常在某种验证之后）。在第二个阶段，另一个实体将发出请求，兑换已签发的令牌，以读取该令牌中的值。在最后一阶段，兑换方会收到一条兑换记录 (RR)，其中包含令牌中所含的值。然后，该兑换方可出于各种目的使用该记录作为该用户证明。

私密状态令牌的基本流程。 — 序列图：该图显示了在真实场景中 PST 的基本用法，其中两个网站想要交换关于该特定 Chrome 实例的某些信号。这两个网站会在不同的时刻执行签发和兑换操作，从而能够在两者之间交换可信信号。

定义令牌策略

要定义令牌策略，您需要了解 PST 关键概念（令牌和兑换记录）、变量、行为和限制，以便思考它们在您的用例中的潜在用途。

令牌和兑换记录：它们之间有何关系？

每台设备最多可为每个顶级网站和颁发机构存储 500 个令牌。此外，每个令牌都包含元数据，用于告知发卡机构使用哪个密钥来颁发令牌。在兑换过程中，此信息可用于决定是否兑换令牌。PST 数据由用户设备上的浏览器存储在内部，只能通过 PST API 访问。

兑换令牌时，兑换记录 (RR) 会存储在设备上。该存储空间会用作日后兑换的缓存。对于每个设备、页面和发卡机构，每 48 小时只能兑换两个令牌。新的兑换调用将尽可能使用缓存的 RR，而不是向发卡机构发出请求。

发放新令牌（每个颁发者、网站和设备最多 500 个令牌）。
所有令牌都存储在设备端令牌存储中（与 Cookie 存储类似）。
如果未找到有效的 RR，则可以在发布后生成新的 RR（每 48 小时最多生成 2 个）。
RR 在到期之前被视为有效，并且将用作本地缓存。
新的兑换调用将到达本地缓存（不会生成新的 RR）。

定义用例后，您必须仔细定义 RR 的有效期，因为这将定义您可以在您的用例中使用它们的次数。

在定义策略之前，请确保您了解以下关键行为和变量：

变量 / 行为	说明	潜在用途
令牌密钥元数据	每个令牌只能使用一个加密密钥发出，而在 PST 中，每个颁发者只能有 6 个密钥。	使用此变量的一种潜在方法是根据您的加密密钥定义令牌的信任范围（例如，密钥 1 = 高信任度，而密钥 6 = 不信任）。
令牌失效日期	令牌失效日期与密钥失效日期相同。	密钥至少每 60 天轮替一次，使用无效密钥颁发的所有令牌也被视为无效。
令牌兑换速率限制	每 48 小时，每台设备和发卡机构最多只能兑换两次令牌。	取决于您的用例每 48 小时预计需要的兑换次数。
每个顶级源的发卡机构数量上限	目前，每个顶级源的发卡机构数量上限为 2 个。	仔细定义每个页面的发卡机构。
设备上每个颁发者的令牌数	目前，特定设备上每个颁发者的令牌数量上限为 500。	确保每个发卡机构的令牌数量少于 500 个。在尝试颁发令牌时，请务必处理网页中的错误。
密钥承诺轮替	每个 PST 颁发者都需要提供一个端点，该端点具有每 60 天可以更改一次的密钥承诺，并且任何轮替速度快于该时间的轮替都将会被忽略。	如果您的密钥将在 60 天内到期，您必须在该日期之前更新密钥承诺，以免服务中断（请参阅详细信息）。
兑换记录有效期	可以定义 RR 的有效期来确定到期日期。由于会缓存 RR，以避免对发卡机构进行不必要的新兑换调用，因此请务必确保拥有足够新的兑换信号。	由于兑换率限制为每 48 小时两个令牌，因此请务必定义 RR 的有效期，以便能够至少在此时间段内成功执行兑换调用（应相应地设置 RR 有效期）。建议将此有效期设置为几周。

场景示例

场景 1：RR 有效期短于 24 小时 (t=t)，兑换在 48 小时内多次执行。

PST 示例场景 1：短寿命。 — 在这种情况下，在 28 小时内，用户将无法兑换新令牌，并且所有 RR 都将过期。

场景 2：RR 有效期为 24 小时，在 48 小时内多次执行兑换。

PST 场景 2 示例：有效期 24 小时。 — 在这种情况下，由于 RR 的有效期为 24 小时，因此可在这 48 小时内进行兑换，而没有任何限制。

场景 3：RR 有效期为 48 小时，在 48 小时的期限内多次执行兑换。

PST 场景 3 示例：有效期 48 小时。 — 在这种情况下，由于 RR 的有效期为 48 小时，因此可在这 48 小时内进行兑换，而没有任何限制。

运行演示

在采用 PST 之前，我们建议您先通过演示版进行设置。如需试用 PST 演示版，您需要运行带有标志的 Chrome，以启用演示版颁发者密钥承诺（请按照演示页面上的说明操作）。

通过运行此演示，您的浏览器将使用演示颁发者和兑换器服务器来提供和消耗令牌。

技术问题

如果您执行以下步骤，演示的运行效果最佳：

在运行带有标志的 Chrome 之前，请务必停止所有 Chrome 实例。
如果您是在 Windows 计算机上运行，请查看此指南，了解如何将参数传递给 Chrome 可执行二进制文件。
使用演示版应用时，在 Applications > Storage > Private State Tokens 下打开 Chrome DevTools，以查看演示颁发者发放/兑换的令牌。

为采用做好准备

成为发卡机构

发卡机构在 PST 中扮演着重要角色。它们为令牌分配值，以确定用户是否是机器人。如果您想开始使用 PST 作为发卡机构，则需要完成发卡机构注册流程进行注册。

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

颁发者服务器

颁发者和兑换者是 PST 的关键参与者；服务器和令牌是 PST 的关键工具。虽然我们已经在 GitHub 文档中提供了有关令牌的一些详细信息，但还是希望提供有关 PST 服务器的更多详细信息。如需设置为 PST 的颁发者，您需要先设置签发服务器。

部署您的环境：颁发者服务器

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

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

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

颁发者服务器：在我们的示例实现中，我们的签发服务器是一个 Node.js 服务器，它使用 Express 框架来托管颁发者 HTTP 端点。您可以查看 GitHub 上的示例代码。
令牌颁发者：颁发者加密组件不需要任何特定语言，但鉴于此组件的性能要求，我们提供 C 实现作为示例，该实现使用 Boring SSL 库管理令牌。您可以在 GitHub 上找到颁发者代码示例以及有关安装的更多信息
密钥：令牌颁发者组件使用自定义 EC 密钥来加密令牌。这些密钥必须受到保护并存储在安全的存储空间中。

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

根据协议，您需要在颁发者服务器中至少实现两个 HTTP 端点：

密钥承诺（例如 /.well-known/private-state-token/key-commitment）：浏览器可在此端点获取您的加密公钥详细信息，以确认您的服务器是否合法。
- 示例代码
令牌颁发（例如 /.well-known/private-state-token/issuance）：令牌颁发端点，将处理所有令牌请求。此端点将是令牌颁发者组件的集成点。
- 示例代码

如前所述，由于预计此服务器可能会处理的高流量，我们建议您使用可扩缩的基础架构（例如，在云环境中）对其进行部署，以便能够根据可变需求调整后端。

向颁发者服务器发送调用

对您的发卡机构堆栈实现网站提取调用，以颁发新令牌。

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

查看代码示例。

兑换器服务器

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

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

兑换器服务器组件。 — PST 演示组件：这些是兑换器服务器的主要组件。兑换器服务器（Node.js 应用）和令牌兑换器（负责在兑换流程中验证签名和令牌的加密组件）。

兑换器服务器的技术要求

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

/.well-known/private-state-token/redemption：将处理所有令牌兑换的端点。将在此端点集成令牌 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
您拥有并控制它：如有必要，您可以快速停用实现，而无需进行复杂审批
不超过一个颁发者：限制令牌数量以简化测试。
最多两个兑换者：您需要简化出现问题时的问题排查。

问题排查

您可以从 Chrome DevTools 的“Network”（网络）和“Application”（应用）标签页中检查 PST。

在“网络”标签页上：

针对“Network”标签页的开发者工具检查。 — 针对 PST 的开发者工具检查：转到网络 > **不公开状态令牌**，获取特定网页的令牌和颁发者的所有相关信息。

在“应用程序”标签页上：

“Application”标签页的开发者工具检查。 — 针对 PST 的开发者工具检查：依次转到“应用”>“私密状态令牌”，获取特定网页的令牌和颁发者的所有相关信息。

如需了解详情，请参阅此 DevTools 集成。

服务器最佳做法和问题排查

为了让您的发卡机构和兑换者服务器有效运行，我们建议您实施以下最佳实践，以确保您不会遇到与 PST 相关的任何访问、安全、日志记录或流量方面的问题。

您的端点必须使用 TLS 1.3 或 1.2 来应用强加密。
您的基础架构必须准备好应对不定的流量（包括高峰）。
确保您的密钥受到妥善保护，并与您的访问权限控制政策、密钥管理策略和业务连续性计划保持一致。
向您的堆栈添加可观测性指标，以确保在进入生产阶段后，您清晰地了解使用情况、瓶颈和性能问题。