Workload identity federation

워크로드 아이덴티티 페더레이션(workload identity federation)은 신뢰되는 워크로드가 OpenAI API 키나 ChatGPT 자격 증명을 저장하는 대신 이미 가진 아이덴티티를 사용할 수 있게 해줘요. 워크로드는 아이덴티티 제공자(identity provider)의 단기 토큰을 제시하고, OpenAI는 그것을 단기 OpenAI 액세스 토큰으로 교환해요.

출처: 문서

본문

OpenAI API 워크로드는 또한 X.509 워크로드 아이덴티티 페더레이션을 통해 검증된 인증서 아이덴티티를 교환할 수 있어요.

워크로드 아이덴티티 페더레이션은 OpenAI API 또는 Codex와 함께 사용할 수 있어요.

	OpenAI API	Codex
OpenAI 아이덴티티	API Platform 프로젝트의 서비스 계정	관리형 ChatGPT 워크스페이스의 사용자 또는 서비스 계정
관리자가 설정하는 곳	OpenAI Platform	OpenAI Admin Portal
워크로드 연결 방법	OpenAI SDK 또는 토큰 교환 엔드포인트	Codex 환경 변수와 아이덴티티 토큰 파일
액세스 토큰이 사용할 수 있는 것	매핑된 서비스 계정에 사용 가능한 API와 권한	매핑된 워크스페이스 주체에 사용 가능한 Codex 액세스

두 경로 모두 같은 신뢰 모델을 사용하지만, 관리와 런타임 구성은 달라요. 아래의 공유 개념과 아이덴티티 제공자 지침부터 시작한 다음 워크로드가 사용하는 제품에 대한 섹션을 따르세요.

OpenAI API: OpenAI API와 함께 워크로드 아이덴티티 사용으로 계속하세요.
Codex: Codex와 함께 워크로드 아이덴티티 사용을 참고하세요.

규칙과 수명 주기 동작은 Codex 페더레이션 규칙 레퍼런스를 참고하세요.

작동 방식

관리자는 워크로드가 연결되기 전에 세 가지를 구성해요.

아이덴티티 제공자는 OpenAI에 어떤 외부 발행자(issuer)를 신뢰할지, 그리고 서명된 토큰이나 인증서 아이덴티티를 어떻게 검증할지 말해줘요.
액세스 규칙은 OpenAI가 수락하는 토큰 속성과 워크로드가 활동할 수 있는 OpenAI 아이덴티티를 설명해요. OpenAI API 구성은 이를 서비스 계정 매핑(service account mapping)이라고 불러요. Codex 구성은 이를 페더레이션 규칙(federation rule)이라고 불러요.
OpenAI 주체는 결과 액세스를 받아요. OpenAI API의 경우 주체는 Platform 서비스 계정이에요. Codex의 경우 주체는 관리형 워크스페이스의 ChatGPT 사용자 또는 서비스 계정이에요.

런타임에서:

워크로드는 단기 OIDC JWT 또는 SPIFFE JWT-SVID를 받거나, OpenAI API 워크로드는 X.509 인증서를 제시해요.
워크로드는 해당 제품이 요구하는 ID와 함께 외부 아이덴티티를 제시해요.
OpenAI는 토큰 또는 인증서를 검증한 다음 구성된 매핑 또는 규칙을 평가해요.
OpenAI는 매핑된 주체에 대한 단기 액세스 토큰을 반환해요.

토큰 교환은 주체, 프로젝트 또는 워크스페이스 멤버십을 절대 생성하지 않아요. 관리자는 설정 중에 해당 리소스를 생성하거나 선택해요.

아이덴티티 토큰 얻기

워크로드가 실행되는 환경에 맞는 가이드를 선택하세요.

X.509 인증서: OpenAI API 워크로드에 대한 인증서 기반 교환을 구성해요.
Kubernetes: 자체 관리 클러스터에서 projected service account 토큰을 사용해요.
AWS: 아웃바운드 아이덴티티 페더레이션 또는 Amazon EKS projected 토큰을 사용해요.
Microsoft Azure: managed identity 토큰 또는 AKS projected service account 토큰을 사용해요.
Google Cloud: 메타데이터 서버 아이덴티티 토큰 또는 GKE projected service account 토큰을 사용해요.
Oracle Cloud Infrastructure: Oracle 아이덴티티 도메인의 instance principal 토큰을 사용해요.
GitHub Actions: 지속적 통합 워크플로에서 OIDC 토큰을 사용해요.
SPIFFE: SPIRE 또는 호환 제공자에서 발행한 SPIFFE JWT-SVID를 사용해요.

