[GitHub Actions][OIDC] enterprise custom issuer 뒤 repo_property claim을 GCP Workload Identity 조건에 넣을 때 issuer·aud·sub를 어떤 순서로 다시 고치나

IT 리서치 노트

[GitHub Actions][OIDC] enterprise custom issuer 뒤 repo_property claim을 GCP Workload Identity 조건에 넣을 때 issuer·aud·sub를 어떤 순서로 다시 고치나

GitHub enterprise custom issuer를 켠 뒤 GCP Workload Identity Federation에 repo_property 기반 조건까지 붙이려 하면 어디서부터 다시 맞춰야 할지 헷갈릴 때가 많다. 2026년 8월 9일 기준 GitHub 공식 문서를 다시 보면 enterprise custom issuer는 `iss` 값을 enterprise slug가 붙은 URL로 바꾸고, repository custom properties는 `repo_property_*` 클레임으로 OIDC 토큰에 자동 포함될 수 있다. 동시에 Google Cloud 문서는 GitHub Actions provider 기본 예시가 기본 issuer와 기본 audience를 전제로 하며, OIDC provider 생성·수정 시 issuer-uri, allowed audiences, attribute mapping, attribute condition을 따로 받는다고 설명한다. 이 글은 issuer·aud·sub를 어떤 순서로 다시 고친 뒤 repo_property 조건을 붙이는 편이 실수를 줄이는지 정리한 것이다.

목차

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

1. 개요

결론부터 말하면 GCP에서 repo_property 조건을 붙이기 전에 먼저 issuer-uri, 그다음 aud, 그다음 sub, 마지막에 repo_property_* 조건으로 좁히는 편이 맞다. custom issuer를 켠 순간 provider가 믿는 토큰 발급자부터 달라지므로, attribute mapping을 먼저 손보면 오히려 원인 분리가 어려워진다.

이미 GCP issuer와 allowed audiences 글과 custom issuer 뒤 claim drift 글을 읽었다면, 이번 글은 그 다음 단계인 ABAC 조건 추가다. issuer만 바꾸고 repo_property를 곧장 붙이면 정상 repo까지 막는 실수가 나기 쉽다. 실제 cleanup 단계에서 repository_owner allowlist를 언제 남기고 언제 줄일지는 follow-up 글에서 이어서 정리했다.

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

현장에서 가장 흔한 꼬임은 세 가지다. 첫째, enterprise custom issuer를 켰는데도 GCP provider는 기본 issuer-uri를 그대로 둔다. 둘째, audience가 기본값인지 custom action이 만든 값인지 확인하지 않고 repo_property 조건을 먼저 붙인다. 셋째, subject 조건과 repo_property 조건을 한 번에 바꾸어 어떤 조건이 토큰 교환을 막았는지 설명이 안 된다.

GitHub 문서는 custom issuer를 켜면 iss가 enterprise slug가 붙은 URL로 바뀐다고 적고, custom properties를 OIDC token claims에 넣을 수 있다고 설명한다. Google Cloud 문서는 GitHub Actions provider 기본 예시가 기본 issuer URL과 기본 audience를 전제로 하며, 일반 OIDC provider 생성 명령에서는 issuer-uri, allowed-audiences, attribute-mapping, attribute-condition을 각각 받는다고 적는다. 이 둘을 합치면 변경 순서를 잘못 잡을 이유가 없다.

repo_property 조건은 세분화 도구이지, 발급자 신뢰를 대신하지 못한다. provider가 토큰 발급자나 audience를 먼저 받아들이지 못하면 subject 조건과 repo_property 조건은 아예 평가까지 가지 않는다. 그래서 issuer, audience, subject, ABAC 순서로 좁히고, 각 단계에서 콘솔 탭, 필드, 명령 입력값, 조건식을 따로 확인하는 편이 운영상 훨씬 안전하다.

