OpenID Connect 参考

OIDC 令牌声明

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

OIDC 令牌包括以下声明。

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

声明	声明类型	说明
`aud`	读者	默认情况下，这是存储库所有者（例如拥有存储库的组织）的 URL。可以使用工具包命令设置自定义受众：`core.getIDToken(audience)`
`iss`	颁发者	OIDC 令牌的颁发者： `https://token.actions.githubusercontent.com`
`sub`	主题	定义要由云提供商验证的使用者声明。此设置对于确保仅以可预测的方式分配访问令牌至关重要。

额外的标准 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。
`enterprise`	包含正在运行的工作流所在存储库的企业名称。
`enterprise_id`	包含正在运行的工作流所在存储库的企业 ID。
`environment`	作业使用的环境的名称。如果包含 `environment` 声明（也通过 `include_claim_keys`），则环境是必需的且必须提供。
`event_name`	触发工作流程运行的事件的名称。
`head_ref`	工作流程运行中拉取请求的来源分支。
`job_workflow_ref`	对于使用可重用工作流的作业，请使用可重用工作流的参考路径。有关详细信息，请参阅“将 OpenID Connect 与可重用的工作流程结合使用”。
`job_workflow_sha`	对于使用可重用工作流的作业，可重用工作流文件的提交 SHA。
`ref`

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

已替换的值在GHE.com上

您的提供商的预期声明必须将githubusercontent.com替换为SUBDOMAIN.ghe.com，其中 SUBDOMAIN 是您企业在GHE.com上的子域。
对于包含企业名称或 slug 的路由的任何 URL，您必须在 GHE.com 上将其替换为您企业的子域名。

例如，如果子域为 octocorp，则以下替换适用：

查看 GitHub 的 OIDC 提供程序所支持所有声明的 URL 是 https://token.actions.octocorp.ghe.com/.well-known/openid-configuration。
OIDC 令牌中 iss 的值为 https://token.actions.octocorp.ghe.com。
企业可以在 https://token.actions.octocorp.ghe.com/octocorp 接收令牌，用于自定义 issuer 值的 REST API 终结点为 /enterprises/octocorp/actions/oidc/customization/issuer。

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

受众和主题声明通常结合使用，用来在云角色/资源上设定条件，以限定其对GitHub工作流的访问权限。 * 受众： 此值默认使用组织或存储库所有者的 URL。这可用于设置只有特定组织中的工作流程才能访问云角色的条件。 * 主题： 默认情况下，具有预定义的格式，并且是有关工作流的一些关键元数据（例如 GitHub 组织、存储库、分支或关联 job 环境）的串联。请参阅主题声明示例，了解主题声明是如何从连接的元数据中组合而成的。

如果需要更精细的信任条件，可以自定义 JWT 附带的颁发者（iss）和使用者（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 主题：

云提供商	示例
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"`

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

自定义令牌声明

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

可以自定义issuer或audience声明的值。请参阅自定义 issuer 值用于企业并自定义 audience 值。
可以对主题 (sub) 声明设置条件以要求 JWT 令牌源自特定存储库、可重用工作流或其他源，从而自定义 OIDC 配置的格式。
可以使用其他 OIDC 令牌声明（例如 repository_id 和 repository_visibility）定义精细 OIDC 策略。请参阅“OpenID Connect”。
可以将存储库自定义属性作为声明包含在 OIDC 令牌中，从而启用基于属性的访问控制策略。请参阅在 OIDC 令牌中包含存储库的自定义属性。

自定义 `audience` 值

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

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

为企业自定义 `issuer` 价值

默认情况下，JWT 由 GitHub 的 OIDC 提供程序在 https://token.actions.githubusercontent.com 签发。此路径在 JWT 中使用 iss 值提供给云提供商。