OpenAI는 문서화된 구성에서 SPIFFE JWT-SVID를 포함한 OIDC 호환 JWT 주체 토큰을 지원해요. OpenAI API의 경우 OIDC 제공자가 목록에 없으면 OpenAI 지원에 문의하세요. Codex의 경우 OpenAI Admin Portal에서 Custom OIDC를 선택하세요.

각 OIDC 제공자 가이드는 토큰을 발행하고 검사하는 방법을 설명해요. Codex의 경우 토큰 발행 단계만 따르고 Codex와 함께 워크로드 아이덴티티 사용으로 돌아가세요. 가이드의 OpenAI 설정과 SDK 예시는 OpenAI API 경로에 적용돼요. X.509 페더레이션은 OpenAI API 경로만 지원해요.

OpenAI API와 함께 워크로드 아이덴티티 사용

워크로드가 OpenAI API를 직접 호출할 때 이 경로를 사용하세요. 조직에 대한 Workload Identity Providers와 서비스 계정 매핑을 관리할 권한이 필요해요.

Organization Settings > Security > Workload Identity Provider로 이동하세요. 먼저 제공자를 만든 다음, 제공자 세부 정보 페이지에서 서비스 계정 매핑을 구성하세요.

X.509 제공자

X.509 제공자는 OpenAI가 조직의 기존 Mutual TLS 구성에 대해 검증하는 클라이언트 인증서에서 워크로드 아이덴티티 속성을 파생해요. 인증서를 저장하거나 별도의 신뢰 저장소를 유지하지 않아요.

제공자를 만들기 전에 Organization Settings > Security > Mutual TLS에서 클라이언트 인증서를 앵커하는 신뢰된 인증서를 구성하고 활성화하세요. Mutual TLS 가이드는 권한, 인증서 요구사항, 활성화 범위, mTLS 호스트, 인증서 체인 동작, CEL 필터, 회전을 설명해요.

다음으로 X.509 제공자를 만들고 비어 있지 않은 openai.subject 값을 하나 파생한 다음, 그 아이덴티티를 워크로드가 필요로 하는 권한만 가진 프로젝트 서비스 계정에 매핑하세요. 워크로드는 X.509 토큰 엔드포인트에 인증서를 제시해 단기 bearer 토큰을 얻은 다음, bearer 토큰과 수락된 클라이언트 인증서를 API mTLS 엔드포인트로 보내요.

전체 대시보드와 요청 흐름은 X.509 인증서 설정 가이드를 따르세요.

OIDC Workload Identity Provider 구성

신뢰하는 각 외부 발행자에 대해 Workload Identity Provider를 만드세요. OpenAI API 워크로드 아이덴티티는 OIDC JWT 주체 토큰을 지원해요. 그 구성은 다음을 포함해요.

옵션	설명
Name	조직에서 Workload Identity Provider의 고유 이름.
OIDC Issuer URL	예상 OIDC 발행자 URL. 발행자 비교는 뒤따르는 슬래시를 무시해요.
Audience	외부 주체 토큰의 예상 `aud` 클레임.
Description	Workload Identity Provider의 선택적 설명.
Use custom URL for OIDC discovery	활성화하면 OpenAI가 토큰 발행자와 다를 수 있는 공개 HTTPS URL에서 OIDC 디스커버리 메타데이터를 가져와요.
Custom OIDC discovery URL	커스텀 디스커버리가 활성화될 때 사용하는 디스커버리 기본 URL 또는 완전한 `/.well-known/openid-configuration` URL.
Use uploaded JWKS for token verification	활성화하면 OpenAI가 OIDC 디스커버리에서 키를 가져오는 대신 업로드된 JWKS에 대해 토큰을 검증해요.
JWKS JSON	업로드된 JWKS 검증이 활성화될 때 사용하는 업로드된 공개 JWKS 객체. JWKS는 비어 있지 않은 `keys` 배열을 포함해야 하고 비밀 키 자료가 없어야 해요.
Attribute transformations	매핑 결정을 위해 토큰 클레임에서 커스텀 `openai.*` 속성을 파생하는 선택적 CEL 표현식.

