[OpenAI][인증] workload identity federation으로 GitHub Actions에서 API 키 없이 인증하는 방법

IT 리서치 노트

[OpenAI][인증] workload identity federation으로 GitHub Actions에서 API 키 없이 인증하는 방법

GitHub Actions에서 OpenAI API를 호출할 때 가장 흔한 기본값은 장기 API key를 repository secret에 넣는 방식이다. 하지만 2026년 6월 25일 기준 OpenAI 공식 문서는 workload identity federation을 통해 외부 OIDC subject token을 짧은 OpenAI access token으로 교환하는 경로를 제공한다. 이 글은 GitHub Actions 기준으로 어떤 값을 맞춰야 API key 없이도 안전하게 호출이 되는지 정리한 것이다.

목차

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

1. 개요

결론부터 말하면 OpenAI WIF는 GitHub Actions의 OIDC 토큰을 OpenAI short-lived access token으로 교환하는 구조다. 그래서 핵심은 API key 삭제 자체가 아니라, GitHub workflow가 id-token: write 권한으로 subject token을 얻고, OpenAI 쪽 provider와 service account mapping이 그 토큰의 issuer·audience·claim을 정확히 받아주도록 맞추는 일이다.

이미 subject claim과 environment 조건을 묶는 글을 봤다면 이번 글은 그 GitHub OIDC 토큰을 OpenAI 호출까지 이어 붙이는 단계라고 보면 된다. workflow 권한 자체가 헷갈리면 GITHUB_TOKEN 권한과 OIDC를 줄이는 글도 같이 보는 편이 좋다.

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

실무에서 먼저 막히는 지점은 세 가지다. 첫째, OpenAI WIF를 단순히 API key 대신 넣는 토큰 방식이라고 생각해 GitHub OIDC 권한을 빼먹는다. 둘째, provider id와 service account mapping을 만들었는데 audience나 stable claim 조건을 대충 잡아 토큰 교환이 안 된다. 셋째, inference 프로젝트 API와 Admin API를 구분하지 않고 WIF로 모두 치환하려다가 제한 사항에 부딪힌다.

OpenAI 개요 문서는 WIF가 trusted issuer, service account mapping, token exchange 세 단계를 가진다고 분명히 적고 있다. 즉 GitHub job이 subject token을 발급받는 단계와 OpenAI가 그 subject token을 받아 short-lived access token으로 바꾸는 단계는 별개다. GitHub OIDC가 열려도 OpenAI mapping이 틀리면 실패하고, 반대로 OpenAI provider를 만들어도 workflow가 id-token을 못 받으면 아무 일도 안 일어난다.

또 API 키를 없애고 싶다는 이유만으로 바로 전환하면 운영 기준이 섞이기 쉽다. job이 어느 branch, 어느 workflow, 어느 environment에서만 OpenAI를 호출해야 하는지 먼저 정해야 한다. 그래야 mapping 조건을 안정적인 claim 기준으로 만들 수 있다. 그렇지 않으면 모든 workflow에 같은 audience를 주거나, 반대로 너무 자주 바뀌는 claim을 조건으로 넣어 배포가 깨진다.

• 증상: workflow는 도는데 OpenAI 호출 직전에 인증 오류가 난다.
• 실패: permissions에 id-token: write가 없다.
• 막힘: audience 또는 subject claim 조건이 provider mapping과 안 맞는다.
• 주의: WIF access token은 Admin API에 쓸 수 없다.

증상	먼저 볼 곳	판단 기준
GitHub job에서 토큰 교환이 시작도 안 된다	workflow permissions, OIDC env vars	id-token: write와 GitHub OIDC 환경변수가 노출되는지 본다
OpenAI 인증이 계속 거절된다	identity provider, service account mapping, audience	issuer와 stable claim이 mapping 조건과 일치해야 한다
관리성 API 호출이 실패한다	WIF limitations	Admin API는 별도 admin key 경로가 필요한지 확인한다

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

구성 순서는 다섯 단계가 가장 안정적이다. 먼저 GitHub workflow에서 어떤 repository, branch, environment, reusable workflow가 OpenAI를 호출할지 정한다. 다음으로 OpenAI에서 identity provider를 만들고 issuer와 audience를 맞춘다. 세 번째로 service account mapping을 만들어 GitHub subject token의 안정적인 claim만 허용한다. 네 번째로 workflow에 id-token: write를 주고 OpenAI SDK의 WIF provider를 연결한다. 마지막으로 inference 호출과 실패 로그를 함께 검증한다.

1. GitHub에서 어떤 workflow와 environment를 허용할지 먼저 정한다.
2. OpenAI identity provider에 issuer와 audience를 맞춘다.
3. service account mapping에 안정적인 claim 조건을 넣는다.
4. workflow에 id-token: write와 WIF 환경변수를 준다.
5. 실제 SDK 호출로 token exchange와 inference 성공을 같이 확인한다.

실무에서는 먼저 subject claim을 과하게 좁히지 않는 편이 낫다. branch, environment, reusable workflow 경로처럼 바뀌지 않는 값으로 시작하고, 나중에 필요하면 더 세분화한다. 너무 자주 바뀌는 run id나 임시 값을 조건으로 넣으면 인증은 안전해 보여도 운영이 불안정해진다.

점검 메모 예시

provider:
  issuer: https://token.actions.githubusercontent.com
  audience: openai-prod-ci
mapping:
  project_service_account: sa_123
  stable_claims:
    - repo
    - ref
    - environment
workflow:
  permissions:
    id-token: write

이 과정을 거치면 GitHub secret에 장기 API key를 넣지 않아도 된다. 대신 provider, mapping, audience 세 값을 코드와 운영 문서에서 추적할 수 있게 남겨 두는 편이 중요하다.

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

