GitHub Actions와 AWS 간 작업을 위한 OIDC 활용 임시 자격 증명 발급의 이해 및 방법

개요

본 문서는 GitHub actions에서 개발자가 AWS의 IAM Access Token을 발급받아 관리하지 않고 CI/CD 과정에서 짧은 시간 유효한 임시 토큰을 발급받아 사용하는 방식이 어떤 방식으로 이뤄지는지 설명한다.

자격 증명 획득 흐름

AWS에서는 자격 증명을 AWS 외부 애플리케이션에 장기간 보관하지 않는 것을 강력히 권장한다.

아무래도 권한 액세스 키를 관리해야하기 때문이다. 보안적으로 노출될 위험도 존재하고, 퇴사자가 발생하거나 정보를 알고있는 사람이 외부로 노출되었을 경우와 같은 불필요한 위험을 감수해야한다.

따라서 AWS에서는 OIDC 토큰을 발급받아 이를 AWS가 검증하여 단기 자격증명을 발급해주는 방식을 제공한다.

간단한 흐름은 다음과 같다.

Identity Provider에 대한 정보를 AWS에 저장한다.
Identity Provider는 OIDC ID Token을 발급한다.
AWS는 ID Token을 검증하고 이를 임시 자격증명으로 교환하여 반환해준다.

Github에서 설명하는 OIDC활용 flow

OIDC를 지원하는 클라우드 제공업체와 신뢰 연결을 구축한 후, 워크플로우를 구성하여 해당 클라우드 제공업체로부터 단기 접근 토큰을 요청할 수 있습니다.

클라우드 제공업체 내에서 OIDC 신뢰관계를 구축하여, 특정 Github 워크플로우가 정의된 클라우드 역할을 대신해 클라우드 액세스 토큰을 요청할 수 있도록 합니다.
작업이 실행될 때마다 Github의 OIDC 제공자가 자동으로 OIDC 토큰을 생성합니다. 이 토큰은 인증을 시도하는 특정 워크플로우에 대해 보안에 강하고 검증 가능한 신원을 확립하기 위한 여러 창구를 포함합니다.
워크플로우 작업의 단계나 행동은 Github의 OIDC 제공자에게 토큰을 요청할 수 있으며, 이를 클라우드 제공자에게 워크플로우 신원을 증명하는 증거로 제시할 수 있습니다.
클라우드 제공자가 토큰에 제시된 주장을 성공적으로 검증하면, 작업 기간 동안만 사용할 수 있는 단기 클라우드 액세스 토큰을 제공합니다.

자세한 절차

1. Github Actions 워크플로우 실행, OIDC 토큰 요청

Github Actions 워크플로가 시작되면, Github은 OIDC ID Token(JWT)을 발급할 수 있다.

이 토큰에는 실행 컨텍스트가 클레임으로 들어간다.

발급자, 대상, repo/branch/workflow, 만료 시간
iss, aud, sub, exp

토큰은 GitHub의 비밀키로 서명한다.

2. ID Token → AWS STS로 전송

워크플로는 발급받은 ID Token을 STS의 AssumeRoleWithWebIdentity API를 호출한다.

AWS STS(Security Token Service)는 보안 토큰을 생성하는 서비스이다.

AssumeRoleWithWebIdentity는 Web Identity Provider(예, 구글, 페이스북, 아마존 cognito 등) 외부 IdP를 통해 인증된 사용자에게 IAM Role을 임시로 Assume 할 수 있게 해준다.

3. AWS는 ID Token을 검증한다.