Custom OIDC discovery와 uploaded JWKS는 상호 배타적이에요. 커스텀 디스커버리를 활성화하면 업로드된 JWKS 옵션이 숨겨져요. 커스텀 디스커버리 URL은 공개 HTTPS를 사용해야 하고 자격 증명, 커스텀 포트, 쿼리 또는 프래그먼트를 포함할 수 없어요.

대시보드에 Use custom URL for OIDC discovery가 나타나지 않으면 표준 OIDC 디스커버리를 사용하거나 Use uploaded JWKS for token verification을 활성화하세요. 아이덴티티 제공자가 게시한 공개 JWKS를 사용하고 제공자가 서명 키를 회전할 때 업데이트하세요.

토큰 발행자와 디스커버리 호스트가 다를 때 OIDC Issuer URL을 토큰의 iss 클레임으로 설정하고 Custom OIDC discovery URL을 제공자의 디스커버리 문서를 게시하는 호스트로 설정하세요. OpenAI는 여전히 구성된 발행자에 대해 토큰을 확인해요. 커스텀 URL은 디스커버리 메타데이터와 공개 서명 키를 어디서 가져올지만 결정해요.

CEL로 토큰 클레임 변환

속성 변환(attribute transformations)은 Common Expression Language (CEL)을 사용해요. OpenAI는 langdef.md에 지정된 표준 CEL 연산자를 지원하고 커스텀 워크로드 아이덴티티 페더레이션 함수를 추가하지 않아요. 각 표현식은 하나의 루트 객체를 받아요.

assertion: 검증된 JWT 클레임 집합.

대시보드는 자동으로 openai. 접두사를 적용해요. subject 같은 접미사와 assertion.sub 같은 표현식을 입력하세요. API는 파생 속성을 openai.subject로 저장해요.

[
  {
    "attribute": "openai.subject",
    "expression": "assertion.sub"
  },
  {
    "attribute": "openai.repository",
    "expression": "assertion.repository"
  }
]

CEL 언어 사양에 정의된 CEL 구문을 사용하세요. 예를 들어 assertion.sub 또는 assertion.repository 같은 표현식으로 클레임 값을 읽을 수 있어요. 지원되지 않는 구문이나 함수는 매핑 해석을 실패시켜요.

[
  {
    "attribute": "openai.repository_ref",
    "expression": "assertion.repository + \"@\" + assertion.ref"
  },
  {
    "attribute": "openai.production",
    "expression": "assertion.ref == \"refs/heads/main\""
  }
]

변환 결과는 스칼라 값이어야 해요: 문자열, true 또는 false 값, 정수 또는 유한 숫자. 배열, 객체, null 값 및 평가 오류는 매핑 해석을 실패시켜요. OpenAI는 매핑 값과 비교하기 전에 스칼라 변환 결과를 문자열로 변환해요. 예를 들어 true는 "true"가 되고 7은 "7"이 돼요.

openai.로 시작하는 매핑 키는 속성 변환에서만 해석돼요. 이미 openai. 접두사를 사용하는 원시 주체 토큰 클레임은 일치하는 변환을 구성하지 않으면 매핑 결정에 영향을 주지 않아요.

JWKS와 키 회전 관리

OpenAI는 Workload Identity Provider에 구성된 키 소스로 OIDC 주체 토큰을 검증해요.

OIDC discovery: OpenAI는 발행자의 /.well-known/openid-configuration을 가져온 다음 발견된 jwks_uri를 가져와요. OpenAI는 디스커버리 문서와 원격 JWKS 페이로드를 600초 동안 캐시해요.
Custom OIDC discovery: OpenAI는 구성된 커스텀 디스커버리 기본 URL에서 /.well-known/openid-configuration을 가져온 다음 발견된 jwks_uri를 가져와요. 토큰의 iss 클레임은 여전히 OIDC Issuer URL과 일치해야 해요.
Miss 시 키 새로고침: 토큰 kid가 캐시된 JWKS에서 발견되지 않으면 OpenAI는 JWKS를 새로고침하고 토큰을 거부하기 전에 조회를 다시 시도해요.
Uploaded JWKS: Use uploaded JWKS for token verification이 활성화되면 OpenAI는 제공자에 저장된 업로드된 JWKS를 사용하고 OIDC 디스커버리나 원격 JWKS 가져오기를 수행하지 않아요. 제공자 업데이트가 토큰 교환에 사용 가능해지면 새 교환이 저장된 JWKS를 사용해요.
키 집합: JWKS는 하나 이상의 공개 키를 포함할 수 있어요. 각 키는 고유하고 비어 있지 않은 kid를 가져야 해요.

