在 Amazon Web Services 中配置 OpenID Connect

在您的工作流中使用 OpenID Connect 来对 Amazon Web Services 进行身份验证。

本文内容

概述

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

本指南介绍如何配置 AWS 以信任 GitHub 的 OIDC 作为联合身份，并包含 aws-actions/configure-aws-credentials 的工作流示例，该示例使用令牌对 AWS 进行身份验证并访问资源。

注意

AWS 中不提供对 OIDC 的自定义声明的支持。

先决条件

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

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

向 AWS 添加身份提供商

要将 GitHub OIDC 提供程序添加到 IAM，请参阅AWS 文档。

  • 对于提供程序 URL：使用https://token.actions.githubusercontent.com
  • 对于“Audience”：如果您使用的是官方操作，则使用sts.amazonaws.com。

配置角色和信任策略

要配置 IAM 中的角色和信任，请参阅 AWS 文档“为 GitHub Actions 配置 AWS 凭证”和“为 GitHub OIDC 身份提供商配置角色”。

注意

AWS 身份和访问管理 (IAM) 建议用户在信任 GitHub 的 OIDC 身份提供商 (IdP) 的任何角色的信任策略中评估 IAM 条件键token.actions.githubusercontent.com:sub。在角色信任策略中评估此条件键可以限制哪些 GitHub Actions 能够承担该角色。

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

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

如果您使用具有环境的工作流程，则sub字段必须引用环境名称：repo:ORG-NAME/REPO-NAME:environment:ENVIRONMENT-NAME。有关更多信息，请参阅“关于使用 OpenID Connect 加强安全性的信息”。

注意

当在工作流程或 OIDC 策略中使用环境时，我们建议为环境添加保护规则以增强安全性。例如，您可以配置环境上的部署规则，以限制哪些分支和标签可以部署到环境或访问环境机密。有关更多信息，请参阅“管理用于部署的环境”。

JSON
"Condition": {
  "StringEquals": {
    "token.actions.githubusercontent.com:aud": "sts.amazonaws.com",
    "token.actions.githubusercontent.com:sub": "repo:octo-org/octo-repo:environment:prod"
  }
}

在以下示例中，StringLike与通配符运算符 (*) 一起使用，以允许来自octo-org/octo-repo组织和存储库的任何分支、拉取请求合并分支或环境在 AWS 中承担角色。

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:*"
                },
                "StringEquals": {
                    "token.actions.githubusercontent.com:aud": "sts.amazonaws.com"
                }
            }
        }
    ]
}

更新您的 GitHub Actions 工作流程

要更新您的 OIDC 工作流程，您需要对 YAML 进行两处更改。

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

添加权限设置

作业或工作流程运行需要具有id-token: write权限设置，以允许 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)。
  • 使用 Actions 工具包中的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

根据您的工作流程要求，您可能需要在此处指定其他权限。

对于由与调用者工作流程相同的用户、组织或企业拥有的可重用工作流程，可以在调用者的上下文中访问在可重用工作流程中生成的 OIDC 令牌。对于企业或组织外部的可重用工作流程，应在调用者工作流程级别或调用可重用工作流程的特定作业中将id-token的permissions设置显式设置为write。这可确保只有在需要时才允许在调用者工作流程中使用在可重用工作流程中生成的 OIDC 令牌。

有关更多信息，请参阅“重用工作流程”。

请求访问令牌

aws-actions/configure-aws-credentials操作接收来自 GitHub OIDC 提供程序的 JWT，然后向 AWS 请求访问令牌。有关更多信息，请参阅 AWS 文档。

  • BUCKET-NAME：将其替换为您的 S3 存储桶的名称。
  • AWS-REGION：将其替换为您的 AWS 区域的名称。
  • ROLE-TO-ASSUME：将其替换为您的 AWS 角色。例如，arn:aws:iam::1234567890:role/example-role
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 : "BUCKET-NAME"
  AWS_REGION : "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@v4
      - name: configure aws credentials
        uses: aws-actions/configure-aws-credentials@e3dd6a429d7300a6a4c196c26e071d42e0343502
        with:
          role-to-assume: ROLE-TO-ASSUME
          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 }}/

进一步阅读