第17章 可信发布:内部机制与技术细节
第17章:内部机制与技术细节
注意 此页面对可信发布(Trusted Publishing)的普通使用者没有太大用处! 它主要面向 PyPI 开发人员,以及其他希望支持类似认证模型的软件包索引开发人员。
可信发布的工作原理 PyPI 的可信发布功能构建于 OpenID Connect(简称 OIDC)之上。 OIDC 为服务(如 GitHub Actions)提供了一种可验证自身身份的方法:授权实体(如 GitHub 用户或自动化工作流)可以向第三方服务出示 OIDC Token。该第三方服务随后可以验证 Token,并判断其是否被授权执行某些其他操作。 在可信发布的场景中,具体机制如下:
* 像 GitHub 这样的 OIDC 身份提供方(简称“提供方”)会生成包含限定范围声明(Scoped Claims)的 OIDC Token,这些声明传达了相应的授权范围。 例如,`repo` 声明可能绑定为 `octo-org/example`,表示该 Token 应被授权访问 `octo-org/example` 作为有效存储库的资源。 * 可信发布者是 PyPI 上的配置项,用于告知 PyPI 应信任哪些 OIDC 提供方,以及在何种情况下信任(即哪些具体的声明集被视为有效)。 例如,针对 GitHub Actions 的可信发布者配置可能指定 `repo: octo-org/example`、`workflow: release.yml` 和 `environment: pypi`,这意味着出示的 OIDC Token 必须精确包含这些声明才被视为有效。 * 在适用情况下,PyPI 还会检查防止账户复活攻击的声明。例如,当使用 GitHub 作为 OIDC 身份提供方时,PyPI 会检查 `repository_owner_id` 声明。 * Token 交换是 PyPI 将 OIDC Token 转换为可用于对软件包上传端点进行认证的凭据(PyPI API Token)的过程。
Token 交换本质上是一个匹配过程,即将出示的 OIDC Token 与 PyPI 上当前配置的所有可信发布者进行匹配:首先验证 Token 的签名(以确保其确实来自预期的提供方),然后将其声明与注册了可信发布者的一个或多个项目进行匹配。
如果 OIDC Token 对应一个或多个可信发布者,则会生成一个短生命周期的(15 分钟)PyPI API Token。该 API Token 的作用范围涵盖所有匹配的可信发布者对应的项目,这意味着它可以用于向多个项目上传软件包(如果这样配置的话)。
如果一切顺利进行,成功的可信发布流程将生成一个短生命周期的 PyPI API Token,且无需任何用户交互,这为 PyPI 打包者带来了安全性和易用性的好处:用户不再需要担心 Token 的发放或吊销。
问答 为什么可信发布使用“两阶段” Token 交换? 如上所述,可信发布使用“Token 交换”机制,该过程分为两个阶段: 1. 上传客户端出示 OIDC Token,PyPI 对其进行验证。如果有效,PyPI 将返回一个有效且作用范围适当的 PyPI API Token。 2. 上传客户端使用获得的这个有效 PyPI API Token,并按常规方式使用它。
原则上,这比必要的复杂度更高:PyPI 本可以直接接收 OIDC Token,并在处理 API Token 时将其视为特殊情况,从而跳过上传客户端与软件包索引之间的网络往返。 虽然概念上更简单,但“单阶段” Token 交换也存在自身的问题:
* 关注点隔离:概念上,OIDC Token 是外部签发的 Token,涉及外部关切:它有并非 PyPI 内部特有的失效模式(例如,签发身份提供方签名失败)。 将这些关切与 PyPI 的实际业务逻辑隔离开来,可以确保它们保持封装,且不将设计或安全约束强加给 PyPI 本身(例如,强制 PyPI 在不适用的地方使用 OIDC Token)。 * 对现有认证和授权逻辑的复杂性:PyPI 拥有大量现成的认证(AuthN)和授权(AuthZ)代码。大多数现有的 API Token 代码都直接适配了基于 Macaroons 的 PyPI API Token 格式。 处理 OIDC Token(底层是 JSON Web Token)将需要大量复制现有的代码路径,这意味着更大的测试(和漏洞)表面。通过用 PyPI 现有格式的 API Token 交换 OIDC Token,我们的实现可以重用现有(且经过充分测试的)代码路径,而无需任何重大修改。 * 自动密钥扫描和吊销的挑战:PyPI 是 GitHub 密钥扫描系统的合作伙伴,该系统允许 PyPI 自动吊销意外泄露在公共存储库中的 PyPI API Token。 该系统依赖于 PyPI Token 具有唯一的前缀:它们都以 `pypi-` 开头。如果没有这个前缀,GitHub 将无法高效地扫描公共存储库中的 Token。 OIDC Token 由独立的提供方签发,这意味着 PyPI 无法在它们上强制施加 `pypi-` 前缀。此外,OIDC Token 严格定义为 JSON Web Token,表现为基本上是非结构化的随机字符。这使得它们难以被扫描。最后,即使有效的 JWT 扫描器也需要将每个泄露的 JWT 报告给其签发者(例如 GitHub 本身)和消费者(例如 PyPI),这在吊销过程中引入了复杂性和额外的失效模式。 将 OIDC Token 交换为 PyPI API Token 完全规避了所有这些问题的。
尽管这些原因已在 PyPI 文档中记录,但它们很可能也是其他“联合”OIDC 消费者(如云服务商)执行类似“两阶段”交换机制的原因。
为什么 PyPI 项目与发布者的关系是“多对多”? 如果你在 PyPI 上尝试可信发布,你会发现 PyPI 项目可以有多个发布者,而单个发布者可以注册到多个项目。 这是 PyPI 项目与其可信发布者之间的“多对多”关系,与“两阶段”交换一样,原则上似乎比必要的更复杂。 实际上,这种多对多关系解决了 Python 打包社区常用的发布模式:
* 一个发布者,多个项目:几个相关的 PyPI 项目共享单个源代码存储库并不罕见。此外,由于联合发布(例如,库软件包及其对应的 CLI 工具同时发布),几个相关的 PyPI 项目共享相同的发布工作流也不罕见。 可信发布的设计适应了这种使用场景:维护者可以为所有软件包使用相同的 `release.yml` 工作流,而无需按软件包拆分工作流。 * 一个项目,多个发布者:PyPI 包含大量预构建分发包(“wheels”),其中一些是“二进制 wheels”,包含特定于处理器、操作系统或平台的二进制文件。 由于这些二进制文件特定于各个平台,它们通常必须分别在不同的平台上构建,通常使用每个平台的专用构建器配置。 从那里开始,让每个独立的平台构建器也执行该平台的发布是常见的:Linux 特定的 wheels 由 Linux 构建器上传,等等。 就可靠性和关注点隔离而言,这可以说不是最佳实践:最佳实践是在最终的、不依赖平台的发布步骤中收集所有特定平台的构建,然后可以是一个单一的发布者。 然而,为了让可信发布者能够到达用户手中,而不要求他们对构建进行重大且不相关的更改,可信发布功能允许用户将多个发布者注册到单个项目。因此,`sampleproject` 可以从 `release-linux.yml` 和 `release-macos.yml` 发布,而无需重构为单一的 `release.yml`。
什么是账户复活攻击,PyPI 如何防止它? 一些 OIDC 提供方支持更改用户名,因此 `repository_owner: octo-org` 的声明不一定指用户在可信发布者配置中最初授权的同一个 `octo-org`。 如果存储库所有者更改其用户名或删除其账户,恶意行为者可能能够获取被释放的用户名,并在原始可信名称下创建自己的存储库。这就是所谓的账户复活攻击。 为了解决基于 GitHub 的发布者的这个问题,PyPI 始终检查 `repository_owner_id` 声明。该声明证明了存储库所有者的 ID,与用户名不同,它是稳定且永久的。当配置可信发布者时,PyPI 会查找配置的用户名的 ID 并将其存储。在生成 API Token 期间,PyPI 会将 `repository_owner_id` 声明与存储的 ID 进行比对,如果不匹配则失败。通过此过程,即使原始 GitHub 用户更改其用户名或删除其账户,也只有该原始用户被授权向其 PyPI 项目发布。
我如何成为可信发布提供方? 如果你是托管计算服务的运营商或 CI 提供方,你可能希望 PyPI 支持你的平台或服务作为可信发布者。 向 PyPI 添加新的可信发布者平台有三个主要要求:
1. OIDC 身份提供方:可信发布依赖于特定平台使用 OpenID Connect 规范运行身份提供方。其他形式的身份提供方不具备资格。 2. OIDC 发现:你的 OIDC 身份提供方必须支持 OpenID Connect 发现,即提供包含至少以下内容的 `https://{iss}/.well-known/openid-configuration` 端点: * `jwks_uri`:身份提供方用于签名的 JSON Web Key (JWK) 集的 URL; * `claims_supported`:PyPI 应预期在身份提供方签发的 OIDC 凭据中看到的声明名称数组。 (其中 `iss` 是提供的 OIDC Token 中 `iss` 声明的值) 无法提供发现或发现响应中这些字段的身份提供方不具备资格。 3. 合理的 OIDC 声明集:你的 OIDC 声明必须足以识别一个唯一的负载,该负载可以限定于一个 PyPI 项目或一组项目。这些声明必须支持防止复活攻击,这意味着可重用或可变的声明(如存储库或项目名称)必须由不可变且保证唯一的标识符(如数字 ID)作为后盾。此外,声明集必须支持可定制的 `aud` 声明,该声明可以设置为 `pypi` 的值。不符合此声明标准的身份提供方不具备资格。 4. 可靠性与知名度:与新的可信发布者集成的工作量并不是异常的,但也不是微不足道的。为了最好地利用 PyPI 有限的资源,我们只计划支持在 PyPI 用户中具有合理使用量的平台。此外,我们对受支持的身份提供方的整体可靠性和安全性有着很高的标准:实际上,这意味着自建的或仅供个人使用的身份提供方不具备资格。
如果你认为你的平台充分满足了这些要求,我们鼓励你提交一个问题(issue),请求为你的平台或服务提供可信发布者支持。