[GitHub Actions][OIDC] enterprise custom issuer를 켠 뒤 cloud provider trust policy allowlist를 어떤 순서로 맞추나

IT 리서치 노트

[GitHub Actions][OIDC] enterprise custom issuer를 켠 뒤 cloud provider trust policy allowlist를 어떤 순서로 맞추나

GitHub Actions OIDC에서 enterprise custom issuer를 켠 뒤 AWS, Azure, GCP trust를 다시 좁힐 때 많은 팀이 provider 문법부터 붙든다. 하지만 2026년 8월 11일 기준 GitHub 공식 문서를 다시 보면 custom issuer와 claim inclusion은 GitHub 측 설정층이고, 각 클라우드 trust policy는 그다음 수용층이다. 이 글은 enterprise custom issuer 뒤 cloud provider trust policy allowlist를 어떤 순서로 맞추는 편이 rollback과 incident 분리가 짧은지 정리한 것이다.

목차

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

1. 개요

결론부터 말하면 enterprise custom issuer 뒤 cross-cloud allowlist는 issuer·audience 정렬, owner 또는 repo 수준 기본 경계, reusable workflow 경계, repo_property 또는 내부 ABAC 순으로 붙이는 편이 가장 안전하다. 가장 세밀한 claim을 먼저 넣는다고 더 안전해지는 것이 아니라, 가장 덜 흔들리는 층부터 고정해야 rollback이 짧아진다.

즉 이 문제는 AWS 정책식, Azure federated credential, GCP attribute condition 중 어느 문법이 더 강하냐의 문제가 아니다. GitHub 토큰 출발점과 provider 수용 범위를 어느 층으로 나눠 기록하느냐의 문제에 더 가깝다.

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

현장에서 자주 터지는 실수는 세 가지다. 첫째, custom issuer를 켠 직후 AWS·Azure·GCP trust policy를 같은 배포에서 같이 바꾼다. 둘째, reusable workflow를 쓴다는 이유로 job_workflow_ref나 비슷한 세부 경계를 기본층보다 먼저 강하게 건다. 셋째, repo_property 같은 내부 분류를 첫 allowlist로 두고 claim inclusion 누락을 한참 뒤에 발견한다.

GitHub OIDC 개요는 토큰 발급 구조를, REST OIDC 문서는 custom issuer와 claim inclusion 같은 GitHub 측 설정층을, 각 클라우드 문서는 토큰을 수용하는 trust policy 층을 설명한다. 이 셋을 한 incident 메모에 구분하지 않으면 '토큰 shape가 달라진 문제'와 'provider에서 토큰을 거절한 문제'가 한 줄로 섞인다.

• 증상: 모든 repo가 동시에 인증 실패한다.
• 실패: issuer 정렬 전에 provider별 세부 allowlist부터 손댄다.
• 막힘: reusable workflow drift와 issuer mismatch를 같은 이슈로 본다.
• 누락: repo_property inclusion 시각과 provider policy 변경 시각을 따로 안 남긴다.

증상	먼저 볼 곳	판단 기준
모든 workflow가 막힌다	issuer와 audience	토큰 출발점 자체가 맞는지 먼저 본다
중앙 배포 workflow만 실패한다	reusable workflow 경계	owner 기본층은 통과했는지 분리한다
일부 서비스 repo만 실패한다	repo_property inclusion	토큰에 값이 실리는지부터 확인한다

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

실무에서는 네 단계면 충분하다. 먼저 custom issuer와 provider audience가 안정화됐는지 본다. 두 번째로 owner 또는 repo 수준 기본 경계를 넣는다. 세 번째로 중앙 배포 workflow 경계가 필요할 때만 reusable workflow 층을 얹는다. 마지막으로 조직 내부 서비스 분류 ABAC는 repo_property나 provider-specific 세분화로 끝낸다.

1. issuer와 audience를 가장 먼저 고정한다.
2. owner 또는 repo 기본 경계를 둔다.
3. 공용 배포 workflow가 있으면 그다음에 분리한다.
4. 내부 서비스 분류 ABAC는 마지막에 붙인다.

layer_1 issuer=a.example.internal
layer_2 base_scope=repository_owner:octo-org
layer_3 workflow_scope=platform/deploy.yml@refs/heads/main
layer_4 property_scope=repo_property_service:payments
validation=aws_role | azure_federated_credential | gcp_provider_condition

이 순서를 잡아 두면 '토큰이 잘못 발급됐는가'와 'provider에서 너무 좁게 막았는가'가 빨리 갈린다. custom issuer 뒤에는 특히 첫 두 줄을 별도 메모와 검증 로그로 남기는 편이 낫다.

실제 변경 직후에는 GitHub enterprise 설정 화면과 AWS, Azure, GCP 설정 경로를 각각 열어 issuer, audience, workflow 값, property 값을 입력하고 확인해야 한다. 이어서 콘솔 결과, 오류 메시지, 응답 로그, 설정 표를 비교해 어느 단계에서 실패했는지 기록하면 rollback 판단이 빨라진다.

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

첫 공식 화면은 GitHub OIDC 개요다. enterprise custom issuer를 켠 뒤에도 출발점은 여전히 'GitHub가 짧은 수명 토큰을 발급하고 클라우드가 그 토큰을 신뢰한다'는 기본 구조다.

custom issuer 이후에도 trust policy는 GitHub OIDC 토큰 수용 범위를 줄이는 층이라는 점은 같다.

