# OpenID Connect 参考 查找如何使用 OpenID Connect（OIDC）对GitHub Actions工作流通过云提供商进行身份验证的信息。 ## OIDC 令牌声明 若要查看由GitHub的 OIDC 提供商支持的所有声明，请查看位于`claims_supported` OIDC 令牌包括以下声明。 ### 标准受众、颁发者和使用者声明 | 声明 | 声明类型 | 说明 | | ----- | ---- | ------------------------------------------------------------------------------------------------------------------------------------ | | `aud` | 读者 | 默认情况下，这是存储库所有者（例如拥有存储库的组织）的 URL。 可以使用工具包命令设置自定义受众：[`core.getIDToken(audience)`](https://www.npmjs.com/package/@actions/core/v/1.6.0) | | `iss` | 颁发者 | OIDC 令牌的颁发者： `https://token.actions.githubusercontent.com` | | `sub` | 主题 | 定义要由云提供商验证的使用者声明。 此设置对于确保仅以可预测的方式分配访问令牌至关重要。 对于使用不可变使用者声明的存储库，`sub`格式包括不可变的所有者和存储库ID（这些ID在GitHub Enterprise Server上不可用）。 | ### 额外的标准 JOSE 标头参数和声明 | 标头参数 | 参数类型 | 说明 | | ----- | ----- | ------------------------------ | | `alg` | 算法 | OIDC 提供商使用的算法。 | | `kid` | 密钥标识符 | OIDC 令牌的唯一密钥。 | | `typ` | 类型 | 描述令牌的类型。 这是 JSON Web 令牌 (JWT)。 | | 声明 | 声明类型 | 说明 | | ----- | --------- | --------------- | | `exp` | 过期时间 | 标识 JWT 的过期时间。 | | `iat` | 颁发时间 | 颁发 JWT 的时间。 | | `jti` | JWT 令牌标识符 | OIDC 令牌的唯一标识符。 | | `nbf` | 不早于 | JWT 在此时间之前不可使用。 | ### 由GitHub提供的自定义声明 | 声明 | 说明 | | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `actor` | 发起工作流运行的个人帐户。 | | `actor_id` | 发起工作流运行的个人帐户的 ID。 | | `base_ref` | 工作流程运行中拉取请求的目标分支。 | | | | | `check_run_id` | 当前作业的检查运行 ID。 | | | | | | | | | | | `environment` | 作业使用的环境的名称。 如果包含 `environment` 声明（也通过 `include_claim_keys`），则环境是必需的且必须提供。 | | `event_name` | 触发工作流程运行的事件的名称。 | | `head_ref` | 工作流程运行中拉取请求的来源分支。 | | `job_workflow_ref` | 对于使用可重用工作流的作业，请使用可重用工作流的参考路径。 有关详细信息，请参阅“[将 OpenID Connect 与可重用的工作流程结合使用](/zh/actions/how-tos/secure-your-work/security-harden-deployments/oidc-with-reusable-workflows)”。 | | `job_workflow_sha` | 对于使用可重用工作流的作业，可重用工作流文件的提交 SHA。 | | `ref` | | | *（参考）* 触发工作流运行的 git ref。 | | | `ref_type` | | | `ref` 的类型，例如：“branch”。 | | | `repository_visibility` | 运行工作流的存储库的可见性。 可接受以下值：`internal`、`private` 或 `public`。 | | `repository` | 运行工作流程的存储库。 | | `repository_id` | 运行工作流的存储库的 ID。 | | `repository_owner` | 存储 `repository` 的组织的名称。 | | `repository_owner_id` | 存储 `repository` 的组织的 ID。 | | | | | `repo_property_*` | 在组织或企业级别定义的自定义属性，这些属性作为声明包含在 OIDC 令牌中，其前缀为 `repo_property_`。 有关详细信息，请参阅 [将存储库自定义属性包含在 OIDC 令牌中](#including-repository-custom-properties-in-oidc-tokens)。 | | | | | `run_id` | 触发工作流程的工作流程运行的 ID。 | | `run_number` | 此工作流程已运行的次数。 | | `run_attempt` | 此工作流程运行的重试次数。 | | `runner_environment` | 作业使用的运行器类型。 可接受以下值：`github-hosted` 或 `self-hosted`。 | | `workflow` | 工作流的名称。 | | `workflow_ref` | 工作流的引用路径。 例如，`octocat/hello-world/.github/workflows/my-workflow.yml@refs/heads/my_branch`。 | | `workflow_sha` | 工作流文件的提交 SHA。 | ## 用于在云角色上定义信任条件的 OIDC 声明 受众和主题声明通常结合使用，用来在云角色/资源上设定条件，以限定其对GitHub工作流的访问权限。 * **受众：** 此值默认使用组织或存储库所有者的 URL。 这可用于设置只有特定组织中的工作流程才能访问云角色的条件。 * **主题：** 默认情况下，具有预定义的格式，并且是有关工作流的一些关键元数据（例如 GitHub 组织、存储库、分支或关联 [`job`](/zh/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idenvironment) 环境）的串联。 请参阅[主题声明示例](#example-subject-claims)，了解主题声明是如何从连接的元数据中组合而成的。 如果需要更精细的信任条件，可以自定义包含颁发者 (`sub`) 和) 声明。 有关详细信息，请参阅[自定义令牌声明](#customizing-the-token-claims)。 OIDC 令牌中还支持许多其他声明，这些声明可用于设置这些条件。 此外，云提供商可以允许你为访问令牌分配角色，从而允许你指定更精细的权限。 > \[!NOTE] > 若要控制云提供商颁发访问令牌的方式，**必须**至少定义一个条件，以便不受信任的存储库无法为云资源请求访问令牌。 ## 示例主题声明 以下示例演示如何使用“主题”作为条件，并说明如何从串联的元数据汇编“主题”。 [主题](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims)使用来自 [`job` 上下文](/zh/actions/reference/workflows-and-actions/contexts#job-context)的信息，并指示云提供商只能为来自特定分支、环境中运行的工作流的请求授予访问令牌请求。 以下各节介绍了您可以使用的一些常见主题。 ### 筛选特定环境 当作业引用环境时，主题声明包括环境名称。 可以配置用于筛选特定[环境](/zh/actions/how-tos/deploy/configure-and-manage-deployments/manage-environments)名称的主题。 在此示例中，工作流运行必须源自 `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`](/zh/actions/reference/workflows-and-actions/events-that-trigger-workflows#pull_request) 事件的主题。 在此示例中，工作流运行必须由 `pull_request` 组织拥有的名为 `octo-repo` 的存储库中的 `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` ### 筛选包含 `:` 的元数据 元数据值中的任何`:`将在使用者声明中替换为`%3A`。 可以配置包含冒号的元数据的主题。 在此示例中，工作流运行必须源自 `Production:V1` 组织拥有的名为 `octo-repo` 的存储库中，一个具有名为 `octo-org` 的环境的作业： * 语法： `repo:ORG-NAME/REPO-NAME:environment:ENVIRONMENT-NAME` * 示例： `repo:octo-org/octo-repo:environment:Production%3AV1` ## 不可变的主题声明 OpenID Connect (OIDC) 规范要求主题 (`sub`) 声明在本地是唯一的并且永不重新分配。 以前，默认 `sub` 格式仅使用组织和存储库名称。 如果已回收命名空间，则其他所有者可以创建相同的主题值。 为了帮助防止这种情况，2026 年 7 月 15 日之后创建的存储库现在使用不可变的默认主题格式，其中包括所有者 ID 和存储库 ID。 此推出不包括 GitHub Enterprise Server。 * 语法： `repo:OWNER@OWNER-ID/REPO@REPO-ID:ref:refs/heads/BRANCH` * 以前的格式示例： `repo:octo-org/octo-repo:ref:refs/heads/main` * 不可变格式示例： `repo:octo-org@123456/octo-repo@456789:ref:refs/heads/main` 名称与 ID 之间使用 `@` 分隔符是因为 `@` 不能出现在 GitHub 用户名或存储库名称中。 除非你选择不可变使用者声明，否则在 2026 年 7 月 15 日之前创建的存储库保留以前的格式。 可以通过使用 OIDC 设置的用户界面或 REST API 在组织或存储库级别选择参与。 存储库在 2026 年 7 月 15 日之后重命名和传输也会移动到不可变的主题格式。 ## 在云提供商中配置主题 要在云提供商的信任关系中配置主题，必须将主题字符串添加到其信任配置中。 以下示例演示了不同的云提供商如何以不同的方式接受同一 `repo:octo-org/octo-repo:ref:refs/heads/demo-branch` 主题： | 云提供商 | 示例 | | --------------------- | ------------------------------------------------------------------------------------------------- | | Amazon Web Services | `"token.actions.githubusercontent.com:sub": "repo:octo-org/octo-repo:ref:refs/heads/demo-branch"` | | Azure | `repo:octo-org/octo-repo:ref:refs/heads/demo-branch` | | Google Cloud Platform | `(assertion.sub=='repo:octo-org/octo-repo:ref:refs/heads/demo-branch')` | | HashiCorp Vault | `bound_subject="repo:octo-org/octo-repo:ref:refs/heads/demo-branch"` | 对于在 2026 年 7 月 15 日之后创建的存储库，或者已选择加入不可变主题声明的存储库，声明 `sub` 包括 `owner_id` 并 `repo_id` 如不可变示例所示。 更新信任策略以匹配存储库使用的格式。 不可变的主题声明在 GitHub Enterprise Server 上不可用。 | 云提供商 | 不可变格式示例 | | --------------------- | --------------------------------------------------------------------------------------------------------------- | | Amazon Web Services | `"token.actions.githubusercontent.com:sub": "repo:octo-org@123456/octo-repo@456789:ref:refs/heads/demo-branch"` | | Azure | `repo:octo-org@123456/octo-repo@456789:ref:refs/heads/demo-branch` | | Google Cloud Platform | `(assertion.sub=='repo:octo-org@123456/octo-repo@456789:ref:refs/heads/demo-branch')` | | HashiCorp Vault | `bound_subject="repo:octo-org@123456/octo-repo@456789:ref:refs/heads/demo-branch"` | 有关配置特定云提供商的详细信息，请参阅 [安全强化您的部署](/zh/actions/how-tos/secure-your-work/security-harden-deployments) 中列出的指南。 ## 自定义令牌声明 可以通过自定义 JWT 中包含的声明来增强 OIDC 配置的安全性。 通过这些自定义，可以在允许工作流访问云中托管的资源时，对云角色定义更精细的信任条件： * 可以自定义`audience`声明的值。 请参阅 [自定义 `audience` 值](#customizing-the-audience-value)。 * 可以对主题 (`sub`) 声明设置条件以要求 JWT 令牌源自特定存储库、可重用工作流或其他源，从而自定义 OIDC 配置的格式。 * 可以使用其他 OIDC 令牌声明（例如 `repository_id` 和 `repository_visibility`）定义精细 OIDC 策略。 请参阅“[OpenID Connect](/zh/actions/concepts/security/openid-connect#understanding-the-oidc-token)”。 * 可以将存储库自定义属性作为声明包含在 OIDC 令牌中，从而启用基于属性的访问控制策略。 请参阅 [在 OIDC 令牌中包含存储库的自定义属性](#including-repository-custom-properties-in-oidc-tokens)。 ### 自定义 `audience` 值 在您使用自定义操作的工作流中，这些操作可能会使用 GitHub Actions 工具包，使您能够为声明提供 `audience` 的自定义值。 一些云提供商还会在官方登录操作中使用它来强制实施 `audience` 声明的默认值。 例如，[GitHub Action for Azure Login 操作](https://github.com/Azure/login/blob/master/action.yml) 设置了一个默认的 `aud` 值为 `api://AzureADTokenExchange`，也允许你在工作流中设置自定义的`aud`值。 有关工具包的详细信息 GitHub Actions ，请参阅文档中的 [OIDC 令牌](https://github.com/actions/toolkit/tree/main/packages/core#oidc-token) 部分。 如果不想使用操作提供的默认 `aud` 值，可以为 `audience` 声明提供自定义值。 这允许你设置一个条件，即只有特定组织中的工作流才能访问云角色。 如果正在使用的操作支持此条件，则可以使用工作流中的 `with` 关键字将自定义 `aud` 值传递给该操作。 有关详细信息，请参阅“[元数据语法参考](/zh/actions/reference/workflows-and-actions/metadata-syntax#inputs)”。 ### 在 OIDC 令牌中包含存储库自定义属性 组织和企业管理员可以选择要作为声明包含在 GitHub Actions OIDC 令牌中的存储库自定义属性。 将自定义属性添加到 OIDC 配置后，为该属性设置值的组织或企业中的每个存储库将自动将其包含在其 OIDC 令牌中。 属性名称显示在带有 `repo_property_`前缀的标记中。 这样，就可以在云提供商中创建基于属性的访问控制 （ABAC） 策略，该策略直接绑定到存储库元数据，从而减少配置偏移，并且无需管理每个存储库的单独访问配置。 #### 声明格式 每个已启用的自定义属性在 OIDC 令牌中显示为单独的声明。 声明名称是带有前缀`repo_property_`的属性名称。 | 自定义属性名称 | OIDC 令牌中的声明名称 | | --------------------- | ----------------------------------- | | `business_unit` | `repo_property_business_unit` | | `workspace_id` | `repo_property_workspace_id` | | `data_classification` | `repo_property_data_classification` | #### 支持的属性类型 支持作为 OIDC 声明的自定义属性类型如下。 令牌中的值表示形式取决于属性类型。 | 属性类型 | OIDC 令牌中的示例值 | 备注 | | ---------- | ------------------------------------------------ | ------------------------------- | | String | `"repo_property_team": "platform-eng"` | 值显示为纯字符串。 | | 单选 | `"repo_property_env_tier": "production"` | 所选选项显示为纯字符串。 | | 多选 | `"repo_property_regions": "us-east-1,eu-west-1"` | 多个选定的值联接到一个逗号分隔的字符串中。 | | True/false | `"repo_property_pci_compliant": "true"` | 布尔值显示为字符串 `"true"` 或 `"false"`。 | #### 多选值表示形式 当存储库具有选择了多个值的多选自定义属性时，这些值将联接到 OIDC 令牌中的单个逗号分隔字符串中。 例如，如果存储库具有属性 `regions` 其值为 `us-east-1` 和 `eu-west-1`，则声明显示为： ```json { "repo_property_regions": "us-east-1,eu-west-1" } ``` 在云提供商中配置信任策略时，请使用字符串匹配或包含检查来评估多选声明。 #### 包括自定义属性的先决条件 * 必须在组织或企业级别定义自定义属性。 有关详细信息，请参阅“[管理组织中存储库的自定义属性](/zh/organizations/managing-organization-settings/managing-custom-properties-for-repositories-in-your-organization)”。 * 必须是组织管理员或企业管理员。 * 将自定义属性添加到 OIDC 配置后，为该属性设置值的组织或企业中的所有存储库将自动将其包含在其 OIDC 令牌中。 #### 将自定义属性添加到 OIDC 令牌的声明中 可以使用设置 UI 或 REST API 管理 OIDC 令牌中包含的自定义属性。 * **使用设置用户界面：** 导航到组织的 Actions OIDC 设置，查看和配置 OIDC 令牌中包含的自定义属性。 * **使用 REST API：** 若要将自定义属性添加到您组织的 OIDC 令牌声明中，请向相应的 OIDC 自定义属性包含终端发送 `POST` 请求。 例如： * 对于组织：`POST /orgs/{org}/actions/oidc/customization/properties/repo` * 对于企业： `POST /enterprises/{enterprise}/actions/oidc/customization/properties/repo` 有关请求参数和完整详细信息，请参阅用于管理 OIDC 自定义属性的 REST API 文档： [GitHub Actions OIDC 的 REST API 终结点](/zh/rest/actions/oidc)。 #### 具有自定义属性的示例令牌 将自定义属性添加到 OIDC 配置后，为该属性设置的值的存储库将将其包含在其令牌中。 在以下示例中，令牌中包含两个自定义属性（`business_unit` 和 `workspace_id`） ： ```json { "sub": "repo:my-org/my-repo:ref:refs/heads/main", "aud": "https://github.com/my-org", "repository": "my-org/my-repo", "repo_property_business_unit": "payments", "repo_property_workspace_id": "ws-abc123" } ``` 可以将这些 `repo_property_*` 声明用作云提供商信任策略中的条件。 有关示例，请参阅 [示例：筛选存储库自定义属性](#example-filtering-on-a-repository-custom-property)。 ### 为组织或存储库自定义主题声明 若要帮助提高安全性、合规性和标准化，可以自定义标准声明以满足所需的访问条件。 如果云提供商对主题声明支持条件，则可以创建一个条件，用于检查 `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 终结点](/zh/rest/actions/oidc)”。 > \[!NOTE] > 当应用组织模板时，它不会影响任何已使用 OIDC 的工作流，除非其存储库选择加入自定义组织模板。 对于所有存储库（现有存储库和新存储库），存储库所有者将需要使用存储库级别 REST API ，通过将 `use_default` 设置为 `false` 来选择接收此配置。 或者，存储库所有者可以使用 REST API 应用特定于存储库的其他配置。 有关详细信息，请参阅“[GitHub Actions OIDC 的 REST API 终结点](/zh/rest/actions/oidc#set-the-customization-template-for-an-oidc-subject-claim-for-a-repository)”。 自定义声明会导致整个 `sub` 声明采用新格式，这会替换`sub`所述令牌中的默认预定义 [](#example-subject-claims) 格式。 > \[!NOTE] > > ``` > `sub` 声明使用简写形式 `repo`（例如 `repo:ORG-NAME/REPO-NAME`）而不是 `repository` 来引用存储库。 > `:`上下文值中的任何内容都将替换为 `%3A`。 > ``` 对于使用不可变主题声明的存储库（GitHub Enterprise Server中不可用），`owner_id`和`repo_id`始终包含在`repo`声明的`sub`段中，即使您使用`include_claim_keys`自定义声明，也不例外。 无法从不可变格式中删除这些 ID。 以下示例模板演示了自定义主题声明的各种方法。 若要配置 GitHub这些设置，管理员使用 REST API 指定必须包含在主题 （`sub`） 声明中的声明列表。 若要应用此配置，请向 API 终结点提交请求，并在请求正文中包含所需配置。 对于组织，请参阅“[GitHub Actions OIDC 的 REST API 终结点](/zh/rest/actions/oidc#set-the-customization-template-for-an-oidc-subject-claim-for-an-organization)”；对于仓库，请参阅“[GitHub Actions OIDC 的 REST API 终结点](/zh/rest/actions/oidc#set-the-customization-template-for-an-oidc-subject-claim-for-a-repository)”。 若要自定义使用者声明，应首先在云提供商的 OIDC 配置中创建匹配条件，然后使用 REST API 自定义配置。 配置完成后，每次运行新作业时，在该作业期间生成的 OIDC 令牌都会遵循新的自定义模板。 如果在作业运行之前，云提供商的 OIDC 配置中不存在匹配条件，则云提供商可能不会接受生成的令牌，因为云条件可能未同步。 #### 示例：基于可见性和所有者允许存储库 此示例模板允许 `sub` 声明具有使用 `repository_owner` 和 `repository_visibility` 的新格式： ```json { "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 终结点](/zh/rest/actions/oidc#set-the-customization-template-for-an-oidc-subject-claim-for-an-organization)”；对于仓库，请参阅“[GitHub Actions OIDC 的 REST API 终结点](/zh/rest/actions/oidc#set-the-customization-template-for-an-oidc-subject-claim-for-a-repository)”。 ```json { "include_claim_keys": [ "repository_owner" ] } ``` 在云提供商的 OIDC 配置中，将 `sub` 条件配置为要求声明必须包含 `repository_owner` 的特定值。 例如：`"sub": "repository_owner:monalisa"` #### 示例：需要可重用工作流 此示例模板允许 `sub` 声明具有包含 `job_workflow_ref` 声明值的新格式。 这使企业能够使用可重用工作流在其组织和存储库中实施一致的部署。 若要应用此配置，请向 API 终结点提交请求，并在请求正文中包含所需配置。 对于组织，请参阅“[GitHub Actions OIDC 的 REST API 终结点](/zh/rest/actions/oidc#set-the-customization-template-for-an-oidc-subject-claim-for-an-organization)”；对于仓库，请参阅“[GitHub Actions OIDC 的 REST API 终结点](/zh/rest/actions/oidc#set-the-customization-template-for-an-oidc-subject-claim-for-a-repository)”。 ```json { "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 终结点](/zh/rest/actions/oidc#set-the-customization-template-for-an-oidc-subject-claim-for-an-organization)”；对于仓库，请参阅“[GitHub Actions OIDC 的 REST API 终结点](/zh/rest/actions/oidc#set-the-customization-template-for-an-oidc-subject-claim-for-a-repository)”。 此示例还演示如何使用 `"context"` 定义条件。 这是采用默认 `sub` 格式的仓库后面的部分。 例如，当作业引用环境时，上下文包含：`environment:ENVIRONMENT-NAME`。 ```json { "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 终结点](/zh/rest/actions/oidc#set-the-customization-template-for-an-oidc-subject-claim-for-an-organization)”；对于仓库，请参阅“[GitHub Actions OIDC 的 REST API 终结点](/zh/rest/actions/oidc#set-the-customization-template-for-an-oidc-subject-claim-for-a-repository)”。 ```json { "include_claim_keys": [ "repo" ] } ``` 在云提供商的 OIDC 配置中，将 `sub` 条件配置为需要与所需值匹配的 `repo` 声明。 #### 示例：使用系统生成的 GUID 此示例模板使用系统生成的 GUID 实现可预测的 OIDC 声明，这些 GUID 不会在实际的重命名（例如重命名存储库）之间更改。 若要应用此配置，请向 API 终结点提交请求，并在请求正文中包含所需配置。 对于组织，请参阅“[GitHub Actions OIDC 的 REST API 终结点](/zh/rest/actions/oidc#set-the-customization-template-for-an-oidc-subject-claim-for-an-organization)”；对于仓库，请参阅“[GitHub Actions OIDC 的 REST API 终结点](/zh/rest/actions/oidc#set-the-customization-template-for-an-oidc-subject-claim-for-a-repository)”。 ```json { "include_claim_keys": [ "repository_id" ] } ``` 在云提供商的 OIDC 配置中，将 `sub` 条件配置为需要与所需值匹配的 `repository_id` 声明。 或者： ```json { "include_claim_keys": [ "repository_owner_id" ] } ``` 在云提供商的 OIDC 配置中，将 `sub` 条件配置为需要与所需值匹配的 `repository_owner_id` 声明。 #### 示例：包含 `:` 的上下文值 此示例演示如何处理包含 `:` 的上下文值。 例如，当作业引用名为 `production:eastus` 的环境时。 若要应用此配置，请向 API 终结点提交请求，并在请求正文中包含所需配置。 对于组织，请参阅“[GitHub Actions OIDC 的 REST API 终结点](/zh/rest/actions/oidc#set-the-customization-template-for-an-oidc-subject-claim-for-an-organization)”；对于仓库，请参阅“[GitHub Actions OIDC 的 REST API 终结点](/zh/rest/actions/oidc#set-the-customization-template-for-an-oidc-subject-claim-for-a-repository)”。 ```json { "include_claim_keys": [ "environment", "repository_owner" ] } ``` 在云提供商的 OIDC 配置中，将 `sub` 条件配置为要求声明必须包含 `environment` 和 `repository_owner` 的特定值。 例如： `"sub": "environment:production%3Aeastus:repository_owner:octo-org"`。 #### 示例：筛选存储库自定义属性 此示例模板允许 `sub` 声明包含存储库自定义属性声明。 在 OIDC 令牌中包含的自定义属性以 `repo_property_` 前缀形式出现，但 `include_claim_keys` 值使用在令牌中出现的完整声明名称。 若要应用此配置，请向 API 终结点提交请求，并在请求正文中包含所需配置。 对于组织，请参阅“[GitHub Actions OIDC 的 REST API 终结点](/zh/rest/actions/oidc#set-the-customization-template-for-an-oidc-subject-claim-for-an-organization)”；对于仓库，请参阅“[GitHub Actions OIDC 的 REST API 终结点](/zh/rest/actions/oidc#set-the-customization-template-for-an-oidc-subject-claim-for-a-repository)”。 ```json { "include_claim_keys": [ "repo_property_workspace_id" ] } ``` 在云提供商的 OIDC 配置中，将 `sub` 条件配置为要求声明必须包含 `repo_property_workspace_id` 的特定值。 例如： `"sub": "repo_property_workspace_id:ws-abc123"`。 #### 重置组织模板自定义 此示例模板将主题声明重置为默认格式。 此模板实际上会选择退出任何组织级自定义策略。 若要应用此配置，请向 API 终结点提交请求，并在请求正文中包含所需配置。 对于组织，请参阅“[GitHub Actions OIDC 的 REST API 终结点](/zh/rest/actions/oidc#set-the-customization-template-for-an-oidc-subject-claim-for-an-organization)”；对于仓库，请参阅“[GitHub Actions OIDC 的 REST API 终结点](/zh/rest/actions/oidc#set-the-customization-template-for-an-oidc-subject-claim-for-a-repository)”。 ```json { "include_claim_keys": [ "repo", "context" ] } ``` 在云提供商的 OIDC 配置中，将 `sub` 条件配置为要求声明必须包含 `repo` 和 `context` 的特定值。 #### 重置存储库模板自定义 组织中的所有存储库都可以选择加入或选择退出（组织和存储库级的）自定义 `sub` 声明模板。 若要选择退出仓库并重置回默认 `sub` 声明格式，仓库管理员必须在 [GitHub Actions OIDC 的 REST API 终结点](/zh/rest/actions/oidc#set-the-customization-template-for-an-oidc-subject-claim-for-a-repository) 使用 REST API 终结点。 要将存储库配置为使用默认的 `sub` 声明格式，请使用 `PUT /repos/{owner}/{repo}/actions/oidc/customization/sub` REST API 终结点，并包含以下请求正文。 ```json { "use_default": true } ``` #### 示例：将存储库配置为使用组织模板 组织创建自定义 `sub` 声明模板后，可以使用 REST API 以编程方式将模板应用于组织内的存储库。 存储库管理员可以将其存储库配置为使用其组织管理员创建的模板。 要将存储库配置为使用组织的模板，存储库管理员必须使用 `PUT /repos/{owner}/{repo}/actions/oidc/customization/sub` REST API 终结点，并包含以下请求正文。 有关详细信息，请参阅“[GitHub Actions OIDC 的 REST API 终结点](/zh/rest/actions/oidc#set-the-customization-template-for-an-oidc-subject-claim-for-a-repository)”。 ```json { "use_default": false } ``` ## 调试 OIDC 声明 在与云提供商集成之前，可以使用该 [`github/actions-oidc-debugger`](https://github.com/github/actions-oidc-debugger) 操作可视化要发送的声明。 此操作请求 JWT 并打印在从 GitHub Actions 接收的 JWT 中包含的声明。 ## 请求 OIDC 令牌的工作流权限 ### 必需的权限 * 作业或工作流必须授予 [`id-token: write`](/zh/actions/reference/workflows-and-actions/workflow-syntax#permissions) 权限，以允许 GitHub 的 OIDC 提供程序创建 JSON Web 令牌 (JWT)： ```yaml permissions: id-token: write ``` * 没有 `id-token: write`，则无法请求 OIDC JWT ID 令牌。 此设置仅启用获取和设置 OIDC 令牌；它不会授予对其他资源的写权限。 ### 设置权限 * 若要为工作流获取 OIDC 令牌，请在工作流级别设置权限： ```yaml permissions: id-token: write # This is required for requesting the JWT contents: read # This is required for actions/checkout ``` * 若要为单个作业获取 OIDC 令牌，请在该作业中设置权限： ```yaml permissions: id-token: write # This is required for requesting the JWT ``` * 根据工作流需要，可能需要其他权限。 ### 可重用工作流 * 对于与调用方属于同一用户、组织或企业的可重用工作流程，可从调用方上下文访问可重用工作流程中生成的 OIDC 令牌。 * 对于企业或组织之外的可重用工作流程，请在调用方工作流程或作业级别将 `permissions` 的 `id-token` 设置显式设置为 `write`。 这可以确保 OIDC 令牌仅对预期的调用方工作流程可用。 ## 请求 OIDC 令牌的方法 自定义操作可以使用以下方式请求 OIDC 令牌： * Actions 工具包中的 `getIDToken()` 方法。 有关详细信息，请参阅 npm 包文档中的 [OIDC 令牌](https://www.npmjs.com/package/@actions/core/v/1.6.0#oidc-token)。 * 运行器上的以下环境变量。 | 变量 | 说明 | | ------------------------------ | -- | | `ACTIONS_ID_TOKEN_REQUEST_URL` | | GitHub 的 OIDC 提供程序的网址。 | \| `ACTIONS_ID_TOKEN_REQUEST_TOKEN` | 向 OIDC 提供商发出请求的持有者令牌。 | 例如： ```shell copy curl -H "Authorization: bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" "$ACTIONS_ID_TOKEN_REQUEST_URL&audience=api://AzureADTokenExchange" ```