서명 검증: GitHub OIDC Provider의 JWKS로 JWT 서명 확인
- JWKS는 우리가 등록한 Issuer URL에 .well-known/openid-configuration 을 조회하여 가져온다.
- JWKS는 비밀키를 검증하기 위한 공개키 목록이다.
발급자 검증: iss == [https://token.actions.githubusercontent.com](https://token.actions.githubusercontent.com/)
대상 검증: aud가 IAM에 등록된 값과 동일한지 검증
조건 검증: IAM Trust Policy의 조건과 토큰 클레임이 일치

trust policy 예시

{
  "Effect": "Allow",
  "Principal": {
    "Federated": "arn:aws:iam::<ACCOUNT_ID>:oidc-provider/token.actions.githubusercontent.com"
  },
  "Action": "sts:AssumeRoleWithWebIdentity",
  "Condition": {
    "StringEquals": {
      "token.actions.githubusercontent.com:aud": "sts.amazonaws.com"
    },
    "StringLike": {
      "token.actions.githubusercontent.com:sub": "repo:org/repo:ref:refs/heads/main"
    }
  }
}

4. 임시 AWS 자격 증명 발급

모든 검증을 통과하면 STS가 임시 자격증명을 발급한다.

발급받은 후, AWS SDK/CLI는 이 자격증명을 활용해 API를 호출한다.

결과적으로 이룬 장점

장키 키 없음, 탈취될 가능성/관리에 드는 비용이 없다. (ex, 쿠팡 액세스 키 탈취)
임시 자격증명이다. → 시간이 매우 짧음
서명 기반 신원 검증 → JWT는 위조 불가

실제 AWS와 Github actions 설정

1. AWS IAM에서 Identity Provider를 설정한다.

provider url: Open ID Connect 토큰 provider의 url이다. 이는 github actions 공식 문서에 가면 나와있다.
audience는 토큰 발급을 위한 대상으로 jwt 내부 클레임에 포함될 정보다.
https://docs.github.com/ko/enterprise-cloud@latest/actions/how-tos/secure-your-work/security-harden-deployments/oidc-in-aws 두 값 모두 github 공식 문서에 나와있다.

2. AWS IAM Role 생성

IAM Role을 생성하고, 신뢰 정책을 만든다.

{
  "Effect": "Allow",
  "Principal": {
    "Federated": [1에서 만든 identity provider arn]
  },
  "Action": "sts:AssumeRoleWithWebIdentity",
  "Condition": {
    "StringEquals": {
      "token.actions.githubusercontent.com:aud": [1에서 넣은 audience]
    },
    "StringLike": {
      "token.actions.githubusercontent.com:sub": "repo:org/repo:ref:refs/heads/main"
    }
  }
}

federated에는 identity provider의 ARN을 넣는다.
aud는 앞에서 만든 것과 동일한 값을 넣는다.
sub는 위에서 설명한 것 처럼, “누구”인지 검증하기 위한 값으로, 우리 repo/branch/workflow를 작성한다.
repo:ORG-NAME/*: ORG 내에서는 모두 사용 가능
repo:ORG-NAME/REPO-NAME:* 저장소 내의 브랜치는 모두 사용 가능
repo:ORG-NAME/REPO-NAME:ref:refs/heads/BRANCH-NAME: 특정 브랜치에서만 사용 가능
repo:ORG-NAME/REPO-NAME:environment:ENVIRONMENT-NAME 특정 환경에서만 사용 가능

이제 생성한 Role에 Github actions에서 사용할 AWS 권한을 추가하면 된다.

3. Github Actions에서 사용하기

name: OIDC Test
on:
  push:
  workflow_dispatch:

permissions:
  id-token: write

jobs:
  access-s3:
    runs-on: ubuntu-latest
    steps:
      - name: Configure AWS Credentials
        uses: aws-actions/configure-aws-credentials@v4
        with:
          aws-region: ap-northeast-2
          role-to-assume: arn:aws:iam::252807701206:role/oidc-demo-role

permissions에 write 권한을 제공해 id token을 발급할 권한을 준다.
configure-aws-credentials에 role-to-assume을 앞에서 생성한 role의 ARN을 지정하면 된다.

정리

정리하면 우리가 AWS에 제공한 값을 aud와 sub 값이다.

aud는 github에서 생성한 id token의 서명을 검증하기 위함이다. 즉, id token의 위조가 불가능하게 된다. 반드시 github에서 만든 id token만 aws에서 검증을 통과한다.
sub는 github 중에서, 우리가 지정한 org/repo/branch가 일치하는지 검증하기 위함이다. 따라서 github이 발급했다고 하더라도, 우리가 지정한 레포가 아니라면 검증을 통과할 수 없고 접근이 불가능하다.

출처

'웹' 카테고리의 다른 글

GitHub actions runner 변경으로 인해 testcontainers 호환 트러블 슈팅 (0)	2026.02.19
OAuth 2.0 Authorization Code Grant 방식 (0)	2025.12.30
OAuth와 OIDC의 역사 (0)	2025.12.30
festabook의 TPS 기준 서버 및 MySQL 튜닝 (1)	2025.10.29
festabook MySQL 설정 튜닝 (0)	2025.10.29

개요

자격 증명 획득 흐름

Github에서 설명하는 OIDC활용 flow

자세한 절차

1. Github Actions 워크플로우 실행, OIDC 토큰 요청

2. ID Token → AWS STS로 전송

3. AWS는 ID Token을 검증한다.

4. 임시 AWS 자격 증명 발급

결과적으로 이룬 장점

실제 AWS와 Github actions 설정

1. AWS IAM에서 Identity Provider를 설정한다.

2. AWS IAM Role 생성

3. Github Actions에서 사용하기

정리

출처

'웹' 카테고리의 다른 글

티스토리툴바