关于使用 OpenID Connect 进行安全加固

OpenID Connect 概述

GitHub Actions 工作流通常被设计为访问云提供商（例如 AWS、Azure、GCP 或 HashiCorp Vault）以部署软件或使用云服务。在工作流能够访问这些资源之前，它会向云提供商提供凭据，例如密码或令牌。这些凭据通常存储为 GitHub 中的机密，并且工作流在每次运行时都会将此机密呈现给云提供商。

但是，使用硬编码的机密需要您在云提供商中创建凭据，然后在 GitHub 中将其作为机密复制。

使用 OpenID Connect (OIDC)，您可以通过配置工作流以直接从云提供商请求短期访问令牌来采用不同的方法。您的云提供商也需要在其端支持 OIDC，并且您必须配置一个信任关系来控制哪些工作流能够请求访问令牌。当前支持 OIDC 的提供商包括 Amazon Web Services、Azure、Google Cloud Platform 和 HashiCorp Vault 等。

使用 OIDC 的优势

通过更新您的工作流以使用 OIDC 令牌，您可以采用以下良好的安全实践

• 无云机密：只要您配置了云提供商上的 OIDC 信任关系，并更新了工作流以通过 OIDC 从云提供商请求短期访问令牌，就不需要将云凭据复制为长期存在的 GitHub 机密。
• 身份验证和授权管理：您可以更精细地控制工作流如何使用凭据，使用您的云提供商的身份验证 (authN) 和授权 (authZ) 工具来控制对云资源的访问。
• 轮换凭据：使用 OIDC，您的云提供商会发出一个短期访问令牌，该令牌仅对单个作业有效，然后自动过期。

OIDC 入门

下图概述了 GitHub 的 OIDC 提供商如何与您的工作流和云提供商集成

1. 在您的云提供商中，在您的云角色和需要访问云的 GitHub 工作流之间创建 OIDC 信任关系。
2. 每次您的作业运行时，GitHub 的 OIDC 提供商都会自动生成一个 OIDC 令牌。此令牌包含多个声明，以建立关于尝试进行身份验证的特定工作流的安全强化且可验证的身份。
3. 您可以在作业中包含一个步骤或操作，以从 GitHub 的 OIDC 提供商请求此令牌，并将其呈现给云提供商。
4. 一旦云提供商成功验证了令牌中提供的声明，它就会提供一个短期云访问令牌，该令牌仅在作业持续时间内可用。

配置与云的 OIDC 信任关系

当您配置云以信任 GitHub 的 OIDC 提供商时，您**必须**添加筛选传入请求的条件，以便不受信任的存储库或工作流无法请求您的云资源的访问令牌

• 在授予访问令牌之前，您的云提供商会检查subject和用于在其信任设置中设置条件的其他声明是否与请求的 JSON Web 令牌 (JWT) 中的声明匹配。因此，您必须注意正确定义云提供商中的主体和其他条件。
• OIDC 信任配置步骤以及用于设置云角色条件的语法（使用主体和其他声明）将根据您使用的云提供商而有所不同。有关一些示例，请参阅“主体声明示例”。

了解 OIDC 令牌

每个作业都会从 GitHub 的 OIDC 提供商请求一个 OIDC 令牌，该提供商会响应一个为每个生成它的工作流作业生成的唯一的 JSON Web 令牌 (JWT)。作业运行时，会将 OIDC 令牌呈现给云提供商。为了验证令牌，云提供商会检查 OIDC 令牌的主体和其他声明是否与云角色的 OIDC 信任定义中预先配置的条件匹配。

以下 OIDC 令牌示例使用一个主体 (sub)，该主体引用 octo-org/octo-repo 存储库中名为 prod 的作业环境。

{
  "typ": "JWT",
  "alg": "RS256",
  "x5t": "example-thumbprint",
  "kid": "example-key-id"
}
{
  "jti": "example-id",
  "sub": "repo:octo-org/octo-repo:environment:prod",
  "environment": "prod",
  "aud": "https://github.com/octo-org",
  "ref": "refs/heads/main",
  "sha": "example-sha",
  "repository": "octo-org/octo-repo",
  "repository_owner": "octo-org",
  "actor_id": "12",
  "repository_visibility": "private",
  "repository_id": "74",
  "repository_owner_id": "65",
  "run_id": "example-run-id",
  "run_number": "10",
  "run_attempt": "2",
  "runner_environment": "github-hosted"
  "actor": "octocat",
  "workflow": "example-workflow",
  "head_ref": "",
  "base_ref": "",
  "event_name": "workflow_dispatch",
  "ref_type": "branch",
  "job_workflow_ref": "octo-org/octo-automation/.github/workflows/oidc.yml@refs/heads/main",
  "iss": "https://token.actions.githubusercontent.com",
  "nbf": 1632492967,
  "exp": 1632493867,
  "iat": 1632493567
}

