概述
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
- 对于“受众”:如果使用官方操作,请使用
sts.amazonaws.com
。
配置角色和信任策略
若要在 IAM 中配置角色和信任,请参阅 AWS 文档“为 GitHub 操作配置 AWS 凭据”和“为 GitHub OIDC 标识提供者配置角色”。
注意:AWS 标识和访问管理 (IAM) 建议用户在信任 GitHub 的 OIDC 标识提供者 (IdP) 的任何角色的信任策略中评估 IAM 条件键 token.actions.githubusercontent.com:sub
。 在限制哪些 GitHub 操作能够承担该角色的角色信任策略中,评估此条件键。
编辑信任策略以将 sub
字段添加到验证条件。 例如:
"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" } }
"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 策略中使用环境时,建议将保护规则添加到环境中以提高安全性。 例如,可以在环境中配置部署规则,以限制可以部署到环境或访问环境机密的分支和标记。 有关详细信息,请参阅“管理部署环境”。
"Condition": { "StringEquals": { "token.actions.githubusercontent.com:aud": "sts.amazonaws.com", "token.actions.githubusercontent.com:sub": "repo:octo-org/octo-repo:environment:prod" } }
"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 中担任角色。
{ "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" } } } ] }
{
"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 进行两项更改:
- 为令牌添加权限设置。
- 使用
aws-actions/configure-aws-credentials
操作将 OIDC 令牌 (JWT) 交换为云访问令牌。
添加权限设置
作业或工作流运行需要使用 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 令牌按预期在调用方工作流中使用。
有关详细信息,请参阅“重新使用工作流”。
请求访问令牌
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
# 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 }}/
# 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 }}/