첫 화면은 OpenAI의 workload identity federation 개요다. 여기서 장기 API 키를 저장하지 않고 외부 ID 토큰을 짧은 OpenAI access token으로 교환한다는 기본 전제를 먼저 확인해야 한다.

WIF 개요 문서는 외부 OIDC subject token을 OpenAI의 short-lived access token으로 교환하는 구조를 직접 보여 준다.

즉 이 기능의 목적은 키를 숨기는 편법이 아니라, CI 워크로드가 짧게 살아 있는 토큰으로만 호출하게 만드는 것이다. GitHub Actions처럼 job 수명이 짧은 환경과 궁합이 좋다.

두 번째로 보는 화면은 GitHub Actions 가이드의 workflow 권한 구간이다. 여기서 id-token 권한이 없으면 OpenAI WIF가 아니라 GitHub OIDC 자체가 열리지 않는다.

GitHub Actions 가이드는 workflow에 id-token: write 권한을 주고 OIDC 기반 subject token을 넘기라고 설명한다.

이 지점은 기존의 id-token: write가 없을 때 토큰 요청이 실패하는 글과 정확히 이어진다. WIF도 결국 GitHub OIDC 토큰이 있어야 시작된다.

세 번째 화면은 실제 subject token provider 예시다. OpenAI 문서는 GitHub가 노출하는 ACTIONS_ID_TOKEN_REQUEST_URL과 ACTIONS_ID_TOKEN_REQUEST_TOKEN 환경변수를 SDK provider에서 읽으라고 적고 있다.

SDK 예시는 GitHub가 job에 제공하는 OIDC 요청 환경변수를 받아 OpenAI WIF로 교환하는 흐름을 보여 준다.

실무에서는 여기서 provider id, service account id, audience 세 값을 같이 맞춰야 한다. 어느 하나라도 빗나가면 API 키가 없다는 사실만 남고 실제 토큰 교환은 성립하지 않는다.

네 번째 자료는 API reference의 제한 사항 구간이다. WIF access token이 모든 OpenAI API를 대체하는 것은 아니고, Admin API에는 쓸 수 없다는 점을 미리 알아야 설계가 꼬이지 않는다.

WIF reference는 Admin API 미지원과 provider 및 mapping 개수 제한 같은 운영 한계를 같이 적고 있다.

즉 WIF를 붙였다고 기존 관리성 API key를 모두 없앨 수 있는 것은 아니다. 실제 호출 대상이 inference용 프로젝트 API인지, 조직 관리성 Admin API인지 먼저 구분해야 한다.

workflow 파일에서는 어떤 값을 어디까지 GitHub job에 넘길지 명확히 남기는 편이 좋다. provider id와 service account id를 secret으로 숨기기보다, 환경변수 이름과 audience 조합을 문서화해 두면 나중에 추적이 쉽다.

GitHub Actions workflow 예시는 permissions, OpenAI WIF 설정값, 실제 SDK 실행 단계를 한 화면에 묶어 보여 준다.

여기서 핵심은 API key를 secrets에 넣지 않는 대신, job이 요청할 audience와 OpenAI 쪽 provider mapping이 정확히 짝을 이루어야 한다는 점이다.

마지막 자료는 API key와 WIF를 어떤 기준으로 나눌지 정리한 비교표다. 팀에서 바꾸려는 이유가 단순 보안 문구인지, 실제로 키 회전과 만료 문제를 줄이려는지 먼저 구분해야 한다.

API key 방식과 GitHub Actions WIF 방식은 노출면, 만료 전략, 운영 절차가 다르다.

이 표를 기준으로 보면 WIF는 설정 초기비용이 조금 있지만, CI 전용 비밀값을 없애고 짧은 토큰으로만 호출한다는 운영 이점이 분명하다.

5. 주의사항과 리스크

첫 번째 리스크는 WIF access token으로 Admin API까지 호출할 수 있다고 오해하는 것이다. 두 번째 리스크는 workflow를 너무 넓게 허용해 사실상 모든 CI job이 같은 OpenAI service account를 쓰게 만드는 것이다. 세 번째 리스크는 GitHub OIDC 토큰 claim을 구체적으로 읽지 않고 대충 audience만 맞춰 인증 범위를 넓히는 것이다.

운영 전에 확인할 때는 실제 GitHub workflow 파일, OpenAI provider 설정, service account mapping, 실패 로그를 같은 체크리스트에 넣는 편이 좋다. 인증 실패를 SDK 문제로만 보면 provider 조건 누락을 놓치기 쉽다.

• Admin API 호출은 WIF token만으로 대체되지 않을 수 있다.
• mapping 조건을 너무 넓게 두면 CI 범위가 과도해진다.
• audience만 맞추고 stable claim 검증을 생략하면 운영 범위가 과도하게 넓어진다.

6. 결론

OpenAI WIF를 GitHub Actions에 붙일 때 핵심은 API key 제거 자체가 아니라, GitHub OIDC subject token을 안전한 조건으로만 OpenAI short-lived access token으로 교환하게 만드는 데 있다. workflow의 id-token: write, provider audience, service account mapping, 호출 대상 API 범위를 함께 맞추면 장기 키 없이도 안정적으로 운영할 수 있다.

• workflow OIDC 권한부터 확인한다.
• provider와 mapping 조건을 안정적인 claim 기준으로 만든다.
• WIF token이 커버하는 API 범위를 먼저 구분한다.

7. 참고 링크

1. https://developers.openai.com/api/docs/guides/workload-identity-federation
2. https://developers.openai.com/api/docs/guides/workload-identity-federation/github-actions
3. https://developers.openai.com/api/reference/workload-identity-federation