要查看 GitHub 的 OIDC 提供商支持的所有声明，请查看 https://token.actions.githubusercontent.com/.well-known/openid-configuration 中的 claims_supported 条目。

令牌包括标准的受众、发行者和主体声明。

OIDC 令牌还包括其他标准 JOSE 标头参数和声明。

令牌还包括 GitHub 提供的自定义声明。

使用 OIDC 声明定义云角色上的信任条件

使用 OIDC，GitHub Actions 工作流需要令牌才能访问云提供商中的资源。工作流会向您的云提供商请求访问令牌，后者会检查 JWT 提供的详细信息。如果 JWT 中的信任配置匹配，您的云提供商将通过向工作流发出临时令牌来响应，然后可以使用该令牌访问云提供商中的资源。您可以配置您的云提供商，使其仅响应源自特定组织存储库的请求。您还可以指定其他条件，如下所述。

在云角色/资源上设置条件以将其访问范围限定到 GitHub 工作流时，通常会将受众和主体声明结合使用。

• 受众：默认情况下，此值使用组织或存储库所有者的 URL。这可用于设置一个条件，即只有特定组织中的工作流才能访问云角色。
• 主体：默认情况下，具有预定义的格式，并且是一些关于工作流的关键元数据的串联，例如 GitHub 组织、存储库、分支或关联的job环境。请参阅“主体声明示例”，以了解如何从串联的元数据中组装主体声明。

如果您需要更细粒度的信任条件，则可以自定义 JWT 中包含的主体 (sub) 声明。有关更多信息，请参阅“自定义令牌声明”。

OIDC 令牌中还支持许多其他声明，可用于设置这些条件。此外，您的云提供商可能允许您为访问令牌分配角色，让您指定更细粒度的权限。

示例主题声明

以下示例演示了如何使用“Subject”作为条件，并解释了如何从连接的元数据中组装“Subject”。该主题使用来自job 上下文的信息，并指示您的云提供商仅对来自特定分支、环境中运行的工作流的请求授予访问令牌请求。以下部分描述了一些您可以使用的常见主题。

筛选特定环境

当作业引用环境时，主题声明包含环境名称。

您可以配置一个筛选特定环境名称的主题。在此示例中，工作流运行必须源自具有名为Production的环境的作业，该作业位于名为octo-repo的存储库中，该存储库由octo-org组织拥有

• 语法：repo:ORG-NAME/REPO-NAME:environment:ENVIRONMENT-NAME
• 示例：repo:octo-org/octo-repo:environment:Production

筛选pull_request事件

当工作流由拉取请求事件触发时，主题声明包含pull_request字符串，但前提是作业未引用环境。

您可以配置一个筛选pull_request事件的主题。在此示例中，工作流运行必须由octo-repo存储库中触发的pull_request事件触发，该存储库由octo-org组织拥有

• 语法：repo:ORG-NAME/REPO-NAME:pull_request
• 示例：repo:octo-org/octo-repo:pull_request

筛选特定分支

主题声明包含工作流的分支名称，但前提是作业未引用环境，并且工作流未由拉取请求事件触发。

您可以配置一个筛选特定分支名称的主题。在此示例中，工作流运行必须源自名为demo-branch的分支，该分支位于名为octo-repo的存储库中，该存储库由octo-org组织拥有

• 语法：repo:ORG-NAME/REPO-NAME:ref:refs/heads/BRANCH-NAME
• 示例：repo:octo-org/octo-repo:ref:refs/heads/demo-branch

筛选特定标签

主题声明包含工作流的标签名称，但前提是作业未引用环境，并且工作流未由拉取请求事件触发。

您可以创建一个筛选特定标签的主题。在此示例中，工作流运行必须源自名为demo-tag的标签，该标签位于名为octo-repo的存储库中，该存储库由octo-org组织拥有

• 语法：repo:ORG-NAME/REPO-NAME:ref:refs/tags/TAG-NAME
• 示例：repo:octo-org/octo-repo:ref:refs/tags/demo-tag

在您的云提供商中配置主题

要在您的云提供商的信任关系中配置主题，您必须将其主题字符串添加到其信任配置中。以下示例演示了各种云提供商如何以不同的方式接受相同的repo:octo-org/octo-repo:ref:refs/heads/demo-branch主题

