[GitHub Actions][OIDC] enterprise custom issuer 뒤 Azure federated credential와 include_claim_keys drift를 어떤 순서로 다시 분리하나

IT 리서치 노트

[GitHub Actions][OIDC] enterprise custom issuer 뒤 Azure federated credential와 include_claim_keys drift를 어떤 순서로 다시 분리하나

GitHub Actions OIDC에서 enterprise custom issuer를 켠 뒤 Azure login이 흔들리면 많은 팀이 issuer URL 하나만 다시 보거나, 반대로 include_claim_keys 변경만 의심한다. 하지만 2026년 8월 13일 기준 GitHub과 Microsoft 공식 문서를 함께 다시 보면 Azure는 audience와 subject 조건을 federated credential 객체에 고정하고, GitHub은 custom subject claims를 바꾸기 전에 cloud provider 조건을 먼저 맞추라고 안내한다. 이 글은 enterprise custom issuer 뒤 Azure federated credential와 include_claim_keys drift를 어떤 순서로 다시 분리해야 운영 메모가 덜 꼬이는지 정리한 것이다.

목차

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

1. 개요

결론부터 말하면 Azure branch에서는 aud, sub, 현재 GitHub subject template, 그리고 Microsoft Entra의 federated credential 객체를 한 묶음으로 먼저 기록해야 한다. GitHub에서 claim 구조를 바꿨는지와 Azure에서 수용 객체를 갱신했는지를 따로 나눠 기록해야 하기 때문이다.

즉 첫 질문은 "include_claim_keys를 켰나"가 아니라 "현재 live token의 aud·sub가 Azure credential 객체의 기대값과 같은가"다. 그다음에야 custom issuer rollout, repo_property, environment 세분화 같은 다음 분기로 내려가는 편이 맞다.

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

실무에서 자주 꼬이는 지점은 세 가지다. 첫째, enterprise custom issuer rollout과 subject template 변경을 같은 배포에 묶어 어떤 층이 깨졌는지 구분하지 못한다. 둘째, azure/login의 audience 기본값을 다른 cloud와 같은 습관으로 덮어써 놓고 나중에 subject만 다시 본다. 셋째, GitHub에서는 include_claim_keys를 바꿨지만 Entra의 federated credential은 예전 subject를 그대로 기대한다.

GitHub Azure 가이드는 audience 기본값을 명시하고 있고, OIDC reference는 subject claims를 바꾸기 전에 cloud provider 조건을 먼저 만들라고 적고 있다. Microsoft Learn은 federated identity credential 객체를 애플리케이션 또는 관리 ID에 구성해야 한다고 설명한다. 이 셋을 같이 읽으면, Azure OIDC triage의 첫 레코드는 claim만이 아니라 credential object 이름과 subject 조건까지 포함해야 한다는 결론이 나온다.

• 증상: 같은 workflow인데 Azure login이 특정 environment에서만 실패한다.
• 실패: GitHub subject template 변경과 Entra credential 갱신 시점을 따로 적지 않는다.
• 막힘: audience를 확인하지 않은 채 subject drift만 추적한다.
• 누락: live token과 federated credential 객체의 subject를 한 줄로 대조하지 않는다.

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

실무 triage는 네 단계가 짧다. 첫째, 실패한 run에서 iss, aud, sub를 남긴다. 둘째, GitHub subject template 또는 include_claim_keys 변경 이력을 적는다. 셋째, Entra의 federated credential 객체 이름과 현재 subject 값을 저장한다. 넷째, 두 값을 문자열 단위로 비교한 뒤에야 environment 세분화와 repo_property 같은 보조 claim을 본다.

1. 실패 run의 iss, aud, sub를 저장한다.
2. GitHub subject template 변경 이력을 저장한다.
3. Entra federated credential 객체 이름과 subject를 적는다.
4. 두 문자열이 맞는지 비교하고 나서 보조 claim을 본다.

이때는 Azure portal 화면에서 credential 목록을 조회하고, workflow 로그 화면에서 live token 값을 확인하고, audience 필드와 subject 필드를 복사해 같은 표에 저장하는 식으로 움직여야 한다. portal 메뉴, credential 필드, workflow 로그, 응답 메시지, 설정 파일, YAML 파일을 한 번에 비교해 두면 재배포 전에 어떤 설정을 다시 확인할지 빠르게 정리된다.

확인 메모 예시

aud=api://AzureADTokenExchange
sub=repo:example-org/example-repo:environment:prod
github_subject_template=repo,context
entra_credential_subject=repo:example-org/example-repo:environment:prod
decision=subject matches; check credential object selection and rollout timing