• 증상: enterprise custom issuer 이후 GCP token exchange가 갑자기 실패한다.
• 실패: repo_property 조건을 먼저 추가해 원인 층을 섞는다.
• 막힘: aud가 기본값인지 custom action 값인지 확인하지 않는다.
• 누락: sub 조건과 repo_property 조건을 분리한 rollout 메모가 없다.

실패 상황	먼저 볼 곳	판단 기준
token exchange 자체가 실패한다	issuer-uri	enterprise slug가 붙은 새 issuer와 맞는지 본다
일부 workflow만 실패한다	aud / allowed audiences	custom audience를 쓰는 action이 있는지 본다
특정 repo만 막고 싶다	sub 뒤 repo_property 조건	기본 신원 경계 위에 ABAC를 얹는다

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

실무 적용 순서는 네 단계가 가장 짧다. 먼저 GitHub 쪽 custom issuer 적용 여부와 실제 iss 값을 확인한다. 두 번째로 GCP provider의 issuer-uri와 allowed audiences를 맞춘다. 세 번째로 sub 조건을 그대로 둘지 immutable subject나 reusable workflow 기준으로 바꿀지 고정한다. 마지막으로 repo_property 값을 attribute mapping과 attribute condition에 붙여 팀·서비스·분류 기준을 세분화한다.

1. 실제 iss가 enterprise custom issuer로 바뀌었는지 확인한다.
2. GCP provider의 issuer-uri와 allowed audiences를 먼저 맞춘다.
3. sub 조건을 먼저 고정해 기본 신원 경계를 잡는다.
4. repo_property mapping과 condition으로 마지막 세분화를 넣는다.

이 순서를 지키면 ABAC 조건 추가가 훨씬 단순해진다. 예를 들어 repo_property_business_unit == 'payments' 같은 조건은 provider가 토큰을 정상 수용한다는 전제 위에서만 의미가 있다. 콘솔에서 issuer-uri 필드를 열고, allowed audiences 입력값을 확인하고, attribute mapping 필드에 값을 입력하고, 마지막으로 condition 식을 저장하면 어느 버튼과 필드에서 막혔는지 추적하기 쉽다. issuer가 틀리거나 audience가 어긋나면 repo_property 값이 아무리 맞아도 토큰 교환은 시작조차 되지 않는다.

iss=https://token.actions.githubusercontent.com/example-enterprise
aud=...
sub=repo:org/repo:ref:refs/heads/main
repo_property_business_unit=payments

rollout 메모도 분리하는 편이 좋다. 1차는 issuer/audience 정렬, 2차는 subject 정렬, 3차는 repo_property ABAC 추가로 나누면 문제가 생겼을 때 되돌릴 범위가 훨씬 짧아진다. 각 단계마다 어떤 탭을 열었는지, 어떤 필드를 입력했는지, 어떤 명령을 실행했는지, 어떤 로그와 조건식을 확인했는지 같이 적어 두면 더 안전하다.

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

첫 공식 화면은 enterprise custom issuer 설명이다. GitHub는 issuer를 enterprise slug가 붙은 고유 URL로 바꿀 수 있다고 설명한다.

GitHub enterprise custom issuer를 켜면 `iss`가 enterprise slug가 붙은 URL로 바뀐다.

즉 GCP Workload Identity Provider가 믿는 issuer-uri도 같이 바뀌어야 한다. repo_property claim을 붙이는 일은 이보다 뒤 단계다.

두 번째 자료는 repository custom properties를 OIDC claim으로 넣는 구간이다. GitHub는 `repo_property_*` 클레임을 cloud trust policy에서 조건으로 쓸 수 있다고 적고 있다.

GitHub는 `repo_property_*` 클레임으로 ABAC 정책을 만들 수 있다고 설명한다.

이 기능 덕분에 repo 이름 allowlist를 길게 유지하지 않고도 팀·서비스·분류 기준을 토큰에 실어 GCP 조건으로 옮길 수 있다. 다만 issuer와 audience가 먼저 맞아야 그 조건이 의미를 가진다.

