GitHub Actions에서 AWS에 가장 안전하게 로그인하는 방법

GitHub Actions 워크플로를 사용해서 AWS에 어플리케이션을 배포할 때, AWS 계정에 로그인(액세스)하는 방법은 일반적으로 두 가지입니다.

• IAM User의 Access Key와 Secret Access Key를 발급받아 GitHub Actions secrets에 등록해서 사용하기
• GitHub OIDC provider를 사용해서 AWS IAM Role를 위임(Assume)받기

1번 방법은 쉽고, 간단하고, 직관적입니다. 다만 Access Key와 Secret Access Key는 사용자가 직접 관리해야 하는 비밀 값이기에, 사용자의 실수로 비밀 값이 유출될 가능성이 있습니다. 만약 비밀 값이 유출된다면 큰 보안 사고로 이어질 우려가 있습니다.

2번 방법은 1번 방법보다는 번거롭지만, 매우 안전합니다. Access Key와 Secret Access Key가 필요하지 않기 때문에 비밀 값이 유출될 걱정이 전혀 없습니다. 워크플로가 실행될 때마다 AWS로부터 매우 짧은 수명을 가진 토큰을 발급받아 워크플로 내에서만 사용하기 때문에 토큰이 유출되어 보안 사고로 이어질 가능성도 거의 없습니다.

또 2번 방법은 1번 방법보다 약간 더 번거로울 뿐, 5분 이내에 구성을 끝낼 수 있을 정도로 쉽고 간단합니다. 그럼 우선 빠르게 구성해 보고, 자세한 동작 구조를 알아보겠습니다.

5분만에 구성하기

Identity provider 생성

우선 AWS 콘솔에서 IAM 대쉬보드에 접속합니다.

왼쪽의 Identity providers 메뉴를 클릭하고, 우측 상단의 Add provider 버튼을 클릭합니다.

아래와 같이 설정합니다.

• Provider type: OpenID Connect
• Provider URL: https://token.actions.githubusercontent.com
• Audience: sts.amazonaws.com

모두 입력했다면 Get thumbprint 버튼을 클릭하고, Add provider 버튼을 클릭해 provider를 생성합니다.

IAM Role 생성

다음으로는 워크플로가 위임받을 AWS IAM Role을 생성해야 합니다. IAM 대쉬보드의 왼쪽 메뉴에서 Roles 메뉴를 클릭한 뒤, 우측 상단의 Create role 버튼을 클릭합니다.

아래와 같이 설정합니다.

• Trusted entity type: Web Identity
• Identity provider: token.actions.githubusercontent.com 선택
• Audience: http://sts.amazonaws.com 선택
• GitHub organization: IAM Role을 위임받을 GitHub 계정 이름(username) 또는 organization 이름을 입력합니다.
• (선택) GitHub repository: IAM Role을 위임받을 레포지토리 이름을 입력합니다. 입력하지 않을 경우 계정(또는 organization)의 모든 레포지토리에서 IAM Role을 위임받을 수 있습니다.
• (선택) GitHub branch: IAM Role을 위임받을 브랜치 이름을 입력합니다. 입력하지 않을 경우 레포지토리의 모든 브랜치에서 IAM Role을 위임받을 수 있습니다.

모두 입력했다면 Next 버튼을 클릭합니다.

이후 IAM Role에 권한을 할당하고, Role 이름을 입력한 뒤 Role을 생성합니다.

Role을 생성한 뒤에는 Role의 ARN을 메모해 둡니다.

GitHub Actions에서 IAM Role 위임받기

이제 바로 위에서 생성한 IAM Role을 GitHub Actions 워크플로에서 위임받아 사용할 수 있습니다.

GitHub Actions 워크플로 파일을 아래처럼 작성해서 사용할 수 있습니다.

name: Deploy to Amazon ECS

on:
  push:
    branches:
    - main

permissions:
  id-token: write
  contents: read

jobs:
  deploy:
    name: Deploy
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

	    - name: Configure AWS credentials
        uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: # 이곳에 IAM Role ARN을 입력합니다.
          aws-region: # 이곳에 AWS 리전을 입력합니다. 서울 리전은 ap-northeast-2 입니다.

      - name: Login to Amazon ECR
        id: login-ecr
        uses: aws-actions/amazon-ecr-login@v2

			# ...

중요한 부분은 두 부분입니다.

• 아래 설정을 추가해야 합니다.

permissions:
  id-token: write  # 워크플로가 AWS로부터 OIDC 토큰을 가져오는 것을 허용합니다.
  contents: read  # 워크플로 내에서 레포지토리 및 커밋 데이터를 가져오는 것을 허용합니다.

• aws-actions/configure-aws-credentials@v4 액션을 이용해서 AWS로부터 IAM Role을 위임받아야 합니다.
  • role-to-assume 항목에는 IAM Role의 ARN을 입력합니다.
  • aws-region 항목에는 워크플로에서 사용할 AWS 리소스가 위치한 리전을 입력합니다.

- name: Configure AWS credentials
  uses: aws-actions/configure-aws-credentials@v4
  with:
    role-to-assume: # 이곳에 IAM Role ARN을 입력합니다.
    aws-region: # 이곳에 AWS 리전을 입력합니다. 서울 리전은 ap-northeast-2 입니다.