有关更多信息，请参阅"为您的云提供商启用 OpenID Connect"中列出的指南。

更新您的操作以使用 OIDC

要更新您的自定义操作以使用 OIDC 进行身份验证，您可以使用 Actions 工具包中的getIDToken()从 GitHub 的 OIDC 提供程序请求 JWT。有关更多信息，请参阅npm 包文档中的“OIDC 令牌”。

您还可以使用curl命令请求 JWT，使用以下环境变量。

例如

curl -H "Authorization: bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" "$ACTIONS_ID_TOKEN_REQUEST_URL&audience=api://AzureADTokenExchange"

curl -H "Authorization: bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" "$ACTIONS_ID_TOKEN_REQUEST_URL&audience=api://AzureADTokenExchange"

添加权限设置

作业或工作流运行需要一个具有id-token: write的permissions设置，以允许 GitHub 的 OIDC 提供程序为每次运行创建 JSON Web 令牌。如果id-token的permissions未设置为write，则您将无法请求 OIDC JWT ID 令牌，但是此值并不意味着授予任何资源的写入访问权限，而只是能够为操作或步骤获取和设置 OIDC 令牌以启用使用短期访问令牌进行身份验证。任何实际的信任设置都是使用 OIDC 声明定义的，有关更多信息，请参阅"关于使用 OpenID Connect 加固安全性的信息"。

id-token: write设置允许使用以下方法之一从 GitHub 的 OIDC 提供程序请求 JWT

• 在运行程序上使用环境变量（ACTIONS_ID_TOKEN_REQUEST_URL和ACTIONS_ID_TOKEN_REQUEST_TOKEN）。
• 使用 Actions 工具包中的getIDToken()。

如果您需要为工作流获取 OIDC 令牌，则可以在工作流级别设置权限。例如

permissions:
  id-token: write # This is required for requesting the JWT
  contents: read  # This is required for actions/checkout

permissions:
  id-token: write # This is required for requesting the JWT
  contents: read  # This is required for actions/checkout

如果您只需要为单个作业获取 OIDC 令牌，则可以在该作业中设置此权限。例如

permissions:
  id-token: write # This is required for requesting the JWT

permissions:
  id-token: write # This is required for requesting the JWT

根据工作流的要求，您可能需要在此处指定其他权限。

对于与调用者工作流属于同一用户、组织或企业的可重用工作流，可以在调用者的上下文中访问在可重用工作流中生成的 OIDC 令牌。对于您企业或组织外部的可重用工作流，应在调用者工作流级别或调用可重用工作流的特定作业中将id-token的permissions设置显式设置为write。这确保仅在预期时才允许在调用者工作流中使用在可重用工作流中生成的 OIDC 令牌。

有关更多信息，请参阅"重用工作流"。

自定义令牌声明

您可以通过自定义 JWT 中包含的声明来加强 OIDC 配置的安全。这些自定义允许您在允许工作流访问云中托管的资源时，在云角色上定义更细粒度的信任条件

• 您可以自定义audience声明的值。请参阅"自定义audience值"。
• 您可以通过在主题（sub）声明上设置条件来自定义 OIDC 配置的格式，这些条件要求 JWT 令牌源自特定存储库、可重用工作流或其他来源。
• 您可以使用其他 OIDC 令牌声明（例如repository_id和repository_visibility）定义细粒度的 OIDC 策略。请参阅"了解 OIDC 令牌"。

自定义audience值

当您在工作流中使用自定义操作时，这些操作可能会使用 GitHub Actions 工具包，使您可以为audience声明提供自定义值。一些云提供商还在其官方登录操作中使用此功能来强制执行audience声明的默认值。例如，用于 Azure 登录的 GitHub 操作提供api://AzureADTokenExchange的默认aud值，或者允许您在工作流中设置自定义aud值。有关 GitHub Actions 工具包的更多信息，请参阅文档中的OIDC 令牌部分。

如果您不想使用操作提供的默认aud值，则可以为audience声明提供自定义值。这允许您设置一个条件，即只有特定存储库或组织中的工作流才能访问云角色。如果使用的操作支持此功能，则可以在工作流中使用with关键字将自定义aud值传递给操作。有关更多信息，请参阅"GitHub Actions 的元数据语法"。

自定义组织或存储库的主题声明

