过去,第三方 Cookie 一直用来存储和传递信息 用户状态的相关信息,例如登录状态、设备的相关信息 以及是否了解其用户且可信。例如, 用户使用 SSO 登录,无论用户是否具有特定类型的兼容 或用户是否为已知且可信的用户。包含 不再支持第三方 Cookie 其中许多用例都需要通过其他方式提供支持。
私密状态令牌提供了一种在整个网络上分享信息的方法, 一种可保护隐私的方法, 共享。
私密状态令牌(以前称为“信任令牌”)可信任用户的 真实性可在不同的情境之间传达,同时帮助网站 打击欺诈行为并区分机器人与真人,而无需被动跟踪。
本文档简要介绍了实现私密状态的技术详情 令牌 (PST)。有关更高级的概述,请参阅 PST 概览。
<ph type="x-smartling-placeholder">![PST 的学习流程。](https://developers.google.cn/static/privacy-sandbox/protections/private-state-tokens/images/pstdevelopergu--a7powvbg65.png?authuser=1&hl=ca)
私密状态令牌的工作原理是什么?
在 PST 中,需要了解的关键关系是发卡机构和兑换者之间的关系。 发卡机构和兑换者可以属于同一家公司。
- Issuers(颁发者)- 这些实体具有关于用户的某种信号(例如 例如用户是否为机器人),并将信号嵌入到 存储在用户设备上的令牌(详见以下部分)。
- 兑换者 - 这些实体可能没有关于用户的信号,但 需要了解一些相关信息(例如,用户是否为聊天机器人) 并要求兑换发卡机构提供的令牌以了解 可信度。
每次 PST 互动都需要发卡机构和兑换者共同合作才能共享 信号。这些信号是粗略值,不详细 足够用于识别个人身份。
私密状态令牌适合我吗?
![私密状态令牌的使用场景。](https://developers.google.cn/static/privacy-sandbox/protections/private-state-tokens/images/pstdevelopergu--k013opby06j.png?authuser=1&hl=ca)
正在做出信任决策的公司希望 可通过 PST 处理。如需详细了解可能的应用场景 的 PST 数量, 请参阅关于 PST 用例的文档
颁发和兑换令牌
PST 的实施分为三个阶段:
- 颁发令牌
- 兑换令牌
- 兑换记录转发
在第一阶段,令牌会发放给浏览器(通常是在进行某种 验证)。在第二阶段,其他实体会提出兑换请求 为读取该令牌中的值而颁发的令牌。在决赛中 阶段,兑换方将收到兑换记录 (RR),价值是 包含在令牌中。然后,兑换方便可将该记录用作 出于各种目的对该用户进行认证。
<ph type="x-smartling-placeholder">![私密状态令牌的基本流程。](https://developers.google.cn/static/privacy-sandbox/protections/private-state-tokens/images/pstdevelopergu--mpu9o98yv8s.png?authuser=1&hl=ca)
定义令牌策略
要定义令牌策略,您需要了解 PST 关键概念(令牌) 和兑换记录)、变量、行为和限制 请考虑它们在您的用例中的潜在用途。
令牌和兑换记录:它们之间的关系是什么?
对于每个顶级网站和颁发者,每台设备最多可以存储 500 个令牌。此外, 每个令牌都具有元数据,用于说明颁发者使用哪个密钥来颁发令牌。这样 信息可用于决定在兑换期间是否兑换令牌 过程。PST 数据由用户设备上的浏览器在内部存储, 只能通过 PST API 访问。
用户兑换令牌后,兑换记录 (RR) 便会存储在设备上。 此存储空间可用作日后兑换的缓存。最多只能添加两个 每 48 小时兑换一次令牌。新兑换 调用将尽可能使用缓存的 RR,而不是向 发卡机构。
![PST 和 RR 之间的关系。](https://developers.google.cn/static/privacy-sandbox/protections/private-state-tokens/images/pstdevelopergu--k3dv3b99emg.png?authuser=1&hl=ca)
- 发放新令牌(每个发卡机构、网站和设备最多 500 个)。
- 所有令牌都存储在设备端令牌存储区(与 Cookie 存储区类似)。
- 如果未找到有效的 RR,则可以在发布后生成新的 RR (每 48 小时最多 2 次)。
- RR 在到期之前将被视为有效,将用作本地 缓存。
- 新的兑换调用将命中本地缓存(不会生成新的 RR)。
定义用例后,您必须仔细定义 RR 的有效期,具体如下: 这将定义您可以在 这种情况。
请务必先了解以下关键行为和变量,然后再 制定策略:
变量 / 行为 | 说明 | 潜在用量 |
---|---|---|
令牌密钥元数据 | 每个令牌可以有且只能使用一个加密密钥 在 PST 中,每个颁发者最多只能使用 6 个密钥。 | 使用此变量的一种可能方法是定义信任范围 添加到令牌中(例如,密钥 1 = 高信任度,而密钥 6 = 不信任)。 |
令牌失效日期 | 令牌失效日期与密钥失效日期相同。 | 密钥至少可以每 60 天轮替一次,使用 无效键也会被视为无效。 |
令牌兑换速率限制 | 每台设备和每个发卡机构最多只能进行两次令牌兑换 48 小时。 | 取决于您的使用所需的估算兑换次数 每 48 小时检测到一次充电盒。 |
每个顶级来源的发卡机构数量上限 | 目前,每个顶级来源的发卡机构数量上限为两个。 | 仔细定义每个页面的颁发者。 |
设备上每个颁发者的令牌数 | 目前,特定设备上每个发卡机构的令牌数量上限 500。 | 确保每个发卡机构的令牌数量少于 500 个。 在尝试提出问题时,请务必处理您网页中的错误 词元。 |
密钥承诺轮替 | 每个 PST 颁发者都必须公开具有密钥的端点 可每 60 天更改一次的承诺,并加快任何轮替的速度 则会被忽略。 | 如果您的密钥将在 60 天内过期,则必须执行此操作 请在该日期之前更新您的关键承诺,以免服务中断 (请参阅详细信息)。 |
兑换记录有效期 | 可以定义 RR 的有效期,以确定到期时间 日期。由于系统会缓存 RR,以避免不必要的新兑换调用 发布信息,这对于确保 兑换信号 | 由于兑换率限制为每 48 小时包含两个令牌, 请务必指定 RR 的有效期 至少在此时间段内成功的兑换调用次数 (RR) 有效期)。建议将此配置设置为 有效期按周数排序 |
场景示例
场景 1:RR 有效期少于 24 小时 (t=t),兑换 在 48 小时内执行了多次操作。
<ph type="x-smartling-placeholder">![PST 示例场景 1:使用寿命较短。](https://developers.google.cn/static/privacy-sandbox/protections/private-state-tokens/images/pstdevelopergu--vfxzghqns1.png?authuser=1&hl=ca)
场景 2:RR 有效期为 24 小时,并且已兑现 在 48 小时内多次出现。
<ph type="x-smartling-placeholder">![PST 示例场景 2:有效期为 24 小时。](https://developers.google.cn/static/privacy-sandbox/protections/private-state-tokens/images/pstdevelopergu--msmzxvv5hfj.png?authuser=1&hl=ca)
场景 3:RR 有效期为 48 小时,已执行兑换 在 48 小时内多次出现。
<ph type="x-smartling-placeholder">![PST 示例场景 3:有效期为 48 小时。](https://developers.google.cn/static/privacy-sandbox/protections/private-state-tokens/images/pstdevelopergu--c1w59jiklah.png?authuser=1&hl=ca)
运行演示
采用 PST 之前,我们建议您先设置演示模式。试用 PST 演示,您需要运行带有标志的 Chrome 以启用演示颁发者 关键承诺(请按照演示版中提供的说明操作) 页面)。
![PST 演示屏幕。](https://developers.google.cn/static/privacy-sandbox/protections/private-state-tokens/images/pstdevelopergu--ztx8xb2m1j.png?authuser=1&hl=ca)
运行此演示后,您的浏览器就使用了演示颁发者和兑换器 提供和消耗令牌
技术问题
如果您按照下列步骤操作,演示效果会更好:
- 请务必先停止所有 Chrome 实例,然后再运行带标志的 Chrome。
- 如果您在 Windows 机器上运行,请查看 本指南 如何将参数传递给 Chrome 可执行二进制文件。
- 打开 Applications >存储 >私密状态 令牌(使用演示应用查看已发放/兑换的令牌) 由演示发行商提供
![显示美国太平洋标准时间 (PST) 的 Chrome 开发者工具屏幕。](https://developers.google.cn/static/privacy-sandbox/protections/private-state-tokens/images/pstdevelopergu--t4a5yb69zzp.png?authuser=1&hl=ca)
为采用做好准备
成为发卡机构
发卡机构在 PST 中发挥着重要作用。它们为词元分配值,以确定 判断用户是否为聊天机器人。如果您想以发卡机构的身份开始使用 PST,您 需要完成 发卡机构注册流程。
如需申请成为发卡机构,发卡机构网站的运营商必须开立新的 GitHub 上的问题 (使用“New PST”) 颁发者”模板。按照代码库上的指南填写问题。 端点通过验证后,将合并到此代码库中 Chrome 服务器端基础架构将开始提取这些密钥。
颁发者服务器
发放者和兑换者是 PST 的主要操作者;是关键所在 适用于美国太平洋标准时间 (PST) 的工具。虽然我们已经介绍了一些有关令牌的详细信息, GitHub 文档中,我们希望 提供有关 PST 服务器的更多详情。要设为 PST 的发卡机构,您需要 首先要设置签发服务器
部署您的环境:发卡机构服务器
要实现令牌颁发者服务器,您需要构建自己的服务器端 向应用公开 HTTP 端点
发卡机构组件由两个主要模块组成:(1) 发卡机构服务器 和 (2) 令牌颁发者。
![颁发者服务器组件。](https://developers.google.cn/static/privacy-sandbox/protections/private-state-tokens/images/Issuer.png?authuser=1&hl=ca)
与所有面向 Web 的应用一样,我们建议您添加一道额外的保护屏障, 发送到发卡机构服务器
颁发者服务器:在我们的示例实现中,我们的签发服务器是 Node.js 服务器,使用 Express 框架托管 颁发者 HTTP 端点。您可以查看 GitHub 上的示例代码。
令牌颁发者:颁发者加密组件不需要任何 但考虑到该组件的性能要求, 我们以 C 语言实现为例,它使用 Boring SSL 库来管理令牌。 您可在发行商代码示例和安装详情 GitHub 上
密钥:令牌颁发者组件使用自定义 EC 密钥来加密令牌。 这些密钥必须受到保护并存储在安全存储空间中。
颁发者服务器的技术要求
根据协议,您需要在 您的发卡银行服务器:
- 密钥提交(例如
/.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"
}
});
兑换者服务器
您需要通过构建自己的令牌兑换服务来实现令牌兑换服务 服务器端应用这样你就可以读取 发送内容。以下步骤概述了如何兑换令牌以及如何 与这些令牌关联的兑换记录。
您可以选择在同一台服务器(或一组 服务器)。
<ph type="x-smartling-placeholder">![兑换器服务器组件。](https://developers.google.cn/static/privacy-sandbox/protections/private-state-tokens/images/redeemer.png?authuser=1&hl=ca)
兑换器服务器的技术要求
根据协议,您需要为 您的兑换服务器:
/.well-known/private-state-token/redemption
:端点,其中 令牌兑换。这个端点就是 将集成兑换器组件 <ph type="x-smartling-placeholder">- </ph>
- 示例代码
向兑换器服务器发送调用
要兑换令牌,您需要执行网站提取调用 您的兑换者堆栈,以便兑换之前发放的令牌。
// redemption request
await fetch("/.well-known/private-state-token/redemption", {
method: "POST",
privateToken: {
version: 1,
operation: "token-redemption",
refreshPolicy: "none"
}
});
请参阅代码示例。
兑换令牌后,您可以 另一个提取调用:
// 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,
- 您拥有并控制它 :如有必要,您可以快速停用 无需复杂的审批即可实现
- 不超过一个颁发者:限制令牌数量,以便 从而简化测试
- 兑换者不超过两位:您需要在以下位置简化问题排查流程: 出现的问题。
“权限”政策
为了正常运行,PST API 必须可供顶级网页和使用该 API 的所有子资源使用。
令牌请求操作由 private-state-token-issuance
指令控制。操作 token-redemption
和 send-redemption-record
由 private-state-token-redemption
指令控制。默认情况下,这些指令的许可名单会设为 self。这意味着该功能仅适用于顶级网页(以及同源 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,请将源列表设置为 *
。
了解如何使用“权限”政策控制 Privacy Sandbox 功能或更深入地了解权限政策。
问题排查
您可以在 Chrome 开发者工具的“Network”和“Application”标签页中检查 PST。
在“网络”标签页上:
<ph type="x-smartling-placeholder">![在开发者工具中对“Network”标签页进行检查。](https://developers.google.cn/static/privacy-sandbox/protections/private-state-tokens/images/pstdevelopergu--u49gd5id2.png?authuser=1&hl=ca)
在“Application”标签页上:
<ph type="x-smartling-placeholder">![开发者工具对“Application”标签页的检查。](https://developers.google.cn/static/privacy-sandbox/protections/private-state-tokens/images/pstdevelopergu--bl7phyzjw3o.png?authuser=1&hl=ca)
了解详情 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).
服务器最佳实践和问题排查
为了让您的发卡机构和兑换者服务器有效运行,我们建议您 实施以下最佳实践,以确保您不会遇到任何 访问、安全、日志记录或流量验证。
- 您的端点必须使用 TLS 1.3 或 1.2 采用强加密。
- 您的基础架构必须准备好应对不断变化的流量 (包括高峰)。
- 确保您的密钥受到保护且安全可靠,与您的访问权限保持一致 控制政策、关键管理策略和业务连续性计划。
- 向您的堆栈添加可观测性指标,以确保您拥有 以了解迁移后的用量、瓶颈和性能问题 进入生产阶段
更多信息
- 查看开发者文档: <ph type="x-smartling-placeholder">
- 通过 GitHub 贡献力量 问题或 W3C 调用。
- 要更好地了解某个术语,请查看 Privacy Sandbox 术语表。
- 详细了解 Chrome 概念,例如“源试用”或 “Chrome 旗帜”,请查看以下网址中提供的短视频和文章: goo.gle/cc。