OpenID Connect

OpenID Connect (OIDC) 概述

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

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

与支持 OIDC 的云提供商建立信任连接后，可以将工作流配置为直接从云提供商请求短期访问令牌。

使用 OIDC 的好处

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

          **无云机密：** 你无需将云凭据复制为长期存在的 GitHub 机密。 相反，您可以在云提供商上配置 OIDC 信任，然后更新您的工作流程，通过 OIDC 向云提供商请求短期访问令牌。

        **身份验证和授权管理：** 可以更精细地控制工作流使用凭据的方式，使用云提供商的身份验证 (authN) 和授权 (authZ) 工具来控制对云资源的访问。

        **轮换凭据：** 借助 OIDC，云提供商会颁发一个仅对单个作业有效的短期访问令牌，然后自动过期。

OIDC 如何集成与 GitHub Actions

下图概述了 GitHub 的 OIDC 提供程序如何与你的工作流和云提供程序集成：

显示云提供商如何通过访问令牌和 JSON Web 令牌云角色 ID 与 GitHub Actions 集成的示意图。

在云提供商中建立 OIDC 信任关系，允许特定 GitHub 工作流代表定义的云角色请求云访问令牌。
每次作业运行时， GitHub的 OIDC 提供程序都会自动生成一个 OIDC 令牌。此令牌包含多个声明，用于建立有关尝试进行身份验证的特定工作流程的经安全强化且可验证的身份。
工作流作业中的步骤或操作可从 GitHub 的 OIDC 提供程序请求令牌，然后可将该令牌提交给云提供程序，作为工作流身份的证明。
云提供商成功验证令牌中提供的声明后，将提供仅在作业期间可用的短期云访问令牌。

了解 OIDC 令牌

每个作业都从 GitHubOIDC 提供程序请求一个 OIDC 令牌，该令牌使用自动生成的 JSON Web 令牌（JWT）进行响应，该令牌对于生成的每个工作流作业都是唯一的。当作业运行时，OIDC 令牌将呈现给云提供商。要验证令牌，云提供商会检查 OIDC 令牌的主题和其他声明是否与云角色的 OIDC 信任定义上预配置的条件匹配。

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

{
  "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",
  "repo_property_workspace_id": "ws-abc123",
  "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
}

使用 OIDC 对自定义操作进行身份验证

自定义操作通过 Actions 工具包中的 getIDToken() 方法或 curl 命令使用 OIDC 进行身份验证。

有关详细信息，请参阅“OpenID Connect 参考”。

更新 OIDC 的工作流程

          GitHub Actions 工作流可以使用 OIDC 令牌而不是机密向云提供商进行身份验证。 许多主流云提供商都提供官方登录操作，可简化在工作流中使用 OIDC 的流程。 有关针对特定云提供商更新工作流的详细信息，请参阅 [AUTOTITLE](/actions/how-tos/security-for-github-actions/security-hardening-your-deployments)。

将存储库自定义属性用作 OIDC 声明

组织和企业管理员可以将存储库自定义属性作为声明包含在 OIDC 令牌中。这将在云提供程序、项目注册表或机密管理器中启用基于属性的访问控制（ABAC）策略，这些策略由存储库元数据驱动，而不是硬编码的允许列表。

自定义属性声明的工作原理

使用自定义属性作为 OIDC 声明的端到端流程如下：

       **定义自定义属性。** 组织或企业管理员创建自定义属性（例如，`business_unit`或`data_classification``environment_tier`）并将值分配给存储库。 有关详细信息，请参阅 [AUTOTITLE](/organizations/managing-organization-settings/managing-custom-properties-for-repositories-in-your-organization) 和 [AUTOTITLE](/actions/reference/security/oidc#including-repository-custom-properties-in-oidc-tokens)。

       **在 OIDC 令牌中启用属性。** 组织或公司管理员使用设置 UI 或 REST API 选定应包含在 OIDC 令牌中的自定义特性。

       **声明会自动显示。** 存储库中为已启用属性设置值的每个工作流运行都会在其 OIDC 令牌中包含该值，前缀为 `repo_property_`。 不需要工作流级别的配置更改。

       **更新云信任策略。** 更新云提供程序的信任条件以评估新的 `repo_property_*` 声明，实现精细的基于属性的访问决策。

由于此版本基于 GitHub 现有的 OIDC 短期凭据模型，因此无需长期保密信息，并且每个令牌都有一定的范围、可审核，并在每个工作流运行时自动轮换。

先决条件

必须在组织或企业级别定义自定义属性。有关详细信息，请参阅“管理组织中存储库的自定义属性”。
必须是组织管理员或企业管理员。

将自定义属性添加到 OIDC 令牌的声明中

若要在 OIDC 令牌中包含自定义属性，请使用组织的或企业的 REST API 或设置 UI。

        **使用设置 UI：** 导航到组织或企业的 Actions OIDC 设置页，查看和管理 OIDC 令牌中包含的自定义属性。

          **使用 REST API：** 向 `/orgs/{org}/actions/oidc/customization/properties/repo` 终结点发送 `POST` 请求，为组织的 OIDC 令牌声明添加自定义属性。 有关请求参数和完整详细信息，请参阅用于管理 OIDC 自定义属性的 REST API 文档： [AUTOTITLE](/rest/actions/oidc)。

具有自定义属性的示例 OIDC 令牌

以下示例显示了一个包含两个自定义属性的 OIDC 令牌：单选属性 business_unit 和字符串属性 workspace_id。每个自定义属性都出现在带有前缀的 repo_property_ 令牌中。

{
  "sub": "repo:my-org/my-repo:ref:refs/heads/main",
  "aud": "https://github.com/my-org",
  "repository": "my-org/my-repo",
  "repository_owner": "my-org",
  "ref": "refs/heads/main",
  "repo_property_business_unit": "payments",
  "repo_property_workspace_id": "ws-abc123"
}

可以使用 repo_property_* 云提供商信任条件中的声明来创建灵活的基于属性的访问控制策略。有关声明格式、支持的属性类型和限制的详细信息，请参阅 OpenID Connect 参考。

对 OIDC 的支持 Dependabot

          Dependabot 可以使用 OIDC 通过专用注册表进行身份验证，而无需将长期凭据存储为存储库机密。 使用基于 OIDC 的身份验证，Dependabot 更新任务可以从您的云身份提供商动态获取短时效的凭据。

          Dependabot 当注册表托管在 AWS CodeArtifact、Azure DevOps Artifacts 或 JFrog Artifactory 上时，支持对使用 `username` 和 `password` 身份验证的任何注册表类型的 OIDC 身份验证。

OIDC 身份验证 Dependabot 的优点包括：

        **增强的安全性：** 消除存储库中的静态长期凭据。

        **更简单的管理：** 启用对专用注册表的安全、符合策略的访问。

        **避免速率限制：** 动态凭据有助于避免达到与静态令牌关联的速率限制。

有关详细信息，请参阅“为 Dependabot 配置对专用注册表的访问权限”。

后续步骤

有关配置 OIDC 的详细信息，请参阅安全强化您的部署。

有关 OIDC 的参考信息，请参阅 OpenID Connect 参考。

在本文中