-
[GitHub Actions][OIDC] enterprise custom issuer를 켠 뒤 Vault bound_issuer와 oidc_discovery_url를 어느 순서로 바꾸나기타개발지식/풀스택개발 2026. 8. 7. 20:20
IT 리서치 노트
[GitHub Actions][OIDC] enterprise custom issuer를 켠 뒤 Vault bound_issuer와 oidc_discovery_url를 어느 순서로 바꾸나
GitHub Actions OIDC에서 enterprise custom issuer를 켠 뒤 가장 자주 뒤늦게 깨지는 곳은 Vault trust다. 2026년 8월 7일 기준 GitHub 공식 문서를 다시 보면 custom issuer policy는 enterprise 단위 설정이고, Vault 배포 가이드는 custom issuer를 쓸 때
bound_issuer와oidc_discovery_url를 새 값에 맞추라고 직접 적고 있다. 이 글은 enterprise custom issuer를 켠 뒤 Vaultbound_issuer와oidc_discovery_url를 어느 순서로 바꾸는 편이 덜 꼬이는지 정리한 것이다.1. 개요
결론부터 말하면 GitHub custom issuer를 먼저 고정하고, 실제 토큰의
iss샘플을 저장한 뒤, 그다음 Vault의bound_issuer와oidc_discovery_url를 맞추는 편이 맞다. subject template와 repo override는 그 다음 단계다.이 문제를 GitHub claim 튜닝과 같은 단계로 묶으면 issuer mismatch와 sub mismatch가 같은 403처럼 보여 오래 막힌다. 먼저 발급자 anchor를 맞추고 나서 sub 조건을 좁혀야 한다.
2. 어디서 실제로 막히는가
현장에서 자주 꼬이는 지점은 세 가지다. 첫째, GitHub custom issuer와 Vault trust 수정을 동시에 해 실제
iss를 저장하지 않는다. 둘째, Vaultbound_issuer만 바꾸고 discovery URL은 예전 값을 둔다. 셋째, issuer mismatch를 subject template 문제로 먼저 의심한다.GitHub REST 문서는 custom issuer policy를 별도 엔드포인트로 제공하고, Vault 가이드는 custom issuer URL을 쓸 때 두 필드가 모두 새 issuer를 따라야 한다고 적는다. claim reference는 subject customization을 또 다른 레이어로 둔다. 이 셋을 합치면 순서를 분리해야 한다는 힌트가 명확해진다.
- 증상: GitHub OIDC가 갑자기 Vault에서만 403으로 실패한다.
- 실패: actual
iss샘플 없이 trust와 sub를 같이 바꾼다. - 막힘:
bound_issuer와oidc_discovery_url를 같은 change로 적지 않는다. - 누락: repo override와 subject template를 issuer 이후 단계로 남기지 않는다.
3. 실무에서 적용하는 순서
가장 짧은 적용 순서는 네 단계다. 먼저 enterprise custom issuer policy 값을 확인한다. 두 번째로 Actions run에서 실제 토큰의
iss샘플을 남긴다. 세 번째로 Vault의bound_issuer와oidc_discovery_url를 새 값으로 맞춘다. 마지막으로 subject template와 repo override를 확인해 sub 조건을 좁힌다.- GitHub custom issuer policy를 먼저 확인한다.
- actual token의
iss샘플을 저장한다. - Vault trust 두 필드를 함께 바꾼다.
- issuer가 맞은 뒤 subject template를 본다.
실제 운영에서는 enterprise 설정을 조회하고, run id 기준으로 토큰 샘플을 저장하고, Vault role 설정 화면이나 IaC diff를 비교하고, 변경 후 assume 성공 로그를 확인하고, repo override 여부를 다시 조회하는 편이 좋다. 같은 403이라도 어느 레이어가 실패했는지 남겨야 rollback이 짧다.
run_id=... iss_sample_saved=true vault_bound_issuer_updated=true vault_discovery_url_updated=true sub_template_checked_after_issuer=true rollback_diff_saved=true4. 공식 문서와 예시 화면으로 확인하기
첫 공식 화면은 enterprise custom issuer policy 엔드포인트다. 여기서는 issuer URL anchor 자체를 enterprise 단위에서 바꿀 수 있다.
즉 이 변경은 subject template 튜닝보다 한 단계 위다. Vault 쪽 신뢰 anchor도 이 변경을 따라가야 하므로 순서를 분리하지 않으면 원인 분석이 어려워진다.
두 번째 자료는 GitHub의 Vault 배포 가이드다. custom issuer URL을 쓴다면 Vault의
bound_issuer와oidc_discovery_url이 그 값을 따라가야 한다고 직접 적고 있다.여기서 핵심은 두 필드를 같이 바꾸라는 사실보다, GitHub 쪽 custom issuer 적용과 Vault trust 수정이 다른 단계라는 점이다. 토큰 샘플 없이 동시에 바꾸면 어느 쪽이 깨졌는지 분리가 안 된다.
세 번째 화면은 subject claim 커스터마이징 구간이다. issuer 변경 뒤에도 subject template와 repo override는 별도 레이어로 남는다.
그래서 Vault trust 장애를 subject template부터 의심하는 순서는 잘못되기 쉽다. 먼저 issuer anchor를 맞추고, 그 다음 sub 조건을 봐야 한다.
실무에서는 변경 순서를 표로 고정해 두는 편이 안전하다. GitHub 설정, 실제 토큰 샘플, Vault trust 수정, rollback 메모를 따로 봐야 한다.
이미 issuer URL과 subject template 분기 글이 GitHub 쪽 rollout 자체를 다뤘다면, 이번 표는 Vault trust로 내려오는 후속편이다.
마지막 자료는 운영 메모 예시다. GitHub 쪽 issuer 변경과 Vault 쪽 신뢰 수정은 같은 change set처럼 보여도 실제로는 अलग개 검증 항목을 남겨야 한다.
이 메모가 있으면 장애가 났을 때 issuer mismatch인지 sub mismatch인지 더 빨리 가른다. rollout과 rollback 기준도 훨씬 짧아진다.
5. 주의사항과 리스크
첫 번째 리스크는 GitHub와 Vault 변경을 동시에 해 issuer mismatch를 복기하지 못하는 것이다. 두 번째는 discovery URL을 빼먹고 bound_issuer만 바꾸는 것이다. 세 번째는 issuer가 틀린 상태에서 subject template를 계속 만지는 것이다.
운영 전에 확인할 때는 actual
iss, Vault 두 필드, subject template, rollback diff를 같은 메모에 두는 편이 좋다. 이 네 칸이 없으면 장애 원인 분리가 늦어진다.6. 결론
enterprise custom issuer를 켠 뒤 Vault trust를 바꿀 때는 먼저 actual
iss를 고정하고, 그 다음bound_issuer와oidc_discovery_url를 함께 맞추고, 그 뒤에 subject template를 보는 편이 맞다. issuer와 sub를 한 번에 바꾸지 않으면 rollout과 rollback이 훨씬 짧아진다.- issuer anchor를 먼저 맞춘다.
- Vault trust 두 필드를 같은 change로 관리한다.
- subject template는 issuer 이후 단계다.
7. 참고 링크
'기타개발지식 > 풀스택개발' 카테고리의 다른 글
