[GitHub Actions][OIDC] subject 템플릿 변경 뒤 AWS trust policy와 실제 claims 로그를 같이 검증하는 법

IT 리서치 노트

[GitHub Actions][OIDC] subject 템플릿 변경 뒤 AWS trust policy와 실제 claims 로그를 같이 검증하는 법

GitHub Actions OIDC에서 subject 템플릿을 바꾼 뒤 AWS role assumption이 흔들리는 경우가 있다. 2026년 7월 2일 기준 GitHub 공식 문서를 다시 보면, AWS는 GitHub OIDC의 custom claim을 직접 매칭하지 못하고, reusable workflow 쪽 문서는 `job_workflow_ref`와 `sub` customization을 함께 설명한다. 이 글은 템플릿 변경 뒤 AWS trust policy와 실제 claim 로그를 어떤 순서로 같이 확인해야 하는지 정리한 것이다.

목차

1. 개요
2. 어디서 실제로 막히는가
3. 실무에서 적용하는 순서
4. 공식 문서와 예시 화면으로 확인하기
5. 주의사항과 리스크
6. 결론
7. 참고 링크

1. 개요

결론부터 말하면 GitHub에서 subject 템플릿을 바꾼 뒤 AWS가 계속 실패하면, 먼저 실제 JWT의 sub를 출력하고 그다음 AWS trust policy의 token.actions.githubusercontent.com:sub 조건과 한 줄씩 비교해야 한다. AWS는 custom claim을 직접 읽지 못하므로 job_workflow_ref를 trust policy로 곧바로 옮기는 접근보다, 템플릿 변경 뒤 실제 sub 문자열이 어떻게 바뀌었는지 확인하는 편이 빠르다.

이미 OIDC claims를 먼저 검증하는 글이 GitHub 쪽 선행 검증을 다뤘다면, 이번 글은 그 다음 단계인 AWS 조건식 대조다. 또 reusable workflow와 AWS trust policy 글은 trust policy 설계 쪽이고, 이번 글은 변경 후 운영 검증 쪽이라고 보면 된다.

2. 어디서 실제로 막히는가

실무에서 가장 자주 생기는 혼동은 세 가지다. 첫째, subject 템플릿에 job_workflow_ref를 넣었으니 AWS에서도 그 claim을 직접 읽을 수 있다고 생각한다. 둘째, GitHub REST API 호출은 성공했는데 실제 토큰의 sub를 확인하지 않고 바로 AWS role assumption만 재시도한다. 셋째, environment를 붙이며 기본 sub 구조가 바뀌었는데 AWS 조건식은 예전 branch 기준 그대로 둔다.

GitHub의 AWS OIDC 가이드는 AWS에서 custom claim 직접 매칭을 지원하지 않는다고 적고 있다. 반면 reusable workflow 문서는 job_workflow_ref와 subject customization을 함께 보여 준다. 이 둘을 같이 읽으면, GitHub 쪽에서 workflow 경계를 표현하는 값과 AWS에서 실제로 비교하는 값이 서로 다르다는 점이 드러난다.

즉 실패를 좁히는 기준은 'custom claim을 넣었는가'가 아니라 '최종 sub가 AWS가 기대하는 문자열과 같은가'다. 템플릿 변경 뒤 이 비교를 건너뛰면 GitHub 설정, OIDC claim, AWS 조건식 중 어디가 어긋났는지 바로 설명할 수 없다.

• 증상: subject 템플릿 변경 뒤 AWS assume-role만 계속 실패한다.
• 실패: AWS가 custom claim을 직접 읽을 것이라고 가정한다.
• 막힘: REST API 성공만 보고 실제 sub 문자열을 확인하지 않는다.
• 누락: environment나 reusable workflow 도입 뒤 trust policy를 다시 비교하지 않는다.

증상	먼저 볼 곳	판단 기준
JWT는 나오는데 AWS login 실패	현재 sub와 AWS StringEquals	실제 subject 문자열이 완전히 같은지 본다
reusable workflow 경계가 흔들린다	job_workflow_ref와 템플릿 포함 항목	그 값이 sub에 반영됐는지 본다
environment 도입 후부터 실패	기본 sub 형식 변화	branch 문자열을 여전히 비교 중인지 본다