서명 키 회전 중에는 회전 창 동안 발행자 JWKS에 이전 공개 키와 새 공개 키를 모두 게시하세요. 이렇게 하면 이전 키로 서명된 토큰이 계속 작동하는 동안 OpenAI가 새 키로 서명된 토큰을 수락할 수 있어요. 업로드된 JWKS의 경우 새 kid로 토큰을 발행하기 전에 제공자를 업데이트하세요. OpenAI는 구성된 JWKS에 없는 키로 서명된 토큰을 거부해요.

서비스 계정 매핑 구성

서비스 계정 매핑은 어떤 외부 아이덴티티가 OpenAI 서비스 계정에 대한 액세스 토큰을 만들 수 있는지 정의해요.

X.509 제공자의 경우 매핑 키는 파생된 openai.* 속성을 사용해요. 정확한 openai.subject 매핑을 선호하세요. sub, aud, iss 같은 원시 JWT 클레임은 OIDC 제공자에만 적용돼요.

그 구성은 다음을 포함해요.

옵션	설명
Name	Workload Identity Provider 내 매핑의 고유 이름.
Key	일치시킬 속성 키. `sub`, `aud`, `iss` 같은 원시 토큰 클레임 또는 `openai.subject` 같은 파생 속성을 사용하세요.
Value	OpenAI가 토큰을 발행하기 전에 일치해야 하는 속성 값.
Description	매핑의 선택적 설명.
Project	대상 서비스 계정을 소유한 프로젝트.
Service account	워크로드가 사용할 수 있는 서비스 계정. 선택한 프로젝트에서 새 서비스 계정을 만들거나 기존 서비스 계정을 선택할 수 있어요.
Permissions	이 매핑에서 만들어진 액세스 토큰을 더 좁히는 선택적 API 권한. 이 권한은 매핑된 서비스 계정을 넘어 접근을 부여할 수 없어요.

