GitHub Actions OIDC:如何在无需长期密钥的情况下保护您的部署
了解如何通过 OIDC 增强 GitHub Actions 的部署安全性。用短期令牌替换长期云凭据,使用 IAM 信任策略限制访问,并保护您的 CI/CD 管道。
GitHub Actions OIDC:如何在不使用长期密钥的情况下保护您的部署
从 GitHub Actions 部署应用程序通常需要访问外部基础设施。工作流可能会将文件上传到 Amazon S3、发布容器或更新云资源。传统上,团队会将云访问密钥存储在 GitHub Secrets 中。这行得通,但如果工作流、依赖项或日志泄露了长期凭据,攻击者仍可利用它。
OpenID Connect (OIDC) 通过将长期云凭据替换为仅授予给授权工作流身份的临时访问权限,有助于加强 CI/CD 安全性。 它减少了凭据暴露,限制了未经授权的访问,并支持更严格控制的生产部署。
本教程解释安全优势,展示实用的 AWS 配置,并说明您仍需要哪些防护。OIDC 不是一键式安全开关:信任策略、角色权限和工作流控制与令牌交换同样重要。
部署安全为何重要
CI/CD 管道是特权自动化。它们可能替换生产代码、上传资产、读取部署配置或修改基础设施。因此,被攻破的管道可能比被攻破的开发者工作站造成更大影响。
以下三种常见风险值得特别关注:
- 凭据暴露: 从构建环境中窃取的静态云密钥在被吊销前可能一直有效。
- 过度权限: 具有管理员权限的部署凭据可能影响无关服务。
- 未经授权的部署: 如果身份检查过于宽松,不受信任的分支或工作流可能获得生产访问权限。
OIDC 通过将身份验证与短期且可验证的工作流身份绑定,解决了部分问题。它不能取代最小权限 IAM、代码审查或环境保护。
GitHub Actions 中的 OIDC 是什么?
OpenID Connect 是构建在 OAuth 2.0 之上的身份层。GitHub Actions 可以从 GitHub 的 OIDC 提供程序请求签名的 JSON Web 令牌 (JWT):
https://token.actions.githubusercontent.com
该令牌包含描述作业身份和执行上下文的声明。云身份服务会验证令牌的签名、签发者、受众和相关声明,然后决定是否颁发临时凭据。
外部服务必须明确信任预期的 GitHub 工作流身份。仅在 YAML 文件中启用 OIDC 并不会授予访问权限。
请参阅 GitHub 的 OIDC 文档。
静态凭据与 OIDC:安全性比较
| 安全考量 | 长期访问密钥 | OIDC 联合身份 |
|---|---|---|
| GitHub 中的永久云凭据 | 通常需要 | 支持的提供程序不需要 |
| 凭据生命周期 | 直到过期或吊销 | 临时会话 |
| 轮换责任 | 团队必须管理密钥生命周期 | 云提供程序颁发短期凭据 |
| 身份限制 | 取决于凭据存储和 IAM | 信任策略可以限制工作流身份 |
| 授权 | IAM 权限 | 仍需要 IAM 权限 |
| 剩余风险 | 静态密钥被盗和重复使用 | 授权工作流被攻破或信任过宽 |
OIDC 降低了凭据被盗的风险和影响;它不会消除每个密钥。应用程序可能仍需要数据库密码、签名密钥或第三方 API 令牌。
OIDC 身份验证流程如何工作
- 授权的 GitHub Actions 作业请求身份令牌。
- GitHub 为该作业颁发签名的 JWT。
- 工作流将令牌提交给云身份服务。
- 云提供程序验证令牌并评估其配置的信任条件。
- 如果允许该身份,提供程序会颁发临时凭据。
- 工作流在角色允许的范围内使用这些凭据。
云提供程序必须拒绝主题、受众或其他必需条件不匹配的令牌。这种验证是安全部署与过度信任部署之间的界限。
步骤 1:在 AWS 中配置 GitHub 的 OIDC 提供程序
AWS IAM 支持 OpenID Connect 身份提供程序。使用以下内容创建身份提供程序:
| 设置 | 值 |
|---|---|
| 提供程序 URL | https://token.actions.githubusercontent.com |
| 受众 | sts.amazonaws.com |
| 提供程序类型 | OpenID Connect |
受众标识令牌的预期接收者。AWS 凭据操作通常使用 sts.amazonaws.com。
请参阅 AWS IAM OIDC 角色配置。
步骤 2:限制谁可以担任部署角色
创建一个 IAM 角色,其信任策略仅允许来自 GitHub 身份提供程序和预期工作流身份的 sts:AssumeRoleWithWebIdentity。
以下示例使用 GitHub 的传统基于分支的主题格式:
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Federated": "arn:aws:iam::123456789012:oidc-provider/token.actions.githubusercontent.com"
},
"Action": "sts:AssumeRoleWithWebIdentity",
"Condition": {
"StringEquals": {
"token.actions.githubusercontent.com:aud": "sts.amazonaws.com",
"token.actions.githubusercontent.com:sub": "repo:example-org/example-app:ref:refs/heads/main"
}
}
}
]
}
替换 AWS 账户号、组织和仓库。
不要盲目复制主题条件。 GitHub 为 2026 年 7 月 15 日之后创建的仓库引入了不可更改的默认主题格式。检查您的仓库实际使用的主题格式,并配置 AWS 以匹配它。基于环境的工作流也可能使用不同的主题形状。请参阅 GitHub 的 OIDC 令牌参考。
限制性信任策略是防止未经授权的工作流获得生产凭据的最重要方法之一。避免使用可能意外授权无关仓库或上下文的通配符主题。
步骤 3:限制角色可以执行的操作
信任决定谁可以担任角色。IAM 权限决定身份验证后角色可以执行什么。
对于仅将文件上传到单个 S3 存储桶的部署,简化策略如下:
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": ["s3:PutObject"],
"Resource": "arn:aws:s3:::example-deploy-bucket/*"
}
]
}

