[GitHub Actions][OIDC] use_default는 false인데 include_claim_keys와 실제 subject가 어긋날 때 어느 API 응답과 trust policy부터 먼저 맞추나

IT 리서치 노트

[GitHub Actions][OIDC] use_default는 false인데 include_claim_keys와 실제 subject가 어긋날 때 어느 API 응답과 trust policy부터 먼저 맞추나

GitHub Actions OIDC를 AWS에 붙여 둔 팀에서 `use_default`를 `false`로 바꾸고 `include_claim_keys`까지 손봤는데도 실제 subject가 기대와 다르게 보이는 경우가 있다. 2026년 7월 20일 KST 기준 GitHub 공식 문서를 다시 보면 이 문제는 custom template 한 줄보다 저장소 기본 sub 형식, immutable subject, REST API 응답, AWS trust policy가 서로 다른 층으로 엮여 있다. 이 글은 `use_default=false`인데도 actual subject가 어긋날 때 어느 API 응답과 trust policy부터 먼저 맞추는 편이 빠른지 정리한 것이다.

목차

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

1. 개요

결론부터 말하면 use_default=false만으로 기대한 subject 형식이 자동 보장되지는 않는다. 먼저 저장소가 name 기반 기본 형식을 쓰는지, immutable subject가 이미 켜졌는지, 그리고 actual token의 sub가 무엇인지부터 확인해야 한다.

그다음에야 GitHub REST API의 include_claim_keys와 AWS trust policy 문자열을 맞추는 순서가 된다. AWS는 custom claims를 직접 해석하지 않으므로, 결국 cloud-side에서 비교되는 것은 actual subject와 trust policy 조건이다.

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

현장에서 자주 생기는 오해는 두 가지다. 첫째, use_default를 false로 바꾸면 원하는 claim 구조가 그대로 actual subject에 반영될 것이라고 생각한다. 둘째, include_claim_keys를 늘렸으니 AWS trust policy도 자연스럽게 맞아질 것이라고 본다.

하지만 GitHub 문서는 2026년 7월 15일 이후 저장소와 immutable subject opt-in 저장소에서 기본 repo 식별부가 달라질 수 있다고 적고, 같은 문서에서 immutable subject 저장소는 owner_id와 repo_id를 빼지 못한다고 설명한다. 여기에 AWS의 custom claims 미지원까지 겹치면, GitHub 쪽 설정과 cloud 쪽 문자열이 서로 다른 레이어라는 점이 분명해진다.

• 증상: use_default=false인데도 AWS role assume이 같은 sub mismatch로 실패한다.
• 실패: include_claim_keys만 보고 immutable 기본 형식을 잊는다.
• 막힘: actual token의 sub 예시를 남기지 않고 API 응답만 본다.
• 누락: AWS가 custom claims를 직접 지원하지 않는다는 전제를 빼먹는다.

질문	GitHub에서 보는 값	AWS에서 보는 값
기본 sub 형식이 무엇인가	immutable subject 여부, 저장소 생성 시점	실제 sub 문자열
template가 어떻게 바뀌었나	use_default, include_claim_keys	policy 조건 갱신 필요 여부
cloud가 무엇을 읽나	GitHub subject customization 결과	actual sub와 aud만 우선 비교

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

실무 점검 순서는 다섯 단계면 충분하다. 먼저 저장소가 immutable subject 기본값 대상인지 적는다. 두 번째로 저장소 REST API에서 use_default, include_claim_keys, use_immutable_subject를 함께 조회한다. 세 번째로 실제 OIDC token의 sub 예시를 로그에 남긴다. 네 번째로 AWS trust policy의 sub 조건과 wildcard 범위를 비교한다. 마지막으로 필요하면 organization template opt-in 상태를 따로 확인한다.

1. 저장소가 immutable 기본값 대상인지 확인한다.
2. REST API에서 use_default, include_claim_keys, use_immutable_subject를 같이 본다.
3. actual token의 sub 예시를 runbook에 남긴다.
4. AWS trust policy의 sub 조건을 actual subject와 비교한다.
5. 필요하면 org template opt-in 상태를 분리해서 본다.

이 순서를 지키면 GitHub 쪽 template 문제와 AWS 쪽 문자열 문제를 섞지 않게 된다. 특히 actual subject를 로그로 남기지 않은 채 include_claim_keys만 여러 번 바꾸는 패턴을 줄일 수 있다.

gh api repos/OWNER/REPO/actions/oidc/customization/sub   --jq '{use_default, include_claim_keys, use_immutable_subject}'

# compare this with an actual token sample and AWS trust policy
"token.actions.githubusercontent.com:sub": "repo:ORG@OWNER_ID/REPO@REPO_ID:ref:refs/heads/main"

이미 environment를 붙였는데 sub claim이 그대로일 때 보는 글이 workflow 기대값을 다뤘다면, 이번 글은 그다음 단계인 API 응답값과 actual subject 불일치를 다루는 triage 메모라고 보면 된다.

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

첫 화면에서 먼저 봐야 할 문장은 2026년 7월 15일 전후의 기본 sub 형식 차이다. 같은 organization 안에서도 저장소 생성 시점과 opt-in 여부가 다르면 actual subject가 달라질 수 있다.