3. 실무에서 적용하는 순서

운영에서는 네 단계로 보면 충분하다. 먼저 OIDC debugger로 현재 JWT의 aud와 sub를 출력한다. 두 번째로 GitHub 템플릿이 어떤 claim을 sub에 넣도록 설계됐는지 확인한다. 세 번째로 AWS trust policy의 StringEquals와 실제 sub를 한 줄씩 비교한다. 마지막으로 같은 workflow에서 다시 assume-role을 실행해 claim 발급과 조건식 매칭을 분리해 본다.

1. OIDC debugger로 현재 aud, sub를 출력한다.
2. GitHub subject 템플릿과 포함 claim을 다시 본다.
3. AWS trust policy 문자열과 실제 sub를 대조한다.
4. 같은 실행에서 assume-role을 다시 검증한다.

AWS trust policy 예시

"Condition": {
  "StringEquals": {
    "token.actions.githubusercontent.com:aud": "sts.amazonaws.com",
    "token.actions.githubusercontent.com:sub": "repo:owner/app:environment:prod:job_workflow_ref:owner/platform/.github/workflows/deploy.yml@refs/heads/main"
  }
}

핵심은 GitHub에서 표현한 경계가 실제 AWS 비교 문자열로 어떻게 바뀌는지 명시적으로 남기는 것이다. custom claim 지원 여부를 먼저 확인하고, 그다음에만 AWS 조건식을 건드리면 불필요한 재시도를 줄일 수 있다.

4. 공식 문서와 예시 화면으로 확인하기

첫 화면은 GitHub의 AWS OIDC 가이드 핵심 구간이다. 여기서 먼저 확인해야 하는 점은 AWS가 GitHub OIDC의 custom claim을 직접 비교하지 못한다는 사실이다.

GitHub의 AWS OIDC 가이드는 AWS에서 custom claim 직접 매칭이 불가능하다고 분명히 적고 있다.

즉 `job_workflow_ref`를 trust policy에서 바로 비교할 수 있다고 가정하면 방향이 틀어진다. AWS 쪽에서는 결국 `token.actions.githubusercontent.com:sub`가 어떤 문자열로 보이는지부터 다시 확인해야 한다.

두 번째 자료는 reusable workflow용 trust 경계를 다루는 GitHub 문서다. 문서는 reusable workflow를 좁히고 싶다면 `job_workflow_ref`를 고려해야 한다고 설명한다.

GitHub는 reusable workflow trust 경계에서 `job_workflow_ref`와 subject customization을 함께 보라고 안내한다.

하지만 AWS가 custom claim을 직접 읽지 못하므로, 이 정보는 GitHub 쪽 subject 템플릿 설계와 claim 검증 단계에서 먼저 써야 한다. 그대로 AWS 조건식에 옮기려 하면 실패 원인을 잘못 잡기 쉽다.

세 번째 화면은 OIDC reference의 디버깅 구간과 `sub` customization 예시다. subject 템플릿을 바꾼 뒤에는 추측하지 말고 실제 JWT에 어떤 `sub`가 들어왔는지 확인해야 한다.

GitHub OIDC reference는 claim 디버깅과 `sub` customization request body를 같이 보여 준다.

이 단계가 필요한 이유는 REST API 요청 본문이 맞아도, 실제로 적용된 `sub` 문자열이 AWS trust policy의 `StringEquals`와 다를 수 있기 때문이다. 템플릿 변경 후 검증이 빠지면 GitHub 쪽과 AWS 쪽 중 어디가 어긋났는지 설명하기 어려워진다.

네 번째 자료는 `sub` 문자열과 AWS trust policy를 대조하는 표다. GitHub 템플릿이 바뀐 뒤에는 현재 claim과 role condition을 한 줄씩 맞춰 보는 편이 가장 빠르다.