此示例允许对象上传,而不允许账户管理或存储桶删除。如果您的部署还会删除过时文件或列出存储桶内容,请仅授予所需的额外操作,例如受限的 s3:DeleteObject 或 s3:ListBucket。
切勿仅为了让部署运行而授予 AdministratorAccess。具有过度权限的临时凭据仍可能造成严重损害。
步骤 4:从工作流请求临时凭据
部署作业必须获准请求 OIDC 令牌。以下示例将预构建的 dist/ 目录上传到 S3:
name: Deploy website
on:
push:
branches:
- main
permissions:
contents: read
jobs:
deploy:
runs-on: ubuntu-latest
permissions:
contents: read
id-token: write
steps:
- name: Checkout repository
uses: actions/checkout@v4
- name: Configure AWS credentials
uses: aws-actions/configure-aws-credentials@v4
with:
role-to-assume: arn:aws:iam::123456789012:role/github-deploy-role
aws-region: eu-west-1
- name: Deploy website
run: |
aws s3 cp ./dist/ s3://example-deploy-bucket/ --recursive
该示例使用主版本操作引用以提高可读性。在生产环境中,请查看当前受支持的版本,并最好将第三方操作固定到完整的提交 SHA。该示例假设网站已构建到 dist/。
请注意缺少的内容:工作流中未存储永久 AWS 访问密钥或秘密访问密钥。
官方 AWS 凭据操作 将 OIDC 令牌交换为临时 AWS 凭据。
步骤 5:了解 id-token: write
此权限:
permissions:
id-token: write
允许作业请求 GitHub OIDC 身份令牌。它本身并不授予作业写入 GitHub 仓库或访问 AWS 的权限。
云提供程序仍决定是否信任该身份,IAM 角色仍控制允许哪些操作。
仅向实际对云进行身份验证的作业授予 id-token: write。构建、lint 和测试作业通常不需要它。
步骤 6:保护生产环境
OIDC 无法补偿运行恶意代码的授权工作流。如果攻击者可以更改受信任的部署工作流或在该上下文中执行未经审查的代码,他们可能能够获得临时凭据。
GitHub 环境可以添加部署分支限制和必需审查者等控制,具体取决于仓库设置和计划可用性。
jobs:
deploy:
runs-on: ubuntu-latest
environment: production
permissions:
contents: read
id-token: write
当工作流使用环境时,OIDC 主题可能标识该环境而不是分支。更新 IAM 信任策略以匹配实际声明并保护环境本身。
对于生产环境,请将受限身份与分支保护、代码审查、受限工作流权限和环境审批规则(在适当情况下)相结合。这就是 OIDC 成为更强部署安全态势的一部分,而不仅仅是凭据替代品的方式。
步骤 7:验证担任的身份并测试拒绝情况
配置 AWS 身份验证后,添加诊断步骤:
- name: Verify AWS identity
run: aws sts get-caller-identity
检查响应是否标识预期的 AWS 账户和部署角色。该命令不会泄露秘密访问密钥。
还要测试未经授权的分支、仓库或环境无法担任生产角色。未经授权的部署失败即为一次成功的安全测试。
调试时不要记录原始 OIDC 令牌或临时凭据。
常见的 OIDC 安全和配置错误
缺少 id-token: write
除非作业拥有该权限,否则无法请求 OIDC 令牌。作业级权限可能会覆盖工作流级权限。

