[GitHub Actions][OIDC] enterprise custom issuer 뒤 AWS trust policy에서 sub 조건과 repo_property 확장을 어느 로그부터 같이 남기나

IT 리서치 노트

[GitHub Actions][OIDC] enterprise custom issuer 뒤 AWS trust policy에서 sub 조건과 repo_property 확장을 어느 로그부터 같이 남기나

GitHub Actions OIDC에서 enterprise custom issuer를 켠 뒤 AWS trust를 더 좁히려 하면 많은 팀이 repo_property를 바로 정책식에 넣고 싶어진다. 하지만 2026년 8월 11일 기준 GitHub 공식 문서를 다시 보면 AWS는 custom claims 지원이 없고, trust의 첫 anchor는 여전히 subject와 audience 쪽에 가깝다. 이 글은 enterprise custom issuer 뒤 AWS trust policy에서 sub 조건과 repo_property 확장을 어느 로그부터 같이 남기는 편이 incident 분리를 빠르게 만드는지 정리한 것이다.

목차

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

1. 개요

결론부터 말하면 AWS branch에서는 issuer·audience, 실제 sub, repo_property included claims, role policy diff 순으로 로그를 남기는 편이 맞다. repo_property는 바로 trust anchor라기보다 evidence 층으로 먼저 읽고, AWS trust의 첫 경계는 sub anchor로 고정하는 편이 더 안전하다.

즉 이 문제는 repo_property를 지원하느냐의 이분법보다 '어떤 값은 provider trust anchor이고 어떤 값은 incident evidence인가'를 분리하는 문제에 가깝다.

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

현장에서 자주 터지는 실수는 세 가지다. 첫째, custom issuer를 켠 직후 sub anchor를 다시 확인하지 않고 repo_property inclusion부터 본다. 둘째, AWS trust policy 오류와 GitHub 토큰 included claims 오류를 같은 ticket 문장으로 적는다. 셋째, rerun 결과를 남기지 않고 role trust policy를 계속 넓혀 가며 증거를 잃는다.

GitHub OIDC 개요와 enterprise REST 문서는 custom issuer와 claim inclusion 층을, OIDC reference는 repo_property 같은 included claims 층을, AWS deployment hardening 문서는 trust policy 기본 구조를 설명한다. 이 문서들을 같이 읽으면 AWS branch에서 가장 먼저 고정해야 하는 값과, 나중에 증거로 남겨야 하는 값이 다르다는 점이 보인다.

실무에서는 먼저 enterprise 설정을 열고 issuer를 확인하고, workflow를 rerun하고, debugger 또는 로그에서 sub를 조회하고, 그다음에 repo_property value가 실제 토큰에 실렸는지 확인하고, 마지막에 role trust policy diff와 rerun 결과를 다시 비교하는 편이 좋다. 이 과정을 거치지 않으면 실제 원인은 sub drift였는데 property inclusion만 한참 의심하게 된다.

• 증상: custom issuer rollout 뒤 일부 AWS role만 막힌다.
• 실패: sub를 다시 안 보고 repo_property inclusion부터 의심한다.
• 막힘: AWS trust anchor와 GitHub evidence claim을 같은 칸에 적는다.
• 누락: role policy diff와 rerun 결과를 같이 안 남긴다.

증상	먼저 볼 곳	판단 기준
모든 AWS role이 동시에 막힌다	issuer와 audience	발급자 anchor 자체가 맞는지 먼저 본다
일부 repo만 막힌다	sub와 role trust policy	owner 또는 repo anchor가 맞는지 확인한다
로그는 맞는 것 같은데 정책이 헷갈린다	repo_property claims evidence	trust anchor가 아니라 추가 evidence 층으로 본다

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

실무에서는 네 단계면 충분하다. 먼저 enterprise custom issuer와 audience를 확인한다. 두 번째로 실제 sub를 debugger와 rerun 로그에서 저장한다. 세 번째로 repo_property 값이 토큰에 실렸는지 별도 evidence 로그를 남긴다. 마지막으로 AWS role trust policy diff를 비교하고, 실패 repo만 다시 rerun해 결과를 닫는다.

1. issuer와 audience를 먼저 확인한다.
2. 실제 sub를 로그와 debugger로 저장한다.
3. repo_property included claims를 evidence로 분리한다.
4. role trust policy diff와 rerun 결과를 같이 본다.

step_1 = "issuer와 aud를 조회한다"
step_2 = "sub를 debugger와 workflow 로그에 저장한다"
step_3 = "repo_property claim inclusion을 별도 evidence로 남긴다"
step_4 = "AWS role trust policy diff를 비교하고 rerun한다"

이 순서를 지키면 AWS trust policy를 무작정 넓히지 않고도 원인 분리가 가능하다. 먼저 anchor를 고정하고, 그다음 evidence를 추가하고, 마지막에 role별 실패 범위를 줄이는 편이 rollback이 짧다.

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

첫 실제 자료는 enterprise custom issuer 정책 화면이다. 이 변경이 들어간 뒤 AWS trust를 다시 볼 때도 첫 줄은 여전히 issuer 정렬이다.

enterprise custom issuer는 AWS trust policy보다 앞선 GitHub 쪽 발급자 설정층이다.