为了安全强化其 OIDC 配置，企业管理员可以将其企业配置为从唯一 URL (https://token.actions.githubusercontent.com/<enterpriseSlug>) 接收令牌，并将 <enterpriseSlug> 替换为企业的 slug 值。

此配置意味着企业会从唯一 URL 接收 OIDC 令牌，因而可以将云提供商配置为仅接受来自该 URL 的令牌。这有助于确保只有企业存储库才能使用 OIDC 访问云资源。

若要为企业激活此设置，企业管理员必须使用 /enterprises/{enterprise}/actions/oidc/customization/issuer 终结点并在请求正文中指定 "include_enterprise_slug": true。有关详细信息，请参阅“GitHub Actions OIDC 的 REST API 终结点”。

应用此设置后，JWT 会包含更新的 iss 值。在以下示例中，iss 键将 octocat-inc 用作其 enterpriseSlug 值：

{
  "jti": "6f4762ed-0758-4ccb-808d-ee3af5d723a8",
  "sub": "repo:octocat-inc/private-server:ref:refs/heads/main",
  "aud": "http://octocat-inc.example/octocat-inc",
  "enterprise": "octocat-inc",
  "enterprise_id": "123",
  "iss": "https://token.actions.githubusercontent.com/octocat-inc",
  "bf": 1755350653,
  "exp": 1755351553,
  "iat": 1755351253
}

在 OIDC 令牌中包含存储库自定义属性

注意

此功能目前以公共预览版提供，可能会更改。

组织和企业管理员可以选择存储库自定义属性，将其作为声明包含在 Actions OIDC 令牌中。将自定义属性添加到 OIDC 配置后，为该属性设置值的组织或企业中的每个存储库将自动将其包含在其 OIDC 令牌中。属性名称显示在带有 repo_property_前缀的标记中。

这样，就可以在云提供商中创建基于属性的访问控制（ABAC）策略，该策略直接绑定到存储库元数据，从而减少配置偏移，并且无需管理每个存储库的单独访问配置。

包括自定义属性的先决条件

必须在组织或企业级别定义自定义属性。
必须是组织管理员或企业管理员。
将自定义属性添加到 OIDC 配置后，为该属性设置值的组织或企业中的所有存储库将自动将其包含在其 OIDC 令牌中。

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

可以使用设置 UI 或 REST API 管理 OIDC 令牌中包含的自定义属性。

```
        **使用设置用户界面：** 
```
导航到组织的 Actions OIDC 设置，查看和配置 OIDC 令牌中包含的自定义属性。
```
        **使用 REST API：**
```
若要将自定义属性添加到组织的或企业的 OIDC 令牌声明，请使用 REST API。有关详细信息，请参阅“GitHub Actions OIDC 的 REST API 终结点”。

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

将自定义属性添加到 OIDC 配置后，为该属性设置的值的存储库将将其包含在其令牌中。在以下示例中，workspace_id 自定义属性在令牌中显示为 repo_property_workspace_id：

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

可以将这些 repo_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 终结点”。

注意

当应用组织模板时，它不会影响任何已使用 OIDC 的工作流，除非其存储库选择加入自定义组织模板。对于所有存储库（现有存储库和新存储库），存储库所有者将需要使用存储库级别 REST API ，通过将 use_default 设置为 false 来选择接收此配置。或者，存储库所有者可以使用 REST API 应用特定于存储库的其他配置。有关详细信息，请参阅“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 值的新格式。

{
   "include_claim_keys": [
       "repository_owner"
   ]
}

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

示例：需要可重用工作流

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

  {
     "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"。

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

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

此示例还演示如何使用 "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"

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

此示例模板使你可以跨所有分支/标记和环境向云授予对特定存储库中的所有工作流的访问权限。为了进一步提高安全性，可以将此模板与企业的唯一颁发者 URL 结合使用，如自定义企业的 issuer 值中所述。

{
   "include_claim_keys": [
       "repo"
   ]
}

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

示例：使用系统生成的 GUID

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

  {
     "include_claim_keys": [
         "repository_id"
     ]
  }

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

或者：

{
   "include_claim_keys": [
       "repository_owner_id"
   ]
}

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

示例：包含 `:` 的上下文值

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

{
   "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 值使用在令牌中出现的完整声明名称。

{
   "include_claim_keys": [
       "repo_property_workspace_id"
   ]
}

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

重置组织模板自定义

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

{
   "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
}

作业或工作流必须授予 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"

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

在本文中