세 번째 공식 화면은 GCP의 GitHub Actions provider 설정 예시다. 콘솔의 Issuer URL 필드와 Audiences 필드를 보면 기본 예시에서는 issuer URL이 `https://token.actions.githubusercontent.com/`이고 audience는 Default audience다.

Google Cloud 기본 GitHub Actions 예시는 기본 issuer와 기본 audience를 전제로 한다.

enterprise custom issuer를 켠 순간 이 기본 가정이 깨질 수 있다. 따라서 repo_property 조건을 붙이기 전에 provider의 issuer, audience, attribute mapping 순서를 다시 잡고, 콘솔 입력값이나 gcloud 명령 필드를 하나씩 확인해야 한다.

실무에서는 변경 순서를 잘못 잡을 때 incident가 길어진다. issuer, audience, subject, repo_property condition을 어떤 순서로 바꿔야 하는지 한 표로 묶었다.

custom issuer 뒤 repo_property 조건까지 붙일 때 변경 순서를 정리한 표다.

이미 GCP issuer URL과 allowed audiences 글이 provider 기본 축을 다뤘다면, 이번 표는 그 위에 repo_property 기반 ABAC를 얹는 후속편이다.

마지막 자료는 GCP provider 업데이트 예시다. issuer-uri와 allowed audiences를 먼저 맞추고, 그다음 attribute mapping과 condition에 repo_property 값을 붙이는 식으로 두는 편이 안전하다.

GCP Workload Identity Provider에 repo_property 조건을 붙이는 예시다.

이 구조를 쓰면 Vault issuer 변경 글과 include_claim_keys drift 글에서 확인한 증거를 GCP 조건으로 이어 붙이기 쉽다.

5. 주의사항과 리스크

첫 번째 리스크는 custom issuer를 켜고도 GCP provider issuer-uri를 기본값으로 두는 것이다. 두 번째는 audience를 검증하지 않은 채 repo_property 조건만 강화하는 것이다. 세 번째는 subject 조건과 repo_property 조건을 동시에 바꿔 rollback 기준이 사라지는 것이다.

운영 전에 확인할 때는 최소한 iss, aud, sub, repo_property_* 네 층을 서로 다른 체크포인트로 남기는 편이 좋다. 이 순서가 없으면 신뢰 경계 문제와 ABAC 세분화 문제를 한 incident로 섞게 된다.

• repo_property 조건은 issuer·aud 정렬 뒤에 붙인다.
• sub 경계와 ABAC 경계를 한 번에 바꾸지 않는다.
• rollback은 issuer/audience 단계와 ABAC 단계로 나눠 둔다.

6. 결론

GitHub enterprise custom issuer 뒤에 GCP Workload Identity 조건을 더 세분화하려면 순서가 가장 중요하다. 먼저 issuer와 audience를 맞추고, 그다음 sub 경계를 고정한 뒤, 마지막에 repo_property 기반 ABAC를 얹어야 실무 incident와 rollback이 짧아진다. 그다음 단계로 repository_owner allowlist와 repo_property 조건을 hybrid로 남기고 줄이는 cleanup 순서는 후속 정리를 바로 이어 보면 된다. 같은 custom issuer 계열에서 GCP attribute condition을 owner→workflow→property 순서로 더 안정적으로 붙이는 기준은 새 follow-up에 정리해 두었다.

• issuer와 audience부터 먼저 맞춘다.
• sub를 고정한 뒤 repo_property 조건을 얹는다.
• ABAC rollout은 별도 단계로 분리한다.

7. 참고 링크

1. https://docs.github.com/en/enterprise-cloud@latest/actions/reference/security/oidc
2. https://docs.github.com/en/actions/concepts/security/openid-connect
3. https://docs.cloud.google.com/iam/docs/workload-identity-federation-with-deployment-pipelines
4. https://docs.cloud.google.com/sdk/gcloud/reference/iam/workload-identity-pools/providers/create-oidc