즉 AWS에서 역할 정책을 아무리 만져도 issuer가 흔들리면 결과가 한꺼번에 깨진다. 먼저 이 층을 고정하고 나서 sub와 로그 확장 순서를 적어야 한다.

두 번째 자료는 repo_property claim 화면이다. GitHub는 repository custom property가 OIDC 토큰에 포함될 수 있다고 설명하지만, 이 값이 곧바로 AWS trust policy의 첫 조건이 되는 것은 아니다.

repo_property claim은 토큰 안 evidence 층으로 먼저 읽고, AWS trust의 첫 anchor와는 분리해서 다루는 편이 맞다.

그래서 repo_property 확장은 바로 trust policy JSON부터 바꾸는 작업이 아니라, 먼저 토큰에 값이 실리는지 로그와 debugger로 확인하는 작업에 가깝다.

세 번째 실제 자료는 AWS 쪽 제한 설명이다. GitHub 문서는 AWS에서 custom claims 지원이 없다고 적고 있으므로, AWS trust의 기본 경계는 여전히 subject와 audience 쪽에서 먼저 잡아야 한다.

AWS trust policy는 repo_property를 바로 첫 조건으로 쓰기보다 sub와 aud anchor를 먼저 고정하는 편이 안전하다.

이 제한을 빼먹으면 repo_property inclusion 누락과 AWS trust 조건 오류를 한 incident에 섞게 된다. custom property는 evidence 로그층, trust policy는 sub anchor층으로 나눠 적는 편이 낫다.

네 번째 자료는 OIDC debugger 화면이다. repo_property를 trust anchor로 바로 쓰지 못할수록, 실제 sub와 함께 어떤 claim이 토큰에 들어왔는지 로그를 남기는 일이 더 중요해진다.

AWS branch에서는 trust policy 변경보다 먼저 실제 sub와 included claims 로그를 같이 남겨야 한다.

실무에서는 workflow를 rerun하고, debugger 출력을 저장하고, sub와 owner 또는 repo anchor가 먼저 맞는지 보고, 그다음에 repo_property evidence를 추가 메모로 붙이는 편이 짧다.

실무에서는 AWS trust policy와 repo_property evidence를 한 줄로 쓰지 말고, anchor와 evidence를 분리한 로그 순서표로 남기는 편이 낫다.

enterprise custom issuer 뒤 AWS sub 조건과 repo_property evidence를 기록하는 권장 순서표다.

이미 Vault issuer 정렬 글, repo_property claim과 issuer·aud·sub 정렬 글, cross-cloud allowlist 글을 읽었다면 이번 표는 AWS branch를 더 좁히는 후속편이다.

마지막 자료는 triage 메모 예시다. 클릭하고 조회하고 rerun하기 전에 어떤 필드를 먼저 저장할지 정해 두면 sub 문제와 repo_property 문제를 금방 자를 수 있다.

enterprise custom issuer 뒤 AWS OIDC trust triage 메모 예시다.

이 정도 메모만 있어도 AWS role trust policy를 곧바로 넓힐지, 먼저 repo_property inclusion 로그부터 다시 저장할지 판단이 빨라진다.

5. 주의사항과 리스크

첫 번째 리스크는 repo_property inclusion을 trust anchor처럼 생각해 sub 확인을 건너뛰는 것이다. 두 번째는 custom issuer 변경 시각과 AWS role policy 변경 시각을 같은 로그 항목 묶음으로 남기지 않는 것이다. 세 번째는 rerun 결과 없이 trust policy만 넓혀 실제 원인 증거를 잃는 것이다.

운영 메모에는 최소한 issuer, aud, sub, repo_property evidence, role policy diff, rerun 결과가 있어야 한다. 여기서 sub를 빼면 AWS branch는 거의 항상 길어진다.

• issuer와 sub를 확인하기 전에는 role trust를 넓히지 않는다.
• repo_property는 trust anchor와 분리해서 evidence 층으로 적는다.
• rerun 결과를 남기지 않은 정책 변경은 회고 가치가 낮다.

6. 결론

enterprise custom issuer 뒤 AWS trust를 더 좁힐 때는 sub anchor와 repo_property evidence를 같은 층으로 다루지 않는 편이 맞다. issuer와 audience를 먼저 고정하고, 실제 sub를 저장하고, repo_property inclusion을 별도 evidence로 남긴 뒤, role policy diff와 rerun 결과를 같이 보면 incident 분리가 훨씬 빨라진다.

여기서 실제 운영이 막히는 다음 지점은 aud mismatch와 sub scope drift가 같이 보일 때 어떤 claim snapshot부터 다시 남길지다. 바로 이어서 custom issuer 뒤 AWS trust policy에서 aud mismatch와 sub scope drift가 같이 보일 때 claim snapshot을 다시 남기는 글까지 보면 sub 확장 단계 다음 triage 순서를 더 짧게 잡을 수 있다.

• AWS branch의 첫 anchor는 여전히 issuer·aud·sub다.
• repo_property는 evidence 로그층으로 분리한다.
• role trust diff와 rerun 결과를 같이 남긴다.

7. 참고 링크

1. https://docs.github.com/en/actions/concepts/security/openid-connect
2. https://docs.github.com/en/enterprise-cloud@latest/rest/actions/oidc
3. https://docs.github.com/en/enterprise-cloud@latest/actions/reference/security/oidc
4. https://docs.github.com/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-amazon-web-services