为了帮助提高安全性、合规性和标准化，您可以自定义标准声明以适合您所需的访问条件。如果您的云提供商支持主题声明的条件，则可以创建一个条件来检查sub值是否与可重用工作流的路径匹配，例如"job_workflow_ref:octo-org/octo-automation/.github/workflows/oidc.yml@refs/heads/main"。确切的格式会因云提供商的 OIDC 配置而异。要配置 GitHub 上的匹配条件，您可以使用 REST API 要求sub声明必须始终包含特定的自定义声明，例如job_workflow_ref。您可以使用 REST API 为 OIDC 主题声明应用自定义模板；例如，您可以要求 OIDC 令牌中的sub声明必须始终包含特定的自定义声明，例如job_workflow_ref。有关更多信息，请参阅"GitHub Actions OIDC 的 REST API 端点"。

自定义声明会导致整个sub声明采用新的格式，这将替换令牌中描述的默认预定义sub格式，如"关于使用 OpenID Connect 加固安全性的信息"中所述。

以下示例模板演示了自定义主题声明的各种方法。要配置 GitHub 上的这些设置，管理员可以使用 REST API 指定主题 (sub) 声明中必须包含的声明列表。

要应用此配置，请向 API 端点提交请求并在请求正文中包含所需的配置。对于组织，请参阅“GitHub Actions OIDC 的 REST API 端点”，对于存储库，请参阅“GitHub Actions OIDC 的 REST API 端点”。

要自定义主题声明，您应该首先在云提供商的 OIDC 配置中创建匹配条件，然后使用 REST API 自定义配置。完成配置后，每次新作业运行时，该作业期间生成的 OIDC 令牌都将遵循新的自定义模板。如果作业运行前云提供商的 OIDC 配置中不存在匹配条件，则云提供商可能不会接受生成的令牌，因为云条件可能未同步。

示例：根据可见性和所有者允许存储库

此示例模板允许 sub 声明使用新的格式，使用 repository_owner 和 repository_visibility。

{
   "include_claim_keys": [
       "repository_owner",
       "repository_visibility"
   ]
}

在云提供商的 OIDC 配置中，将 sub 条件配置为要求声明必须包含 repository_owner 和 repository_visibility 的特定值。例如："sub": "repository_owner:monalisa:repository_visibility:private"。此方法允许您将云角色访问权限限制到组织或企业内的仅私有存储库。

示例：允许访问所有具有特定所有者的存储库

此示例模板使 sub 声明能够使用仅包含 repository_owner 值的新格式。

要应用此配置，请向 API 端点提交请求并在请求正文中包含所需的配置。对于组织，请参阅“GitHub Actions OIDC 的 REST API 端点”，对于存储库，请参阅“GitHub Actions OIDC 的 REST API 端点”。

{
   "include_claim_keys": [
       "repository_owner"
   ]
}

在云提供商的 OIDC 配置中，将 sub 条件配置为要求声明必须包含 repository_owner 的特定值。例如："sub": "repository_owner:monalisa"

示例：需要可重用工作流

此示例模板允许 sub 声明使用包含 job_workflow_ref 声明值的新格式。这使企业能够使用 可重用工作流 来在其组织和存储库中实施一致的部署。

要应用此配置，请向 API 端点提交请求并在请求正文中包含所需的配置。对于组织，请参阅“GitHub Actions OIDC 的 REST API 端点”，对于存储库，请参阅“GitHub Actions OIDC 的 REST API 端点”。

  {
     "include_claim_keys": [
         "job_workflow_ref"
     ]
  }

在云提供商的 OIDC 配置中，将 sub 条件配置为要求声明必须包含 job_workflow_ref 的特定值。例如："sub": "job_workflow_ref:octo-org/octo-automation/.github/workflows/oidc.yml@refs/heads/main"。

示例：需要可重用工作流和其他声明

以下示例模板将特定可重用工作流的要求与其他声明结合起来。

要应用此配置，请向 API 端点提交请求并在请求正文中包含所需的配置。对于组织，请参阅“GitHub Actions OIDC 的 REST API 端点”，对于存储库，请参阅“GitHub Actions OIDC 的 REST API 端点”。

此示例还演示了如何使用 "context" 定义条件。这是 默认 sub 格式 中存储库后面的部分。例如，当作业引用环境时，上下文包含：environment:ENVIRONMENT-NAME。

{
   "include_claim_keys": [
       "repo",
       "context",
       "job_workflow_ref"
   ]
}

在云提供商的 OIDC 配置中，将 sub 条件配置为要求声明必须包含 repo、context 和 job_workflow_ref 的特定值。

此自定义模板要求 sub 使用以下格式：repo:ORG-NAME/REPO-NAME:environment:ENVIRONMENT-NAME:job_workflow_ref:REUSABLE-WORKFLOW-PATH。例如："sub": "repo:octo-org/octo-repo:environment:prod:job_workflow_ref:octo-org/octo-automation/.github/workflows/oidc.yml@refs/heads/main"