AWS 为角色担任返回 AccessDenied
检查身份提供程序、受众、角色 ARN 和主题条件。特别是,验证实际的 GitHub 主题格式,而不是假设每个仓库都使用相同的默认值。
身份验证成功,但上传失败
信任关系可能正确,但角色缺少所需的 S3 权限。修复作用域受限的 IAM 权限策略,而不是扩大身份信任。
生产访问来自过多上下文
通配符主题或环境限制不足可能会使生产凭据可供不应接收的工作流使用。限制信任策略并测试未经授权的情况。
拉取请求无法部署
拉取请求可能有不同的声明和不可信的代码。不要仅为了让拉取请求担任部署角色而削弱生产信任条件。将验证与生产部署分开运行。
可以将 OIDC 与 Azure 或 Google Cloud 配合使用吗?
是的。联合机制类似,但身份配置不同。
| 云 | 联合机制 | GitHub 操作 |
|---|---|---|
| AWS | IAM OIDC 提供程序和角色 | aws-actions/configure-aws-credentials |
| Microsoft Azure | 联合身份凭据 | azure/login |
| Google Cloud | 工作负载标识联合 | google-github-actions/auth |
Azure 通常将联合凭据与应用程序或托管标识关联。Google Cloud 使用工作负载标识池和提供程序,具体取决于设置,可直接访问资源或模拟服务帐户。
每个平台都有自己的受众、主题匹配和授权规则。在复制示例之前,请查看提供程序的当前官方文档。
传统托管上的 PHP 网站呢?
并非每个 Web 主机都接受 GitHub OIDC 身份。共享托管和托管 PHP 托管可能仍使用 SSH 密钥、SFTP 凭据、部署 Webhook 或提供程序 API 令牌。
在 GitHub Actions 中启用 OIDC 不会自动替换 SSH 密钥,如果目标服务器没有联合机制。
在 OIDC 不可用时,请使用专用部署帐户、作用域受限的权限、受保护的密钥和凭据轮换。在可能的情况下限制文件系统和命令访问。
无论是否支持 OIDC,安全目标都是最小权限和有限的凭据暴露。
部署安全检查清单
在部署到生产环境之前,请验证:
- OIDC 签发者和受众已正确配置。
- 信任策略仅匹配预期的仓库和部署上下文。
- 主题条件反映您的仓库的实际 GitHub 令牌格式。
- IAM 角色仅拥有部署所需的权限。
- 仅部署作业接收
id-token: write。 - 生产分支和环境具有适当的保护。
- 第三方操作已审查,并最好固定到不可更改的提交 SHA。
- 不可信的拉取请求无法担任生产角色。
- 未经授权的分支和仓库身份验证失败。
- 令牌和临时凭据从不被不必要地记录或存储。
常见问题解答
OIDC 是否比静态 AWS 访问密钥更安全?
它降低了长期凭据被盗的风险。强信任策略、受限权限和受保护的工作流仍然必不可少。
OIDC 是否消除了 GitHub Secrets?
它替换了一些云身份验证凭据,而不是每个应用程序密钥或 API 密钥。
id-token: write 授予什么?
它允许工作流请求身份令牌。云权限由提供程序单独确定。
不可信的拉取请求能否使用生产 OIDC 凭据?
不应该。配置限制性信任条件,并将生产部署与不可信代码分开。
OIDC 是否适用于任何托管提供程序?
不。目标服务或身份代理必须支持并信任 GitHub 的 OIDC 令牌。
结论:加强安全性,而不仅仅是身份验证
GitHub Actions OIDC 是受支持云服务提升部署安全性的有效方法。它消除了在 GitHub 中保留永久云密钥的需求,支持短期访问,并允许云信任策略限制哪些工作流可以部署。
但最强的设计将 OIDC 与最小权限 IAM、受保护环境、经审查的工作流代码以及明确测试未经授权身份是否被拒绝相结合。
目标不仅仅是替换一个密钥。而是要确保只有正确的工作流才能访问正确的资源,并拥有最小权限和最短的实际时间。