현재 `sub`와 AWS `StringEquals` 조건을 같은 표에서 대조하면 실패 지점을 좁히기 쉽다.

이미 OIDC claims를 먼저 검증하는 글을 읽었다면, 이 표는 그 다음 단계인 AWS 조건식 대조판이다. 또 reusable workflow와 AWS trust policy 글을 운영 검증 쪽으로 다시 끌어온 형태라고 보면 된다.

다섯 번째 자료는 실제 검증 메모 예시다. claim 출력과 AWS trust policy 검토를 한 번의 배포 로그에 같이 남기면, 템플릿 변경 직후 문제를 다시 재현하지 않아도 된다.

claim 로그와 trust policy 비교 메모를 같은 블록에 남기면 템플릿 변경 직후 진단이 쉬워진다.

이 메모가 없으면 `id-token: write` 문제인지, GitHub 템플릿 문제인지, AWS 조건식 문제인지 다시 세 갈래로 좁혀야 한다. 검증 비용을 줄이려면 변경 직후 한 번의 로그에 세 값을 함께 남기는 편이 낫다.

마지막 자료는 템플릿 변경 뒤 검증 순서다. 현재 claim 확인, AWS 지원 범위 확인, subject 문자열 대조, role assumption 재실행을 순서대로 두면 수정 범위가 작아진다.

subject 템플릿 변경 뒤 검증 순서는 GitHub 설정과 AWS trust policy를 같은 흐름으로 묶는다.

이 순서를 따르면 기존 GitHub OIDC 클러스터 글들을 각각 다른 역할로 다시 연결할 수 있다. claims 디버깅, custom subject 설계, reusable workflow trust 범위를 같은 체인으로 엮는 허브 역할도 해 준다.

5. 주의사항과 리스크

첫 번째 리스크는 GitHub 템플릿만 바꾸고 AWS 조건식을 옛 문자열로 두는 것이다. 두 번째 리스크는 현재 sub를 출력하지 않은 채 reusable workflow 경계만 추측으로 고치는 것이다. 세 번째 리스크는 AWS가 custom claim을 직접 읽는다고 생각해 trust policy를 잘못 쓰는 것이다.

운영 메모에는 최소한 현재 aud, 현재 sub, AWS trust policy의 기대 문자열을 함께 남기는 편이 좋다. 이 셋이 있으면 템플릿 변경 직후에도 실패 원인을 다시 재현하지 않고 설명할 수 있다.

• AWS는 GitHub custom claim을 직접 매칭하지 못한다.
• 최종 sub 문자열이 trust policy와 같아야 한다.
• JWT 발급 성공과 role assumption 성공은 서로 다른 단계다.

6. 결론

GitHub Actions OIDC에서 subject 템플릿을 바꾼 뒤 AWS가 실패하면, 실제 claim 로그와 trust policy를 같은 표로 다시 맞춰 보는 편이 가장 빠르다. AWS가 custom claim을 직접 읽지 못한다는 전제를 먼저 두고, 템플릿 변경 뒤 최종 sub가 어떻게 변했는지 확인해야 역할 분담이 선명해진다.

• claim을 먼저 출력한다.
• 그다음 AWS 문자열과 대조한다.
• reusable workflow 경계는 sub 기준으로 검증한다.

조직 단위 rollout을 준비 중이라면 organization template를 repo에 opt-in하기 전에 현재 sub 형식과 immutable subject 시점을 같이 검증하는 글을 먼저 보고 온 뒤, 여기서 실제 claims 로그와 AWS trust policy를 대조하는 편이 순서가 더 자연스럽다.

7. 참고 링크

1. https://docs.github.com/en/actions/how-tos/secure-your-work/security-harden-deployments/oidc-in-aws
2. https://docs.github.com/en/actions/how-tos/secure-your-work/security-harden-deployments/oidc-with-reusable-workflows
3. https://docs.github.com/en/actions/reference/security/oidc
4. https://docs.github.com/en/rest/actions/oidc#set-the-customization-template-for-an-oidc-subject-claim-for-a-repository