示例：授予对特定存储库的访问权限

此示例模板允许您授予云访问权限，以访问特定存储库中的所有工作流，跨所有分支/标签和环境。

要应用此配置，请向 API 端点提交请求并在请求正文中包含所需的配置。对于组织，请参阅“GitHub Actions OIDC 的 REST API 端点”，对于存储库，请参阅“GitHub Actions OIDC 的 REST API 端点”。

{
   "include_claim_keys": [
       "repo"
   ]
}

在云提供商的 OIDC 配置中，将 sub 条件配置为要求 repo 声明与所需值匹配。

示例：使用系统生成的 GUID

此示例模板使用不会在实体重命名（例如重命名存储库）之间更改的系统生成的 GUID 启用可预测的 OIDC 声明。

要应用此配置，请向 API 端点提交请求并在请求正文中包含所需的配置。对于组织，请参阅“GitHub Actions OIDC 的 REST API 端点”，对于存储库，请参阅“GitHub Actions OIDC 的 REST API 端点”。

  {
     "include_claim_keys": [
         "repository_id"
     ]
  }

在云提供商的 OIDC 配置中，将 sub 条件配置为要求 repository_id 声明与所需值匹配。

或者

{
   "include_claim_keys": [
       "repository_owner_id"
   ]
}

在云提供商的 OIDC 配置中，将 sub 条件配置为要求 repository_owner_id 声明与所需值匹配。

重置组织模板自定义项

此示例模板将主题声明重置为默认格式。此模板有效地选择退出任何组织级自定义策略。

要应用此配置，请向 API 端点提交请求并在请求正文中包含所需的配置。对于组织，请参阅“GitHub Actions OIDC 的 REST API 端点”，对于存储库，请参阅“GitHub Actions OIDC 的 REST API 端点”。

{
   "include_claim_keys": [
       "repo",
       "context"
   ]
}

在云提供商的 OIDC 配置中，将 sub 条件配置为要求声明必须包含 repo 和 context 的特定值。

重置存储库模板自定义项

组织中的所有存储库都可以选择加入或选择退出（组织和存储库级）自定义的 sub 声明模板。

要选择退出存储库并重置回默认的 sub 声明格式，存储库管理员必须使用 REST API 端点“GitHub Actions OIDC 的 REST API 端点”。

要配置存储库以使用默认的 sub 声明格式，请使用 PUT /repos/{owner}/{repo}/actions/oidc/customization/sub REST API 端点，并使用以下请求正文。

{
   "use_default": true
}

示例：配置存储库以使用组织模板

组织创建自定义的 sub 声明模板后，可以使用 REST API 以编程方式将该模板应用于组织内的存储库。存储库管理员可以配置其存储库以使用其组织管理员创建的模板。

要配置存储库以使用组织的模板，存储库管理员必须使用 PUT /repos/{owner}/{repo}/actions/oidc/customization/sub REST API 端点，并使用以下请求正文。有关更多信息，请参阅“GitHub Actions OIDC 的 REST API 端点”。

{
   "use_default": false
}

更新您的工作流以使用 OIDC

您现在可以更新 YAML 工作流以使用 OIDC 访问令牌而不是密钥。流行的云提供商已发布其官方登录操作，使您可以轻松开始使用 OIDC。有关更新工作流的更多信息，请参阅下面“为您的云提供商启用 OpenID Connect”中列出的特定于云的指南。

为 Python 包发布启用 OpenID Connect

您可以将存储库中的 GitHub Actions 工作流用作 PyPI 项目的可信发布者。使用工作流作为可信发布者允许将 OIDC 访问令牌交换为临时的 PyPI API 令牌。有关更多信息，请参阅 PyPI 文档中的“在 PyPI 中配置 OpenID Connect”和“使用可信发布者发布到 PyPI”。

为您的云提供商启用 OpenID Connect

要为您的特定云提供商启用和配置 OIDC，请参阅以下指南

• "在 Amazon Web Services 中配置 OpenID Connect"
• "在 Azure 中配置 OpenID Connect"
• "在 Google Cloud Platform 中配置 OpenID Connect"
• "在 HashiCorp Vault 中配置 OpenID Connect"

要为其他云提供商启用和配置 OIDC，请参阅以下指南

• "在云提供商中配置 OpenID Connect"

调试您的 OIDC 声明

您可以在与云提供商集成之前使用 github/actions-oidc-debugger 操作来可视化将要发送的声明。此操作请求 JWT 并打印从 GitHub Actions 收到的 JWT 中包含的声明。