进阶 docs.pypi.org 2026-10-20 06:39:13 · 17 阅读

第11章 开始使用可信发布

使用可信发布方上传至 PyPI

“可信发布”(Trusted Publishing)指利用 OpenID Connect(OIDC)标准在受信任的第三方服务与 PyPI 之间交换短时效身份令牌。此方法适用于自动化环境,免去在发布时手动生成 API 令牌进行身份验证的步骤。

快速入门,请参阅:

  • 为现有 PyPI 项目添加可信发布方
  • 创建带有可信发布方的 PyPI 项目

背景速览:使用 OpenID Connect 发布

OpenID Connect(OIDC)发布是向 PyPI 上传包的机制,与 API 令牌互为补充。

使用 PyPI 的 OIDC 发布无需深入了解 OIDC,以下是简略说明:

  • 某些 CI 服务(如 GitHub Actions)属于 OIDC 身份提供商,能够签发短时效凭证(“OIDC 令牌”)。第三方可以严格验证这些令牌确实源自该 CI 服务,并确认实际执行操作的用户、仓库等信息。
  • PyPI 上的项目可配置信任特定 CI 服务的某项配置,从而使该配置成为该项目的 OIDC 发布方。
  • 发布自动化流程(如 GitHub Actions)可将 OIDC 令牌提交给 PyPI。该令牌会与各项目信任的配置进行匹配;若某项目信任该令牌对应的配置,PyPI 将为该项目生成一个短时效 API 令牌并返回。
  • 该短时效 API 令牌的行为与普通的项目级 API 令牌完全一致,区别仅在于它自创建起 15 分钟内有效(足以让 CI 完成包上传)。

与 PyPI 的传统身份验证方式相比,这带来了显著易用性与安全性提升:

易用性:采用可信发布后,用户无需再手动在 PyPI 创建 API 令牌并粘贴到 CI 提供商中。唯一的手动步骤是在 PyPI 上配置发布方。

安全性:PyPI 的常规 API 令牌有效期较长,一旦攻击者获取了某个包的发布令牌,便可使用直至合法用户发现并手动吊销。可信发布通过令牌的自动过期机制解决了这一问题。

评论 (0)