Skip to content

Workload Identity Federation Cheat Sheet / 工作负载身份联合速查表

Introduction / 介绍

Use workload identity federation instead of stored, long-lived cloud credentials for continuous integration and continuous deployment (CI/CD), when both platforms support it. This cheat sheet covers OpenID Connect (OIDC) federation for deployment jobs. It removes the need to keep a reusable cloud key in the pipeline, as described in GitHub's OIDC overview. Manage secrets that cannot be replaced through the Secrets Management Cheat Sheet.

当两个平台都支持时，使用工作负载身份联合代替存储的长期云凭证进行持续集成和持续部署（CI/CD）。本速查表涵盖了部署作业的OpenID Connect（OIDC）联合。它消除了在管道中保留可重用云密钥的需要，如GitHub的OIDC概述（GitHub's OIDC overview）中所述。通过Secrets Management Cheat Sheet管理无法替换的秘密。

Federation does not make a compromised job trustworthy. Code running in an authorized job can use its identity and credentials. Keep untrusted pull request code out of jobs that can obtain production access; apply the CI/CD Security Cheat Sheet and, where applicable, the GitHub Actions Security Cheat Sheet. See GitHub's explanation of compromised runner risks.

联合并不能使受损的作业变得可信。在授权作业中运行的代码可以使用其身份和凭证。将不受信任的拉取请求代码排除在可以获取生产访问权限的作业之外；应用CI/CD Security Cheat Sheet和，如果适用，GitHub Actions Security Cheat Sheet。参见GitHub对受损运行器风险的解释。

Understand the Trust Boundary / 理解信任边界

The CI/CD platform issues a signed OIDC token describing the job. The job presents it to the cloud provider, which validates it against a configured trust policy before issuing temporary credentials. These may be access tokens or temporary access keys, depending on the provider. Use the provider's supported federation integration; do not implement a token validator in the pipeline. See the Google Cloud deployment pipeline integration.

CI/CD平台颁发一个描述作业的签名OIDC令牌。作业将其呈现给云提供商，云提供商在颁发临时凭证之前，将其与配置的信任策略进行验证。这些可能是访问令牌或临时访问密钥，具体取决于提供商。使用提供商支持的联合集成；不要在管道中实现令牌验证器。参见Google Cloud部署管道集成。

Validating a token against the configured trusted issuer does not by itself authorize production access. Configure both controls:

验证令牌是否与配置的受信任发行者一致本身并不授权生产访问。配置以下两种控制：

  • Trust policy: which external workloads may obtain credentials.
    中文：信任策略：哪些外部工作负载可以获取凭证。
  • Permissions policy: which resources and operations those credentials authorize. A tightly scoped trust policy does not compensate for an administrative deployment role. AWS distinguishes the role's trust and permissions policies.
    中文：权限策略：这些凭证授权哪些资源和操作。严格的信任策略不能弥补管理部署角色的不足。AWS区分角色的信任和权限策略。

Restrict Which Jobs Are Trusted / 限制受信任作业的范围

  • Configure the exact trusted issuer (iss), expected audience (aud), and allowed subject (sub) or equivalent workload attributes. The provider must validate the signature and token validity period as well as these restrictions. Use the actual claims issued for your job and the provider's documented matching rules; for example, Microsoft Entra requires matching issuer, subject, and audience values.
    中文：配置确切的受信任发行者(iss)、预期的受众(aud)和允许的主题(sub)或等效的工作负载属性。提供者必须验证签名和令牌有效期以及这些限制。使用为您的作业签发的实际声明和提供者的文档化匹配规则；例如，Microsoft Entra要求匹配发行者、主题和受众值。
  • Restrict access to the intended organization, repository or project, and deployment context. Trusting a shared CI/CD issuer alone can admit other tenants. Prefer immutable, non-reusable organization and repository identifiers where supported, rather than names that another owner could acquire. Google Cloud documents these tenant restrictions and identifier risks.
    中文：限制对目标组织、存储库或项目以及部署上下文的访问。仅信任共享CI/CD发行者可能会允许其他租户。在支持的情况下，优先使用不可变、不可重复的组织和存储库标识符，而不是其他所有者可能获得的名称。Google Cloud记录了这些租户限制和标识符风险。
  • Allow only the required branches, environments, or workflows. Avoid wildcards that admit every repository or every job context. Verify which claims the cloud provider can actually enforce; a claim's presence in a token does not mean it is available as a policy condition. Follow the provider's integration documentation, such as GitHub's AWS OIDC configuration guidance.
    中文：仅允许所需的分支、环境或工作流程。避免允许每个存储库或每个作业上下文的通配符。验证云提供商实际上可以强制执行的声明；声明在令牌中的存在并不意味着它可用作策略条件。遵循提供者的集成文档，例如GitHub的AWS OIDC配置指南。
  • Require reviews for changes to trusted deployment workflow files; see the GitHub Actions repository hardening guidance.
    中文：要求对受信任的部署工作流程文件的更改进行审查；参见GitHub Actions 安全加固指南。
  • When trusting a deployment environment, protect who can use it and which branches or tags may deploy to it. For GitHub Actions, the default environment-based subject does not also contain the branch. Match the subject format configured for your repository and enforce the branch restriction through environment protection or another supported condition. See the GitHub OIDC subject reference.
    中文：在信任部署环境时，保护谁可以使用它以及哪些分支或标签可以部署到它。对于GitHub Actions，默认的环境主题不包含分支。匹配为您的存储库配置的主题格式，并通过环境保护或其他支持的条件强制执行分支限制。参见GitHub OIDC主题参考。