즉 allowlist 설계는 claim을 많이 붙이는 문제가 아니라, 기본 신뢰 경계와 세부 claim을 어떤 단계로 나눌지의 문제다. 이 출발점을 놓치면 AWS·Azure·GCP 문서를 각각 따로 읽고도 incident 메모가 하나로 섞인다.

두 번째 자료는 GitHub REST OIDC 설정층이다. custom issuer와 claim inclusion은 subject 템플릿이나 provider trust policy와 다른 단계라는 근거를 여기서 잡아야 한다.

custom issuer 정책과 claim inclusion은 provider trust policy보다 앞선 GitHub 측 설정층이다.

그래서 allowlist 설계를 시작할 때는 먼저 'issuer가 새 값으로 안정화됐는가'를 확인해야 한다. issuer가 흔들리는 상태에서 AWS 조건문, Azure federated credential, GCP attribute condition을 한 번에 손보면 되돌리기 메모가 길어진다.

세 번째 공식 화면은 AWS trust policy 예시다. GitHub 문서는 subject와 audience 조건을 IAM role trust policy에 넣어 범위를 줄이는 흐름을 보여 준다.

AWS는 role trust policy에서 subject·audience 조건으로 GitHub OIDC 범위를 줄이게 한다.

이 자료가 중요한 이유는 AWS가 가장 먼저 'issuer와 subject 기반 기본 경계'를 보게 만들기 때문이다. 조직 전체를 막을 기본층을 owner 또는 repo 범위에서 먼저 고정한 뒤 reusable workflow나 property 세분화를 고려하는 편이 맞다.

네 번째 자료는 Azure federated credential 설명이다. Azure는 GitHub 토큰을 수용하는 credential 객체를 별도로 만들고, subject-like 경계를 거기서 관리하게 한다.

Azure는 federated credential 단위로 GitHub OIDC 수용 범위를 자르는 방식이라 GitHub 설정층과 분리해서 기록해야 한다.

Azure까지 같이 보면 cross-cloud 공통점이 더 분명해진다. provider별 문법은 달라도 기본 경계, reusable workflow 경계, 조직 내부 ABAC 경계를 한 번에 열지 않는 편이 rollback이 짧다.

다섯 번째 공식 화면은 GCP 쪽 attribute condition 가이드다. GCP는 assertion과 mapped attribute를 조건식으로 받아 더 세밀한 allowlist를 만들 수 있다고 적고 있다.

GCP는 attribute condition으로 claim 세분화를 지원하지만, 기본 신뢰 경계보다 먼저 열면 원인 분리가 늦어진다.

즉 GCP가 가장 세밀한 조건식을 지원한다고 해서 그것부터 붙이는 편이 낫다는 뜻은 아니다. AWS와 Azure 흐름까지 같이 보면 owner 또는 repo 수준의 공통 경계를 먼저 두고, reusable workflow와 repo property는 나중에 올리는 편이 incident 추적이 짧다.

실무에서는 클라우드별 문법보다 변경 순서를 먼저 통일해 두는 편이 안전하다. 기본 issuer 정렬, owner·repo 경계, reusable workflow 경계, repo_property 또는 내부 ABAC를 표로 나눴다.

enterprise custom issuer 뒤 cross-cloud allowlist를 붙이는 권장 순서표다.

이미 Vault issuer 정렬 글, GCP audience 글, GCP claim layering 글을 읽었다면 이번 표는 provider를 가로지르는 운영 순서다.

마지막 자료는 rollout 메모 예시다. 핵심은 provider별 구문보다 변경 축을 줄 단위로 분리하는 것이다.

cross-cloud custom issuer allowlist 변경을 기록하는 메모 예시다.

이런 메모가 있으면 특정 repo onboarding 실패가 생겼을 때도 어느 층까지는 정상인지 바로 자를 수 있다. AWS role, Azure federated credential, GCP provider condition을 한 문장에 섞지 않는 것이 핵심이다.

5. 주의사항과 리스크

첫 번째 리스크는 세부 claim을 너무 빨리 붙여 provider policy 문제와 GitHub 토큰 shape 문제를 한 incident에 묻는 것이다. 두 번째는 reusable workflow 경계를 owner 기본층보다 먼저 두어 workflow ref drift와 issuer 변동을 같이 흔드는 것이다. 세 번째는 repo_property inclusion 시각을 안 남겨 policy 회귀와 claim 누락을 나중에 구분하지 못하는 것이다.

cross-cloud 운영 메모의 핵심은 provider 구문 통일이 아니라 변경 축 분리다. 최소한 issuer·base scope·workflow scope·property scope 네 줄은 따로 남겨야 한다.

• 기본 경계 없이 세부 ABAC만 강하게 걸지 않는다.
• workflow drift와 issuer 변동을 같은 원인으로 적지 않는다.
• repo_property inclusion은 provider 정책 변경 시각과 분리해서 남긴다.

6. 결론

enterprise custom issuer 뒤 cross-cloud trust를 좁힐 때는 가장 세밀한 claim보다 가장 덜 흔들리는 층부터 고정하는 편이 맞다. issuer와 audience를 먼저 고정하고, owner 기본 경계를 두고, reusable workflow와 repo_property는 뒤에 올려야 rollback과 incident 분석이 짧다.

• 첫 층은 custom issuer와 audience 정렬이다.
• 둘째 층은 owner 또는 repo 수준 기본 경계다.
• 세부 workflow와 property ABAC는 마지막에 붙인다.

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/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-amazon-web-services
4. https://docs.github.com/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-azure
5. https://docs.github.com/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-google-cloud-platform