Skip to main content
설명서에 자주 업데이트를 게시하며 이 페이지의 번역이 계속 진행 중일 수 있습니다. 최신 정보는 영어 설명서를 참조하세요.

Amazon Web Services에서 OpenID Connect 구성

워크플로 내에서 OpenID 커넥트를 사용하여 Amazon Web Services로 인증합니다.

개요

OIDC(OpenID Connect)를 사용하면 GitHub Actions 워크플로가 AWS 자격 증명을 수명이 긴 GitHub 비밀로 저장할 필요 없이 AWS(Amazon Web Services)의 리소스에 액세스할 수 있습니다.

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

필수 조건

  • GitHub가 OIDC(OpenID Connect)를 사용하는 방법과 아키텍처 및 이점에 대한 기본 개념을 알아보려면 “OpenID Connect를 사용한 보안 강화 정보”를 참조하세요.

  • 계속하기 전에 액세스 토큰이 예측 가능한 방식으로만 할당되도록 보안 전략을 계획해야 합니다. 클라우드 공급자가 액세스 토큰을 발급하는 방법을 제어하려면 신뢰할 수 없는 리포지토리가 클라우드 리소스에 대한 액세스 토큰을 요청할 수 없도록 하나 이상의 조건을 정의해야 합니다. 자세한 내용은 “클라우드를 사용하여 OIDC 신뢰 구성”을 참조하세요.

AWS에 ID 공급자 추가

GitHub OIDC 공급자를 IAM에 추가하려면 AWS 설명서를 참조하세요.

  • 공급자 URL: https://token.actions.githubusercontent.com 사용
  • “대상 그룹”의 경우: 공식 작업을 사용하는 경우 sts.amazonaws.com을 사용합니다.

역할 및 신뢰 정책 구성

IAM에서 역할 및 신뢰를 구성하려면 AWS 설명서에서 “역할 가정”“웹 ID 또는 OpenID Connect 페더레이션에 대한 역할 만들기”를 참조하세요.

신뢰 정책을 편집하여 유효성 검사 조건에 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"
  }
}

다음 예제 StringLike 에서는 을 와일드카드 연산자(*)와 함께 사용하여 조직 및 리포지토리의 분기, 끌어오기 요청 병합 분기 또는 환경이 AWS에서 octo-org/octo-repo 역할을 맡을 수 있도록 합니다.

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 관련 permissions 설정이 필요합니다. id-token에 대한 permissions 설정이 read 또는 none으로 설정된 경우 OIDC JWT ID 토큰을 요청할 수 없습니다.

id-token: write 설정을 통해 다음 방법 중 하나를 사용하여 GitHub의 OIDC 공급자에서 JWT를 요청할 수 있습니다.

  • 실행기(ACTIONS_ID_TOKEN_REQUEST_URLACTIONS_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

워크플로의 요구 사항에 따라 여기에서 추가 권한을 지정해야 할 수 있습니다.

액세스 토큰 요청

aws-actions/configure-aws-credentials 작업은 GitHub OIDC 공급자로부터 JWT를 받은 다음 AWS에서 액세스 토큰을 요청합니다. 자세한 내용은 AWS 설명서를 참조하세요.

  • <example-bucket-name>: S3 버킷의 이름을 여기에 추가합니다.
  • <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 }}/