Limit Credential Exposure and Permissions / 限制凭证暴露和权限

  • Grant only the cloud operations and resources the deployment needs. Use separate identities and trust rules for production and non-production. Keep federation configuration and permission administration outside ordinary deployment roles to prevent a compromised job from widening its own access. See Google Cloud's federation security practices.
    中文：仅授予部署所需的云操作和资源。为生产环境和非生产环境使用单独的身份和信任规则。将联盟配置和权限管理保持在普通部署角色之外，以防止受损害的作业扩大其访问权限。参见Google Cloud的联盟安全实践。
  • Enable OIDC token requests only for jobs that need cloud access. In GitHub Actions, set id-token: write at the job level; it permits token requests and does not itself grant cloud permissions. See GitHub's OIDC permission requirements.
    中文：仅对需要云访问的作业启用OIDC令牌请求。在GitHub Actions中，在作业级别设置id-token: write；它允许令牌请求，但本身并不授予云权限。参见GitHub的OIDC权限要求。
  • Request the shortest credential lifetime the provider supports that meets the job's needs. Do not assume credentials expire when the job ends or when its OIDC token expires: issued cloud credentials have their own lifetime. For example, AWS temporary credentials remain valid until expiry unless their access is disabled.
    中文：请求提供者支持的符合工作需求的最短凭证有效期。不要假设凭证在作业结束时或其OIDC令牌过期时失效：已发行的云凭证有其自己的有效期。例如，AWS临时凭证在到期前保持有效，除非其访问被禁用。
  • Treat both the OIDC token and issued credentials as secrets: do not print them, place them in artifacts or caches, or pass them to unrelated jobs. After verifying migration, revoke the replaced static keys and remove pipeline copies so they cannot bypass the federation restrictions. Apply the Secrets Management lifecycle guidance.
    中文：将OIDC令牌和颁发的凭证都视为机密信息：不要打印它们，不要将它们放置在工件或缓存中，也不要将它们传递给无关的工作。在验证迁移后，撤销替换的静态密钥并删除管道副本，以便它们无法绕过联合限制。应用Secrets Management 生命周期指南。

Verify and Monitor Access / 验证和监控访问

Before production use, test the permitted deployment and verify that unauthorized repositories, branches, and job contexts cannot obtain production credentials. Confirm that the authorized job cannot access resources outside its assigned permissions. Repeat these checks after changes to trust policies, claim formats, or workflow configuration. Use the platform's documented claims, such as the GitHub OIDC reference, to select relevant cases.

在生产使用之前，测试允许的部署并验证未经授权的仓库、分支和工作上下文无法获取生产凭证。确认授权的工作无法访问其分配权限之外的资源。在更改信任策略、声明格式或工作流程配置后，重复这些检查。使用平台记录的声明，例如GitHub OIDC 参考，来选择相关案例。

Enable cloud audit events for token exchange and role or service account use. Check which identity fields are recorded and correlate them with CI/CD run records; complete workflow attribution is not automatic. For example, Google Cloud requires enabling relevant data access logs and choosing an unambiguous subject mapping. Alert on unexpected identities and changes to federation trust or permissions.

启用云审计事件以记录令牌交换和角色或服务账户的使用。检查记录的身份字段并将它们与CI/CD运行记录相关联；工作流程归因不是自动完成的。例如，Google Cloud 要求启用相关数据访问日志并选择一个明确的主题映射。对意外的身份和联合信任或权限的更改发出警报。

Prepare to stop new credential issuance and restrict already-issued credentials if a job is compromised. Removing a trust relationship alone is not a guarantee that existing sessions stop working. Follow the provider's incident procedure, such as revoking AWS role session permissions, and account for policy propagation delays.

准备停止新的凭证颁发并限制已颁发的凭证，如果工作受到损害。仅删除信任关系并不能保证现有会话停止工作。遵循提供商的事故处理程序，例如撤销AWS角色会话权限，并考虑策略传播延迟。

References / 参考