Configuring OpenID Connect in cloud providers

Overview

OpenID Connect (OIDC) allows your GitHub Actions workflows to access resources in your cloud provider, without having to store any credentials as long-lived GitHub secrets.

To use OIDC, you will first need to configure your cloud provider to trust GitHub's OIDC as a federated identity, and must then update your workflows to authenticate using tokens.

Prerequisites

• 若要了解 GitHub 如何使用 OpenID Connect (OIDC) 及其体系结构和优势的基本概念，请参阅“OpenID Connect”。

• 在继续之前，必须规划安全策略，以确保仅以可预测的方式分配访问令牌。 要控制云提供商颁发访问令牌的方式，必须至少定义一个条件，以便不受信任的存储库无法为云资源请求访问令牌。 有关详细信息，请参阅“OpenID Connect”。

Updating your GitHub Actions workflow

To update your workflows for OIDC, you will need to make two changes to your YAML:

1. Add permissions settings for the token.
2. Use the official action from your cloud provider to exchange the OIDC token (JWT) for a cloud access token.

If your cloud provider doesn't yet offer an official action, you can update your workflows to perform these steps manually.

Adding permissions settings

作业或工作流运行需要使用 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）。
• 使用“操作”工具包中的 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 令牌按预期在调用方工作流中使用。

有关详细信息，请参阅“重用工作流”。

Using official actions

If your cloud provider has created an official action for using OIDC with GitHub Actions, it will allow you to easily exchange the OIDC token for an access token. You can then update your workflows to use this token when accessing cloud resources.

For example, Alibaba Cloud created aliyun/configure-aliyun-credentials-action to integrate with using OIDC with GitHub.

Using custom actions

If your cloud provider doesn't have an official action, or if you prefer to create custom scripts, you can manually request the JSON Web Token (JWT) from GitHub's OIDC provider.

If you're not using an official action, then GitHub recommends that you use the Actions core toolkit. Alternatively, you can use the following environment variables to retrieve the token: ACTIONS_ID_TOKEN_REQUEST_TOKEN, ACTIONS_ID_TOKEN_REQUEST_URL.

To update your workflows using this approach, you will need to make three changes to your YAML:

1. Add permissions settings for the token.
2. Add code that requests the OIDC token from GitHub's OIDC provider.
3. Add code that exchanges the OIDC token with your cloud provider for an access token.

Requesting the JWT using the Actions core toolkit

The following example demonstrates how to use actions/github-script with the core toolkit to request the JWT from GitHub's OIDC provider. For more information, see 创建 JavaScript 操作.

jobs:
  job:
    environment: Production
    runs-on: ubuntu-latest
    steps:
    - name: Install OIDC Client from Core Package
      run: npm install @actions/core@1.6.0 @actions/http-client
    - name: Get Id Token
      uses: actions/github-script@v7
      id: idtoken
      with:
        script: |
          const coredemo = require('@actions/core')
          let id_token = await coredemo.getIDToken()
          coredemo.setOutput('id_token', id_token)

Requesting the JWT using environment variables

The following example demonstrates how to use environment variables to request a JSON Web Token.

For your deployment job, you will need to define the token settings, using actions/github-script with the core toolkit. For more information, see 创建 JavaScript 操作.

For example:

jobs:
  job:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/github-script@v7
      id: script
      timeout-minutes: 10
      with:
        debug: true
        script: |
          const token = process.env['ACTIONS_RUNTIME_TOKEN']
          const runtimeUrl = process.env['ACTIONS_ID_TOKEN_REQUEST_URL']
          core.setOutput('TOKEN', token.trim())
          core.setOutput('IDTOKENURL', runtimeUrl.trim())

You can then use curl to retrieve a JWT from the GitHub OIDC provider. For example:

    - run: |
        IDTOKEN=$(curl -H "Authorization: Bearer ${{steps.script.outputs.TOKEN}}" ${{steps.script.outputs.IDTOKENURL}}  -H "Accept: application/json; api-version=2.0" -H "Content-Type: application/json" -d "{}" | jq -r '.value')
        echo $IDTOKEN
        jwtd() {
            if [[ -x $(command -v jq) ]]; then
                jq -R 'split(".") | .[0],.[1] | @base64d | fromjson' <<< "${1}"
                echo "Signature: $(echo "${1}" | awk -F'.' '{print $3}')"
            fi
        }
        jwtd $IDTOKEN
        echo "idToken=${IDTOKEN}" >> $GITHUB_OUTPUT
      id: tokenid

Getting the access token from the cloud provider

You will need to present the OIDC JSON web token to your cloud provider in order to obtain an access token.

For each deployment, your workflows must use cloud login actions (or custom scripts) that fetch the OIDC token and present it to your cloud provider. The cloud provider then validates the claims in the token; if successful, it provides a cloud access token that is available only to that job run. The provided access token can then be used by subsequent actions in the job to connect to the cloud and deploy to its resources.

The steps for exchanging the OIDC token for an access token will vary for each cloud provider.

Accessing resources in your cloud provider

Once you've obtained the access token, you can use specific cloud actions or scripts to authenticate to the cloud provider and deploy to its resources. These steps could differ for each cloud provider.

For example, Alibaba Cloud maintains their own instructions for OIDC authentication. For more information, see Overview of OIDC-based SSO in the Alibaba Cloud documentation.

In addition, the default expiration time of this access token could vary between each cloud and can be configurable at the cloud provider's side.

Further reading

• 将 OpenID Connect 与可重用的工作流程结合使用
• Self-hosted runners reference