이 순서를 지키면 Azure branch에서 claim drift와 credential drift를 따로 자를 수 있다. 이미 immutable sub와 AWS trust policy 글을 읽었다면, 이번 글은 provider 객체를 같이 적는다는 점이 Azure 쪽 차이다.

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

첫 실제 자료는 GitHub의 Azure OIDC 가이드다. Azure 쪽 문제를 볼 때도 audience 축이 먼저 분리돼야 하는 이유가 여기서 드러난다.

GitHub Docs는 Azure OIDC에서 audience 기본값으로 api://AzureADTokenExchange를 권장한다고 설명한다.

즉 Azure login 실패를 custom issuer 문제로만 보지 말고, 현재 workflow의 audience 입력값과 federated credential 쪽 기대값을 먼저 같은 메모에 적어 둬야 한다. audience를 빼먹은 채 subject drift만 파고들면 incident 분리가 느려진다.

두 번째 자료는 GitHub OIDC reference의 핵심 순서다. cloud provider 조건을 먼저 만들고, 그 뒤에 GitHub 쪽 subject customization을 바꾸라고 적혀 있다.

GitHub OIDC reference는 subject claims를 바꾸기 전에 cloud provider 조건을 먼저 맞추라고 안내한다.

이 문장이 중요한 이유는 include_claim_keys 변경을 GitHub에서 먼저 밀어 넣고 Azure credential은 뒤늦게 고치는 순서가 가장 위험하기 때문이다. custom issuer rollout과 subject template 변경을 한 티켓에 섞을수록 rollback 경계가 섞인다.

세 번째 자료는 Microsoft Learn이다. Azure는 federated credential 객체를 따로 두고 GitHub 토큰 수용 범위를 그 객체 단위로 관리한다.

Microsoft Learn은 Microsoft Entra 애플리케이션 또는 사용자 할당 관리 ID에 federated identity credential을 구성해야 한다고 설명한다.

그래서 Azure branch에서는 GitHub token 변화와 Entra credential 객체 변화를 따로 기록하는 편이 맞다. 같은 subject drift라도 원인이 GitHub claim template 변경인지, Azure credential 재생성 누락인지 분리해야 한다.

Azure 쪽에서 자주 섞이는 것은 audience mismatch, subject template drift, federated credential 객체 누락 세 가지다. 한 번에 정리해 두면 triage가 빨라진다.

Azure OIDC 실패를 audience, subject, credential object 세 갈래로 자르는 비교표다.

이미 cross-cloud allowlist 글이 Azure를 포함한 큰 그림을 다뤘다면, 이번 표는 Azure branch만 별도로 좁혀 보는 실무판이다.

마지막 자료는 실제 incident 메모 예시다. Azure는 claim과 credential object를 한 줄로 붙여 두는 것이 핵심이다.

Azure federated credential drift를 볼 때 남기면 좋은 최소 snapshot 예시다.

이 메모를 남겨 두면 GitHub subject template 변경과 Azure credential 갱신 누락을 분리할 수 있다. 이후에야 include_claim_keys나 repo_property 설계를 붙여도 늦지 않다.

5. 주의사항과 리스크

첫 번째 리스크는 audience를 건너뛰고 subject만 다시 보는 것이다. 두 번째 리스크는 GitHub 설정 변경과 Azure credential 갱신을 같은 커밋 메시지 한 줄로만 남기는 것이다. 세 번째 리스크는 credential 객체를 늘린 뒤 어떤 workflow가 어느 객체를 써야 하는지 운영 메모를 남기지 않는 것이다.

• GitHub claim template와 Azure credential object는 같은 층이 아니다.
• subject 문자열이 맞아도 audience가 다르면 login은 계속 실패한다.
• 임시 완화를 위해 broad subject를 열기 전에 현재 drift 지점을 먼저 고정해야 한다.

6. 결론

enterprise custom issuer 뒤 Azure login이 흔들릴 때는 GitHub claim과 Entra federated credential 객체를 따로 적는 편이 가장 빠르다. audience와 subject가 현재 token과 Azure credential에서 일치하는지 먼저 고정하고, 그다음 include_claim_keys와 세부 context를 내려가야 같은 오류를 반복해서 보지 않게 된다.

• aud·sub와 credential object를 같은 레코드에 적는다.
• GitHub template 변경 이력과 Azure 객체 갱신 시점을 분리한다.
• 그 뒤에야 include_claim_keys와 repo_property를 본다.

7. 참고 링크

1. https://docs.github.com/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-azure
2. https://docs.github.com/actions/reference/openid-connect-reference
3. https://learn.microsoft.com/en-us/azure/developer/github/connect-from-azure-openid-connect