참고: GitHub 호스트 실행기는 현재 GitHub Enterprise Server에서 지원되지 않습니다. GitHub public roadmap에 예정된 향후 지원에 대해 자세히 알아볼 수 있습니다.
개요
OIDC(OpenID Connect)를 사용하면 GitHub Actions 워크플로가 AWS 자격 증명을 수명이 긴 GitHub 비밀로 저장할 필요 없이 AWS(Amazon Web Services)의 리소스에 액세스할 수 있습니다.
이 가이드에서는 GitHub의 OIDC를 페더레이션된 ID로 신뢰하도록 AWS를 구성하는 방법에 대해 설명하고, 토큰을 사용하여 AWS에 인증하고 리소스에 액세스하는 aws-actions/configure-aws-credentials
워크플로 예제를 포함합니다.
참고: AWS에서는 OIDC에 대한 사용자 지정 청구와 관련된 지원을 사용할 수 없습니다.
필수 조건
-
GitHub가 OIDC(OpenID Connect)를 사용하는 방법과 아키텍처 및 이점에 대한 기본 개념을 알아보려면 “OpenID Connect를 사용한 보안 강화 정보”를 참조하세요.
-
계속하기 전에 액세스 토큰이 예측 가능한 방식으로만 할당되도록 보안 전략을 계획해야 합니다. 클라우드 공급자가 액세스 토큰을 발급하는 방법을 제어하려면 신뢰할 수 없는 리포지토리가 클라우드 리소스에 대한 액세스 토큰을 요청할 수 없도록 하나 이상의 조건을 정의해야 합니다. 자세한 내용은 "OpenID Connect를 사용한 보안 강화 정보"을(를) 참조하세요.
-
클라우드 공급자가 다음 OIDC 엔드포인트에 액세스할 수 있는지 확인해야 합니다.
https://HOSTNAME/_services/token/.well-known/openid-configuration
https://HOSTNAME/_services/token/.well-known/jwks
참고: AWS IP 주소 범위만 허용하여 OIDC 엔드포인트에 대한 액세스를 제한할 수 있습니다.
참고: {data variables.product.prodname_dotcom %}은 기본적으로 AWS 세션 태그를 지원하지 않습니다.
AWS에 ID 공급자 추가
GitHub OIDC 공급자를 IAM에 추가하려면 AWS 설명서를 참조하세요.
- 공급자 URL:
https://HOSTNAME/_services/token
- "대상 그룹"의 경우: 공식 작업을 사용하는 경우
sts.amazonaws.com
을 사용합니다.
역할 및 신뢰 정책 구성
IAM에서 역할 및 신뢰를 구성하려면 AWS 설명서 "GitHub 작업을 위한 AWS 자격 증명 구성" 및 "GitHub OIDC ID 공급자에 대한 역할 구성"을 참조하세요.
참고: AWS IAM(신원 및 액세스 관리)은 사용자가 GitHub의 OIDC ID 공급자(IdP)를 신뢰하는 모든 역할의 신뢰 정책에서 IAM 조건 키, token.actions.githubusercontent.com:sub
를 평가할 것을 권장합니다. 역할 트러스트 정책에서 이 조건 키를 평가하면 역할을 맡을 수 있는 GitHub 작업이 제한됩니다.
유효성 검사 조건에 sub
필드를 추가하여 신뢰 정책을 편집합니다. 예:
"Condition": { "StringEquals": { "HOSTNAME/_services/token:aud": "sts.amazonaws.com", "HOSTNAME/_services/token:sub": "repo:octo-org/octo-repo:ref:refs/heads/octo-branch" } }
"Condition": {
"StringEquals": {
"HOSTNAME/_services/token:aud": "sts.amazonaws.com",
"HOSTNAME/_services/token: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": { "HOSTNAME/_services/token:aud": "sts.amazonaws.com", "HOSTNAME/_services/token:sub": "repo:octo-org/octo-repo:environment:prod" } }
"Condition": {
"StringEquals": {
"HOSTNAME/_services/token:aud": "sts.amazonaws.com",
"HOSTNAME/_services/token: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)을 교환합니다.
사용 권한 설정 추가
작업 또는 워크플로 실행에는 GitHub의 OIDC 공급자가 모든 실행에 대한 JSON 웹 토큰을 만들 수 있는 id-token: write
가 있는 permissions
설정이 필요합니다. 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 토큰을 페치해야 하는 경우 워크플로 수준에서 사용 권한을 설정할 수 있습니다. 예시:
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 토큰에 액세스할 수 있습니다.
엔터프라이즈 또는 조직 외부에서 재사용 가능한 워크플로의 경우, 호출자 워크플로 수준 또는 재사용 가능한 워크플로를 호출하는 특정 작업에서 write
에 id-token
의 permissions
설정을 명시적으로 설정해야 합니다.
이렇게 설정하면 재사용 가능한 워크플로에서 생성된 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 }}/