[Error] Error: Could not assume role with OIDC: Not authorized to perform sts:AssumeRoleWithWebIdentity 오류

처음으로 AWS Lambda를 GitHub Actions를 통해 관리하기 위해 GitHub와 AWS를 연결하는 과정에서 오류가 발생했다.

이번에는 GitHub Actions가 AWS Lambda에 코드를 자동으로 배포할 수 있도록 GitHub OIDC와 IAM Role을 설정했다.

구성은 대략 다음과 같다.

GitHub Actions
      ↓
GitHub OIDC
      ↓
AWS STS
      ↓
IAM Role
      ↓
AWS Lambda

GitHub Actions가 AWS에 접근할 때 Access Key를 직접 저장하는 대신, GitHub의 OIDC 인증을 이용해서 AWS IAM Role을 임시로 사용할 수 있도록 구성했다.

1. 처음 설정한 Trust Policy

IAM Role의 Trust Policy(신뢰 정책)에 GitHub Actions를 허용하도록 설정했다.

처음에는 GitHub 저장소를 다음과 같은 형태로 작성했다.

{
  "StringLike": {
    "token.actions.githubusercontent.com:sub": "repo:사용자명/저장소명:*"
  }
}

 

쉽게 말하면 AWS에게 다음과 같이 알려준 것이다.

 

"이 GitHub 저장소에서 실행되는 GitHub Actions라면 이 IAM Role을 사용할 수 있도록 허용해줘."

 

StringLike를 사용했기 때문에 뒤쪽의 값은 *를 사용하여 유연하게 허용하도록 설정했다.

2. GitHub Actions 실행

설정을 완료한 후 GitHub Actions에서 AWS와 정상적으로 연결되는지 확인했다.

하지만 다음과 같은 오류가 발생했다.

Error: Could not assume role with OIDC:
Not authorized to perform sts:AssumeRoleWithWebIdentity

처음에는 YAML 설정이나 IAM Trust Policy 자체에 문제가 있다고 생각해서 여러 부분을 수정해봤다.

하지만 무엇이 정확히 잘못되었는지 알기 어려웠다.

3. CloudTrail에서 로그 확인

그러다가 AWS CloudTrail에서 실제 요청 기록을 확인해보기로 했다.

CloudTrail에서는 GitHub Actions가 AWS에 어떤 요청을 했는지 확인할 수 있었다.

여기서 중요한 정보를 발견했다.

GitHub Actions가 AWS에 전달한 OIDC 토큰의 sub 값과 내가 Trust Policy의 StringLike에 작성한 값이 서로 달랐다.

예를 들어 처음에는 다음과 같이 설정했다.

repo:사용자명/저장소명:*

그런데 실제 GitHub Actions가 전달한 sub는 다음과 같은 형태였다.

repo:사용자명@식별자/저장소명@식별자:ref:refs/heads/main

즉, 내가 예상했던 GitHub 저장소 식별자와 실제 GitHub가 OIDC 토큰에 넣어 전달한 sub 값의 형식이 달랐던 것이다.

4. 왜 오류가 발생했을까?

여기서 중요한 것은 sub가 무엇인지 이해하는 것이다.

sub는 OIDC 토큰 안에 들어 있는 **"이 인증 요청이 누구로부터 왔는지 나타내는 식별 정보"**라고 생각하면 된다.

AWS는 Trust Policy를 확인하면서 다음과 같이 판단한다.

GitHub Actions
      ↓
OIDC Token 전달
      ↓
sub 확인
      ↓
Trust Policy의 조건과 비교
      ↓
일치하면 → IAM Role 사용 허용
불일치하면 → AccessDenied

 

이번에는 Trust Policy에서 허용한 sub와 실제 GitHub Actions가 전달한 sub가 일치하지 않았기 때문에

AWS가 IAM Role을 빌려주는 단계에서 거부한 것이다.

따라서 Lambda의 코드나 Lambda 자체의 문제가 아니었다.

5. 실제 전달된 값을 기준으로 수정

원인을 확인한 후 CloudTrail에서 확인한 실제 sub 형식을 기준으로 Trust Policy의 조건을 수정했다.

처음에는:

repo:사용자명/저장소명:*

으로 설정했지만, 실제 GitHub Actions가 전달하는 값은:

repo:사용자명@식별자/저장소명@식별자:ref:refs/heads/main

 

형태였기 때문에 이를 기준으로 수정했다.

수정 후에는 GitHub Actions가 AWS IAM Role을 정상적으로 Assume할 수 있었고, 이후 Lambda 코드 배포도 정상적으로 동작했다.

결국 이번 오류의 핵심은 다음과 같다.

 

잘못된 sub 조건
        ↓
GitHub OIDC 인증
        ↓
Trust Policy와 sub 불일치
        ↓
AssumeRoleWithWebIdentity 실패
        ↓
AccessDenied

 

수정 후에는:

GitHub OIDC 인증
        ↓
Trust Policy의 sub 조건과 일치
        ↓
IAM Role Assume 성공
        ↓
Lambda 권한 확인
        ↓
Lambda 배포 성공

6. 이번에 배운 점

이번 경험을 통해 AWS에서 발생하는 인증 및 권한 문제를 해결할 때는 단순히 설정 화면만 계속 수정하기보다 실제 요청이 어떻게 들어왔는지 로그를 확인하는 것이 중요하다는 것을 배웠다.

 

특히 AWS에서 문제가 발생했을 때는 CloudTrail을 먼저 확인해보는 습관을 들여야겠다고 느꼈다.

이번 경우에도 처음에는 YAML이나 IAM 설정을 계속 의심했지만, CloudTrail을 확인한 뒤에야 실제로 GitHub Actions가 AWS에 전달한 값과 Trust Policy에 설정한 값이 다르다는 사실을 확인할 수 있었다.

 

정리

GitHub Actions와 AWS를 OIDC로 연결할 때 오류가 발생한다면, 먼저 CloudTrail에서 AssumeRoleWithWebIdentity 요청과 실제 OIDC sub 값을 확인해보자.