Skip to main content

在 Amazon Web Services 中配置 OpenID Connect

在工作流程中使用 OpenID Connect 向 Amazon Web Services 进行身份验证。

注意:GitHub Enterprise Server 目前不支持 GitHub 托管的运行器。 可以在 GitHub public roadmap 上查看有关未来支持计划的更多信息。

概述

OpenID Connect (OIDC) 允许您的 GitHub Actions 工作流程访问 Amazon Web Services (AWS) 中的资源,而无需将任何 AWS 凭据存储为长期 GitHub 机密。

本指南说明如何配置 AWS 信任 GitHub 的 OIDC 作为联合标识,并包含 aws-actions/configure-aws-credentials 的工作流示例,其使用令牌向 AWS 进行身份验证并访问资源。

先决条件

  • 若要了解 GitHub 如何使用 OpenID Connect (OIDC) 及其体系结构和优势的基本概念,请参阅“关于使用 OpenID Connect 加强安全性”。

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

将身份提供商添加到 AWS

要将 GitHub OIDC 提供商添加到 IAM,请参阅 AWS 文档

  • 对于提供程序 URL:使用 https://HOSTNAME/_services/token
  • 对于“受众”:如果使用官方操作,请使用 sts.amazonaws.com

配置角色和信任策略

要在 IAM 中配置角色和信任,请参阅“假定角色”“为 Web 身份或 OpenID 连接联合创建角色”的 AWS 文档。

编辑信任策略以将 sub 字段添加到验证条件。 例如:

JSON
"Condition": {
  "StringEquals": {
    "HOSTNAME/_services/token:aud": "sts.amazonaws.com",
    "HOSTNAME/_services/token:sub": "repo:octo-org/octo-repo:ref:refs/heads/octo-branch"
  }
}

在以下示例中,ForAllValues 用于匹配多个条件键,StringLike 用于匹配指定存储库中的任何 ref。 请注意,ForAllValues 过于宽松,不应在 Allow 效果中单独使用。 对于此示例,包含 StringLike 表示 ForAllValues 中的空集仍然不会传递条件:

JSON
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Federated": "arn:aws:iam::123456123456:oidc-provider/token.actions.githubusercontent.com"
            },
            "Action": "sts:AssumeRoleWithWebIdentity",
            "Condition": {
                "StringLike": {
                    "token.actions.githubusercontent.com:sub": "repo:octo-org/octo-repo:*"
                },
                "ForAllValues:StringEquals": {
                    "token.actions.githubusercontent.com:iss": "https://token.actions.githubusercontent.com",
                    "token.actions.githubusercontent.com:aud": "sts.amazonaws.com"
                }
            }
        }
    ]
}

更新 GitHub Actions 工作流程

要更新 OIDC 的工作流程,您需要对 YAML 进行两项更改:

  1. 为令牌添加权限设置。
  2. 使用 aws-actions/configure-aws-credentials 操作将 OIDC 令牌 (JWT) 交换为云访问令牌。

添加权限设置

作业或工作流运行需要具有 id-token: writepermissions 设置。 如果 id-tokenpermissions 设置已设置为 readnone,则无法请求 OIDC JWT ID 令牌。

id-token: write 设置允许使用下列方法之一从 GitHub 的 OIDC 提供程序请求 JWT:

  • 在运行器上使用环境变量(ACTIONS_ID_TOKEN_REQUEST_URLACTIONS_ID_TOKEN_REQUEST_TOKEN)。
  • 使用“操作”工具包中的 getIDToken()

如果需要为工作流提取 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

可能需要在此处指定额外权限,具体取决于你的工作流要求。

请求访问令牌

aws-actions/configure-aws-credentials 操作从 GitHub OIDC 提供商接收 JWT,然后从 AWS 请求访问令牌。 有关详细信息,请参阅 AWS 文档

  • <example-bucket-name>:在此处添加 S3 Bucket 的名称。
  • <role-to-assume>:将示例替换为你的 AWS 角色。
  • <example-aws-region>:在此处添加 AWS 区域的名称。
YAML
# Sample workflow to access AWS resources when workflow is tied to branch
# The workflow Creates static website using aws s3
name: AWS example workflow
on:
  push
env:
  BUCKET_NAME : "<example-bucket-name>"
  AWS_REGION : "<example-aws-region>"
# permission can be added at job level or workflow level    
permissions:
      id-token: write   # This is required for requesting the JWT
      contents: read    # This is required for actions/checkout
jobs:
  S3PackageUpload:
    runs-on: ubuntu-latest
    steps:
      - name: Git clone the repository
        uses: actions/checkout@v3
      - name: configure aws credentials
        uses: aws-actions/configure-aws-credentials@v1
        with:
          role-to-assume: arn:aws:iam::1234567890:role/example-role
          role-session-name: samplerolesession
          aws-region: ${{ env.AWS_REGION }}
      # Upload a file to AWS s3
      - name:  Copy index.html to s3
        run: |
          aws s3 cp ./index.html s3://${{ env.BUCKET_NAME }}/