GitHub OIDC reference는 2026년 7월 15일 이전 저장소가 opt-in 전까지 예전 형식을 유지한다고 설명한다.

이 전제를 빼고 use_default만 보면 API 응답은 맞는데 trust policy가 어긋나는 이유를 놓치기 쉽다. 먼저 저장소 기본 sub 형식이 name 기반인지 immutable 기반인지부터 구분해야 한다.

두 번째 자료는 include_claim_keys를 넣어도 immutable 저장소의 repo segment에서 owner_id와 repo_id를 뺄 수 없다는 대목이다. 여기서 많은 팀이 custom template와 immutable default를 같은 층으로 오해한다.

GitHub는 immutable subject 저장소에서 owner_id와 repo_id가 sub의 repo segment에 항상 남는다고 적는다.

즉 include_claim_keys를 environment나 repository_visibility 위주로 바꿔도 기본 repo 식별부는 그대로 유지된다. trust policy가 예전 name 기반 문자열을 기대하면 use_default가 false여도 실제 subject와 계속 어긋난다.

세 번째 화면은 저장소 OIDC REST API 응답에서 어떤 필드를 같이 읽어야 하는지 보여 준다. use_default만 단독으로 보지 말고 include_claim_keys와 use_immutable_subject를 한 세트로 적어 두는 편이 안전하다.

GitHub Actions OIDC REST API는 use_default, include_claim_keys, use_immutable_subject를 함께 돌려준다.

실무에서는 이 세 값과 실제 sub 예시를 같은 runbook에 붙이면 증상이 빨리 갈린다. GitHub 쪽 템플릿 상태와 AWS 쪽 trust policy 문자열을 따로 보관해야 하는 이유도 여기서 나온다.

네 번째 자료는 AWS 한계다. GitHub에서 subject customization을 세밀하게 설계해도 AWS가 custom claims 자체를 읽어 주는 구조는 아니다.

GitHub의 AWS OIDC 가이드는 AWS에서 custom claims 지원이 없다고 명시한다.

그래서 AWS에서는 claim을 더 늘리는 접근보다 actual subject와 trust policy 문자열을 먼저 맞추는 편이 현실적이다. include_claim_keys drift 문제도 결국 cloud-side 문자열 매칭으로 돌아온다.

마지막 표는 use_default가 false인데 subject가 기대와 다를 때 어디를 먼저 비교해야 하는지 정리한 것이다. 저장소 기본 형식, REST 응답, actual token, trust policy를 한 장에 놓아야 각 층이 섞이지 않는다.

use_default false와 include_claim_keys drift를 AWS trust policy 기준으로 분리하는 점검표다.

이미 name 기반 sub와 immutable subject를 언제 나누는지 정리한 글이 더 넓은 분기였다면, 이번 글은 그 다음 단계인 REST 응답값과 actual subject 불일치 triage다.

5. 주의사항과 리스크

첫 번째 리스크는 use_default=false를 보고 기본 repo 식별부도 완전히 커스텀된다고 오해하는 것이다. 두 번째는 immutable subject가 이미 켜진 저장소에 예전 name 기반 trust policy를 그대로 두는 것이다. 세 번째는 AWS가 custom claims를 읽지 않는데도 cloud-side ABAC를 과하게 설계하는 것이다.

운영 전에는 저장소 생성일, immutable subject 여부, REST 응답 3개 필드, actual sub 예시, trust policy 문자열을 한 문서에 붙여 두는 편이 좋다. 그래야 rename, transfer, template opt-in, workflow 변경이 생겨도 어디부터 다시 봐야 하는지 빨리 갈린다.

• use_default는 템플릿 적용 여부지, immutable 기본 형식 자체를 지우는 스위치가 아니다.
• AWS에서는 custom claims보다 actual subject와 trust policy alignment가 먼저다.
• actual token 예시를 남기지 않으면 API 응답 해석과 cloud-side 증상이 계속 엇갈린다.

6. 결론

GitHub Actions OIDC에서 use_default=false인데도 actual subject가 기대와 어긋나면 먼저 REST API 필드와 actual token을 붙여 놓고 본다. 그다음에야 AWS trust policy를 맞추는 순서가 된다.

같은 GitHub OIDC AWS 흐름에서 더 넓은 분기를 먼저 정리하고 싶다면 repo 이름 기반 sub와 immutable subject 분기 글, template opt-in 글, claim 검증 글을 같이 보면 좋다.

특히 저장소 rename이나 transfer 직후부터 AWS trust policy가 갑자기 깨졌다면 이번에 정리한 immutable subject 전환과 교체 순서 글로 이어서 보면 repo slug가 아니라 owner_id·repo_id 축으로 무엇이 바뀌고 무엇이 그대로 남는지 빠르게 구분할 수 있다.

7. 참고 링크

1. https://docs.github.com/actions/reference/openid-connect-reference
2. https://docs.github.com/en/rest/actions/oidc
3. https://docs.github.com/en/actions/how-tos/secure-your-work/security-harden-deployments/oidc-in-aws