속성 값은 스칼라 JSON 값이어야 해요. 문자열 값은 비어 있지 않은 접두사가 있는 하나의 뒤따르는 와일드카드(예: repo:example/*)를 사용할 수 있어요. 와일드카드 자체 또는 값 중간의 와일드카드는 지원되지 않아요.

유효한 와일드카드 값:

repo:openai/*
repository:my-org/*

지원되지 않는 와일드카드 값:

*
repo:*:prod
repo/*/main

대시보드는 매핑 제한을 Permissions로 표시해요. 토큰 교환 응답은 scope 속성에서 같은 제한을 OAuth 스코프로 노출해요. 매핑은 Admin API 스코프를 포함할 수 없고, 일반적인 다운스트림 API 권한 부여는 여전히 적용돼요.

매핑 해석 예시

매핑 해석은 OpenAI가 외부 아이덴티티를 검증한 후 시작돼요. OpenAI는 요청된 identity_provider_id와 service_account_id에 대한 매핑을 찾고, 활성화되지 않은 매핑을 건너뛰고, 각 매핑에 필요한 속성만 평가하며, 정확히 하나의 활성 매핑이 모든 구성된 속성과 일치할 때만 토큰을 발행해요.

GitHub Actions 토큰이 다음 클레임을 포함한다고 가정해요:

{
  "iss": "https://token.actions.githubusercontent.com",
  "aud": "https://api.openai.com/v1",
  "sub": "repo:my-org/my-repo:ref:refs/heads/main",
  "repository": "my-org/my-repo",
  "ref": "refs/heads/main"
}

제공자는 속성을 파생할 수 있어요:

[
  {
    "attribute": "openai.repository_ref",
    "expression": "assertion.repository + \"@\" + assertion.ref"
  }
]

그런 다음 서비스 계정 매핑은 원시 속성과 파생 속성을 모두 요구할 수 있어요:

Key	Value
`iss`	`https://token.actions.githubusercontent.com`
`sub`	`repo:my-org/my-repo:*`
`openai.repository_ref`	`my-org/my-repo@refs/heads/main`

세 값 모두 일치해야 해요. sub 값은 뒤따르는 와일드카드를 사용하므로 접두사 repo:my-org/my-repo:가 있는 모든 값과 일치해요. openai.repository_ref 키는 그 이름의 원시 토큰 클레임이 아니라 속성 변환에서 해석돼요.

교환에 둘 이상의 활성 매핑이 일치하면 OpenAI는 거부해요. OpenAI는 각 (provider, service account) 쌍에 대해 고유한 매핑을 적용하고 서로 다른 매핑의 권한을 결합하지 않아요.

워크로드 연결

아이덴티티 제공자 가이드의 SDK 예시를 사용하거나 토큰 교환 엔드포인트를 직접 호출하세요. 요청·응답 필드, 권한 부여 동작, 현재 제한은 워크로드 아이덴티티 토큰 교환 레퍼런스를 참고하세요.

액세스 토큰 갱신

토큰 교환을 직접 관리한다면 자격 증명을 토큰 서비스에서 애플리케이션으로 전달할 때 access_token과 expires_at을 함께 유지하세요. expires_at 필드는 초 단위 Unix 타임스탬프로 표현된 절대 UTC 만료예요. 시계 차이와 요청 지연을 고려해 그 시간보다 미리 갱신을 예약하세요.

expires_in 필드는 발행으로부터의 토큰 수명(초)이에요. 예를 들어 12:00 UTC에 발행되고 expires_in: 3600인 토큰은 다른 서비스가 12:05 UTC에 받아도 13:00 UTC에 만료돼요. 전송과 처리 시간은 토큰 수명을 연장하지 않아요. 자세한 내용은 응답 필드를 참고하세요.

토큰 교환은 refresh token을 반환하지 않아요. 갱신하려면 유효한 외부 아이덴티티 토큰이나 클라이언트 인증서로 교환을 반복하세요.

Codex와 함께 워크로드 아이덴티티 사용

관리형 ChatGPT 워크스페이스에서 신뢰되는 Codex 자동화에 이 경로를 사용하세요. Codex는 워크로드를 API Platform 서비스 계정 대신 ChatGPT 사용자 또는 서비스 계정에 매핑해요.

Codex 워크로드 아이덴티티 페더레이션은 베타이며 워크스페이스에 대해 활성화되어 있어야 해요. 접근을 요청하려면 OpenAI 담당자 또는 OpenAI Support에 연락하세요.

페더레이션 규칙 레퍼런스는 하나의 규칙이 하나의 ChatGPT 주체에 매핑하면서 둘 이상의 외부 주체를 수락할 수 있는 방법을 설명해요.

연결 문제 해결

OpenAI가 아이덴티티 토큰을 거부

토큰을 로컬에서 디코딩하고 iss, aud, sub, exp, iat 및 제공자 특정 클레임을 구성된 제공자와 비교하세요. 프로덕션 토큰을 제3자 JWT 도구에 붙여넣지 마세요.

OpenAI API의 경우 토큰 속성을 선택한 서비스 계정 매핑과도 비교하세요. Codex의 경우 선택한 페더레이션 규칙과 비교하세요.

OpenAI API 매핑이 일치하지 않음

요청이 의도한 아이덴티티 제공자와 서비스 계정 ID를 사용하는지, 매핑이 활성인지, 정확히 하나의 매핑이 일치하는지 확인하세요. 자세한 오류 범주는 토큰 교환 오류 레퍼런스를 참고하세요.

Codex가 구성이 불완전하다고 보고

Codex 프로세스에 두 필수 워크로드 아이덴티티 환경 변수가 있고 OPENAI_IDENTITY_TOKEN_FILE이 현재 토큰의 절대 경로를 포함하는지 확인하세요. 파일과 부모 디렉터리 권한을 확인하세요.

Codex가 다른 자격 증명을 사용

두 필수 워크로드 아이덴티티 변수를 Codex 프로세스에 로드하세요. 두 변수 중 하나의 존재가 API 키, 액세스 토큰, 저장된 로그인보다 WIF를 먼저 선택하게 해요. 다운로드한 구성을 로드한 상태로 새 프로세스를 시작한 다음 codex login status를 다시 실행하세요.

보안 권장 사항

각 애플리케이션 또는 워크로드에 전용 주체를 사용하세요.
프로덕션과 비프로덕션 환경을 분리하세요.
넓은 패턴보다 정확한 클레임 일치를 선호하세요.
워크로드가 필요한 액세스만 부여하세요.
짧은 액세스 토큰 수명을 사용하세요.
사용하지 않는 제공자, 매핑, 규칙을 검토하고 제거하세요.
토큰 교환 오류와 예기치 않은 액세스 패턴을 검토하세요.

Workload identity federation