OpenID Connect 参考

OIDC 令牌声明

若要查看由GitHub的 OIDC 提供商支持的所有声明，请查看位于claims_supported``https://HOSTNAME/_services/token/.well-known/openid-configuration条目。

OIDC 令牌包括以下声明。

标准受众、颁发者和使用者声明

额外的标准 JOSE 标头参数和声明

由GitHub提供的自定义声明

          _（参考）_ 触发工作流运行的 git ref。                   |

| ref_type| ref 的类型，例如：“branch”。 | | repository_visibility | 运行工作流的存储库的可见性。 可接受以下值：internal、private 或 public。 | | repository| 运行工作流程的存储库。 | | repository_id| 运行工作流的存储库的 ID。 | | repository_owner| 存储 repository 的组织的名称。 | | repository_owner_id| 存储 repository 的组织的 ID。 | | | | 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 环境）的串联。 请参阅主题声明示例，了解主题声明是如何从连接的元数据中组合而成的。

如果需要更精细的信任条件，可以自定义 使用者（sub）声明。 有关详细信息，请参阅自定义令牌声明。

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

示例主题声明

以下示例演示如何使用“主题”作为条件，并说明如何从串联的元数据汇编“主题”。 主题使用来自 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 事件的主题。 在此示例中，工作流运行必须由 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

在云提供商中配置主题

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

有关配置特定云提供商的详细信息，请参阅 安全强化您的部署 中列出的指南。

自定义令牌声明

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

• 可以自定义audience声明的值。 请参阅 自定义 audience 值。
• 可以对主题 (sub) 声明设置条件以要求 JWT 令牌源自特定存储库、可重用工作流或其他源，从而自定义 OIDC 配置的格式。
• 可以使用其他 OIDC 令牌声明（例如 repository_id 和 repository_visibility）定义精细 OIDC 策略。 请参阅“OpenID Connect”。

自定义 audience 值

在您使用自定义操作的工作流中，这些操作可能会使用 GitHub Actions 工具包，使您能够为声明提供 audience 的自定义值。 一些云提供商还会在官方登录操作中使用它来强制实施 audience 声明的默认值。 例如，GitHub Action for Azure Login 操作 设置了一个默认的 aud 值为 api://AzureADTokenExchange，也允许你在工作流中设置自定义的aud值。 有关工具包的详细信息 GitHub Actions ，请参阅文档中的 OIDC 令牌 部分。

如果不想使用操作提供的默认 aud 值，可以为 audience 声明提供自定义值。 这允许你设置一个条件，即只有特定组织中的工作流才能访问云角色。 如果正在使用的操作支持此条件，则可以使用工作流中的 with 关键字将自定义 aud 值传递给该操作。 有关详细信息，请参阅“元数据语法参考”。

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

若要帮助提高安全性、合规性和标准化，可以自定义标准声明以满足所需的访问条件。 如果云提供商对主题声明支持条件，则可以创建一个条件，用于检查 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所述令牌中的默认预定义 格式。

          `sub` 声明使用简写形式 `repo`（例如 `repo:ORG-NAME/REPO-NAME`）而不是 `repository` 来引用存储库。 

          `:`上下文值中的任何内容都将替换为 `%3A`。 

以下示例模板演示了自定义主题声明的各种方法。 若要配置 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 声明，这些 GUID 不会在实际的重命名（例如重命名存储库）之间更改。

若要应用此配置，请向 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 声明。

示例：包含 : 的上下文值

此示例演示如何处理包含 : 的上下文值。 例如，当作业引用名为 production:eastus 的环境时。

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

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

在云提供商的 OIDC 配置中，将 sub 条件配置为要求声明必须包含 environment 和 repository_owner 的特定值。 例如： "sub": "environment:production%3Aeastus:repository_owner:octo-org"。

重置组织模板自定义

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

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

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

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

重置存储库模板自定义

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

若要选择退出仓库并重置回默认 sub 声明格式，仓库管理员必须在 GitHub Actions OIDC 的 REST API 终结点 使用 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 声明

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

请求 OIDC 令牌的工作流权限

必需的权限

• 作业或工作流必须授予 id-token: write 权限，以允许 GitHub 的 OIDC 提供程序创建 JSON Web 令牌 (JWT)：

  permissions:
    id-token: write
  

• 没有 id-token: write，则无法请求 OIDC JWT ID 令牌。 此设置仅启用获取和设置 OIDC 令牌；它不会授予对其他资源的写权限。

设置权限

• 若要为工作流获取 OIDC 令牌，请在工作流级别设置权限：

  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
  

• 根据工作流需要，可能需要其他权限。

可重用工作流

• 对于与调用方属于同一用户、组织或企业的可重用工作流程，可从调用方上下文访问可重用工作流程中生成的 OIDC 令牌。
• 对于企业或组织之外的可重用工作流程，请在调用方工作流程或作业级别将 permissions 的 id-token 设置显式设置为 write。 这可以确保 OIDC 令牌仅对预期的调用方工作流程可用。

请求 OIDC 令牌的方法

自定义操作可以使用以下方式请求 OIDC 令牌：

• Actions 工具包中的 getIDToken() 方法。 有关详细信息，请参阅 npm 包文档中的 OIDC 令牌。

• 运行器上的以下环境变量。

  变量	说明
  ACTIONS_ID_TOKEN_REQUEST_URL

          GitHub 的 OIDC 提供程序的 URL。 |
  

  | ACTIONS_ID_TOKEN_REQUEST_TOKEN | 向 OIDC 提供商发出请求的持有者令牌。 |

  例如：

  Shell

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