Amazon Web Services에서 OpenID Connect 구성하기

워크플로우에서 OpenID Connect를 사용해 Amazon Web Services에 인증해보세요.

출처: 문서

본문

워크플로우에서 OpenID Connect를 사용해 Amazon Web Services에 인증할 수 있어요.

개요

OpenID Connect(OIDC)를 사용하면 GitHub Actions 워크플로우가 AWS 자격 증명을 장기 보존형 GitHub 시크릿으로 저장하지 않고도 Amazon Web Services(AWS)의 리소스에 접근할 수 있어요.

이 가이드는 AWS가 GitHub의 OIDC를 페더레이션 ID로 신뢰하도록 구성하는 방법을 설명하고, 토큰을 사용해 AWS에 인증하고 리소스에 접근하는 aws-actions/configure-aws-credentials용 워크플로우 예시를 포함합니다.

[!NOTE] AWS에서는 OIDC용 커스텀 클레임(claim) 지원을 사용할 수 없어요.

사전 요구 사항

GitHub가 OpenID Connect(OIDC)를 사용하는 방법, 그 아키텍처와 이점에 대한 기본 개념을 배우려면 OpenID Connect를 참고하세요.
진행하기 전에 보안 전략을 계획해 접근 토큰이 예측 가능한 방식으로만 할당되도록 해야 해요. 클라우드 공급자가 접근 토큰을 발급하는 방식을 제어하려면 신뢰할 수 없는 저장소가 클라우드 리소스에 대한 접근 토큰을 요청할 수 없도록 반드시 최소 하나 이상의 조건을 정의해야 합니다. 자세한 내용은 OpenID Connect reference를 참고하세요.
Dependabot 업데이트 작업을 위해 요청된 OIDC 토큰은 event_name 클레임이 dynamic입니다. 신뢰 정책이 GitHub Actions 워크플로우만 승인하도록 의도되었고 클라우드 공급자가 event_name에 대한 조건을 지원한다면, 워크플로우가 기대하는 이벤트 이름만 허용하세요. 자세한 내용은 OpenID Connect reference를 참고하세요.

AWS에 ID 공급자 추가하기

IAM에 GitHub OIDC 공급자를 추가하려면 AWS documentation을 참고하세요.

공급자 URL: https://token.actions.githubusercontent.com 사용
"Audience": 공식 액션을 사용 중이라면 sts.amazonaws.com 사용

역할과 신뢰 정책 구성하기

IAM에서 역할과 신뢰를 구성하려면 AWS 문서 Configure AWS Credentials for GitHub Actions와 Configuring a role for GitHub OIDC identity provider를 참고하세요.

[!NOTE] AWS Identity and Access Management(IAM)는 GitHub의 OIDC ID 공급자(IdP)를 신뢰하는 모든 역할의 신뢰 정책에서 IAM 조건 키 token.actions.githubusercontent.com:sub를 평가할 것을 권장합니다. 역할 신뢰 정책에서 이 조건 키를 평가하면 어떤 GitHub 액션이 역할을 수임(assume)할 수 있는지 제한됩니다.

신뢰 정책을 편집해 검증 조건에 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"
  }
}

2026년 7월 15일 이후에 생성되었거나 불변 subject 클레임(immutable subject claims)에 옵트인한 저장소의 경우, sub 클레임에는 불변의 소유자와 저장소 ID가 포함됩니다(GitHub Enterprise Server에서는 사용 불가). 신뢰 정책이 저장소에서 사용하는 형식과 일치하는지 확인하세요. 자세한 내용은 OpenID Connect reference를 참고하세요.

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

환경(environment)이 있는 워크플로우를 사용하면 sub 필드는 환경 이름을 참조해야 합니다: repo:ORG-NAME/REPO-NAME:environment:ENVIRONMENT-NAME. 자세한 내용은 OpenID Connect reference를 참고하세요.

[!NOTE] 워크플로우나 OIDC 정책에서 환경을 사용할 때는 추가 보안을 위해 환경에 보호 규칙(protection rules)을 추가하는 것을 권장합니다. 예를 들어 환경에 배포 규칙을 구성해 어떤 브랜치와 태그가 환경에 배포하거나 환경 시크릿에 접근할 수 있는지 제한할 수 있어요. 자세한 내용은 Managing environments for deployment를 참고하세요.

"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"
                }
            }
        }
    ]
}

GitHub Actions 워크플로우 업데이트하기

워크플로우를 OIDC용으로 업데이트하려면 YAML을 두 가지 변경해야 해요:

토큰에 대한 권한(permissions) 설정을 추가하세요.
aws-actions/configure-aws-credentials 액션을 사용해 OIDC 토큰(JWT)을 클라우드 접근 토큰으로 교환하세요.

권한 설정 추가하기

작업 또는 워크플로우 실행에는 GitHub의 OIDC 공급자가 매 실행마다 JSON Web Token을 만들 수 있도록 id-token: write가 있는 permissions 설정이 필요합니다.

[!NOTE] 워크플로우의 권한에 id-token: write를 설정해도 워크플로우가 리소스를 수정하거나 쓰기 권한을 얻는 것은 아닙니다. 대신 액션이나 단계를 위해 OIDC 토큰을 요청(가져오기)하고 사용(설정)할 수만 있게 해줍니다. 이 토큰은 이후 단기 접근 토큰으로 외부 서비스에 인증하는 데 사용됩니다.

필요한 권한, 구성 예시, 고급 시나리오에 대한 자세한 정보는 OpenID Connect reference를 참고하세요.

접근 토큰 요청하기

aws-actions/configure-aws-credentials 액션은 GitHub OIDC 공급자로부터 JWT를 받은 다음 AWS에 접근 토큰을 요청합니다. 자세한 내용은 AWS documentation을 참고하세요.

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 a static website using Amazon S3
# This workflow uses actions that are not certified by GitHub.
# They are provided by a third-party and are governed by
# separate terms of service, privacy policy, and support
# documentation.
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@v6
      - 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 }}/

Amazon Web Services에서 OpenID Connect 구성하기