워크로드 ID 페더레이션

워크로드 ID 페더레이션을 사용하면 개인용 액세스 토큰이나 다른 장기 OpenAI 자격 증명을 저장하지 않고도 신뢰할 수 있는 자동화에서 Codex를 사용할 수 있습니다. 워크로드는 이미 운영 중인 공급자의 단기 ID 토큰을 제시합니다. OpenAI는 해당 토큰을 확인하고 관리형 ChatGPT 작업 공간의 사용자 또는 서비스 계정에 대한 단기 액세스 토큰을 반환합니다.

OIDC 토큰 또는 SPIFFE JWT-SVID를 발급할 수 있는 클라우드 플랫폼, Kubernetes, CI 시스템 및 기타 환경의 무인 Codex 프로세스에는 워크로드 ID를 사용하세요. 공유 신뢰 모델과 별도의 OpenAI API 흐름에 대해서는 워크로드 ID 개요를 참조하세요.

시작하기 전에

다음이 필요합니다.

• OpenAI Admin Portal에서 워크로드 ID를 관리할 권한.
• 관리형 ChatGPT 작업 공간.
• 해당 작업 공간의 활성 구성원인 ChatGPT 사용자 또는 서비스 계정, 또는 설정 중 하나를 만들 수 있는 권한.
• 발급자, 대상 및 식별 클레임을 알고 있는 OIDC 토큰 또는 SPIFFE JWT-SVID.
• 절대 경로의 보호된 파일에서 해당 토큰을 최신 상태로 유지할 수 있는 런타임.
• Codex 0.148.0 이상.
• ChatGPT 인증과 페더레이션 규칙에서 선택한 작업 공간을 허용하는 유효한 Codex 인증 정책. 로그인 방식 또는 작업 공간 적용을 참조하세요.

OpenAI는 토큰 교환 중에 주체 또는 작업 공간 멤버십을 생성하지 않습니다. 관리자는 워크로드가 연결되기 전에 주체를 선택하거나 생성합니다. 사람 사용자를 생성하면 작업 공간 좌석이 사용되며 해당 작업 공간의 멤버십 규칙이 적용됩니다.

네이티브 Windows에서는 elevated Windows 샌드박스를 사용하세요. 다른 Windows 샌드박스 모드로는 모델이 제어하는 명령으로부터 ID 토큰 파일을 보호할 수 없습니다.

ID 토큰 가져오기

워크로드 런타임이 업스트림 ID 토큰을 가져오고 갱신합니다. Codex는 사용자를 대신하여 클라우드 메타데이터 서비스나 ID 공급자 클라이언트 라이브러리를 호출하지 않습니다.

공급자별 가이드에 따라 토큰 발급을 구성하고 샘플 토큰을 검사하세요.

• Microsoft Azure
• AWS
• Google Cloud
• Oracle Cloud Infrastructure
• GitHub Actions
• Kubernetes
• SPIFFE

샘플 토큰을 로컬에서 디코딩하고 iss, aud, sub 및 신뢰할 기타 클레임을 기록하세요. 디코딩은 서명을 확인하지 않습니다. 프로덕션 토큰을 웹사이트에 붙여 넣거나 로그에 기록하지 마세요.

워크로드 연결

관리자가 Codex를 시작하기 전에 공급자와 페더레이션 규칙을 생성합니다.

1. OpenAI Admin Portal에서 Workload identity를 연 다음 Connect workload를 선택합니다.
2. Codex용으로 구성된 공급자를 재사용하거나 새로 만듭니다. 공급자 사전 설정은 GitHub Actions, Microsoft Entra ID, Google Cloud, AWS, Kubernetes, SPIFFE 및 사용자 지정 OIDC 공급자의 일반적인 설정을 입력합니다.
3. Codex와 워크로드에서 사용할 수 있는 관리형 작업 공간을 선택합니다.
4. 워크로드를 식별하는 가장 제한적인 조건을 추가합니다. 주체, 정확한 클레임, CEL 조건 또는 이들의 조합을 일치시키세요. 허용 대상을 추가하여 규칙이 수락하는 토큰을 제한합니다. 구성된 모든 매처가 통과해야 합니다.
5. 규칙을 기존 ChatGPT 사용자 또는 서비스 계정 하나에 매핑하거나 설정 중 새로 만듭니다.
6. 공급자, 조건, 작업 공간, 주체, 범위 및 액세스 토큰 수명을 검토합니다. Connect workload를 선택한 다음 Download config를 선택합니다.

다운로드한 파일에는 비밀이 아닌 페더레이션 규칙 ID와 Codex가 ID 토큰을 읽을 경로가 포함됩니다. 자격 증명은 포함되지 않습니다.

설정을 자동화하려면 워크로드 ID Admin API를 사용하세요. 매처 동작 및 예시는 페더레이션 규칙 참조를 확인하세요.

Codex 프로세스 구성

Codex를 시작하는 프로세스에는 다음 두 워크로드 ID 변수가 필요합니다.

export OPENAI_FEDERATION_RULE_ID="idpm_..."
export OPENAI_IDENTITY_TOKEN_FILE="/var/run/secrets/openai.com/identity-token"

OPENAI_FEDERATION_RULE_ID은 비밀이 아닙니다. 토큰 파일은 비밀입니다. 워크로드 계정이 소유하고 모드가 0700인 /var/run/secrets/openai.com 같은 전용 디렉터리의 절대 경로를 사용하세요. 신뢰할 수 있는 호스트 프로세스만 해당 위치에 써야 합니다. 디렉터리를 저장소 및 Codex 도구에서 사용할 수 있는 다른 경로 외부에 두세요. 자격 증명을 로그, 셸 기록 및 빌드 아티팩트에 포함하지 마세요.

감사 기여 정보 추가

런타임 인스턴스가 페더레이션 규칙을 공유하는 경우 토큰 발급 감사 이벤트에서 각 인스턴스를 식별할 수 있습니다. 선택적 OPENAI_WORKLOAD_IDENTITY_CONTEXT 변수를 문자열로 인코딩된 JSON 객체로 설정하세요.

export OPENAI_WORKLOAD_IDENTITY_CONTEXT='{
  "instance_id": "runner-42",
  "display_name": "payments-prod",
  "labels": {
    "environment": "production",
    "region": "us-west-2"
  }
}'

객체에는 instance_id이 필요합니다. display_name 및 최대 8개의 레이블도 포함할 수 있습니다. 인코딩된 객체는 최대 1,024바이트일 수 있습니다. instance_id 및 display_name은 최대 128자일 수 있습니다. 레이블 키는 최대 64자, 레이블 값은 최대 256자일 수 있습니다.

식별자는 ASCII 문자나 숫자로 시작해야 합니다. 이후 값에는 문자, 숫자, ., _, :, /, @ 및 -을 사용할 수 있습니다. 레이블 키에는 문자, 숫자, ., _ 및 -을 사용할 수 있습니다.

OpenAI는 이 컨텍스트를 확인된 워크로드 ID가 아닌 클라이언트가 보고한 감사 기여 정보로 취급합니다. 인증, 권한 부여, 규칙 일치, 범위, 속도 제한, 해지, 기능 게이트 또는 메트릭에는 영향을 주지 않습니다. 자격 증명, 비밀, 개인 데이터, 프롬프트, 모델 출력 또는 기타 Customer Content를 포함하지 마세요.

유효한 컨텍스트의 경우 OpenAI는 테넌트, 공급자, 페더레이션 규칙 및 instance_id으로 범위가 지정된 안정적인 기여 정보 ID를 파생합니다. 기여 정보 목적으로 액세스 토큰에는 컨텍스트가 아닌 ID가 포함됩니다. 성공한 토큰 발급 감사 이벤트에는 ID와 정규화된 컨텍스트가 포함됩니다. 제한을 초과하거나 이 스키마를 위반하는 컨텍스트는 invalid_grant 오류와 함께 교환에 실패합니다.

Codex는 프로세스 시작 시 컨텍스트를 읽으며, 컨텍스트, 규칙 ID 또는 토큰 파일 경로를 모델이 제어하는 셸, 후크 또는 MCP 서버에 전달하지 않습니다. 컨텍스트를 변경한 후에는 Codex를 다시 시작하세요.

토큰 파일 보호 및 교체

관리형 Linux, macOS 및 WSL 배포에서는 토큰 디렉터리 전체를 관리형 요구 사항의 permissions.filesystem.deny_read에 추가하세요.

[permissions.filesystem]
deny_read = ["/var/run/secrets/openai.com"]

이렇게 하면 모델이 제어하는 명령이 활성 토큰이나 임시 교체 파일을 읽지 못하도록 차단하면서 Codex 호스트 프로세스는 계속 토큰을 교환에 사용할 수 있습니다. 프로젝션된 토큰 볼륨의 경우 토큰 마운트 전체와 그 외부의 모든 백업 경로 또는 확인된 대상 경로를 거부하세요. 파일 모드와 환경 변수 제거만으로는 동일한 사용자로 실행되는 다른 프로세스로부터 자격 증명을 보호할 수 없습니다. 네이티브 Windows에서는 위에서 설명한 elevated 샌드박스를 사용하세요.

파일을 프로젝션하지 않는 토큰 소스의 경우 신뢰할 수 있는 호스트 프로세스가 해당 보호 디렉터리 안에 각 교체 파일을 쓴 후 이름을 바꾸어 제자리에 배치하도록 하세요. 원자적 이름 바꾸기는 Codex가 불완전한 토큰을 읽는 것을 방지합니다. 예를 들어 다음 호스트 소유 갱신 스크립트를 공급자의 토큰 명령에 맞게 조정하세요. 스크립트를 실행하기 전에 디렉터리를 프로비저닝하세요.

set -eu
TOKEN_DIR="/var/run/secrets/openai.com"
TOKEN_FILE="$TOKEN_DIR/identity-token"
umask 077
TOKEN_TEMP="$(mktemp "$TOKEN_DIR/.identity-token.XXXXXX")"
trap 'rm -f -- "$TOKEN_TEMP"' EXIT
trap 'exit 1' HUP INT TERM
your-identity-provider-command > "$TOKEN_TEMP"
test -s "$TOKEN_TEMP"
mv -f -- "$TOKEN_TEMP" "$TOKEN_FILE"

Codex가 제어할 수 있는 셸이나 도구 외부에서 갱신 프로세스를 실행하세요. 갱신 및 정리 중에도 읽기 거부를 유지하세요. 강제 중지로 임시 파일이 남더라도 해당 파일은 거부된 디렉터리 안에 있어야 합니다. 워크로드 ID 설정을 config.toml에 넣지 마세요.

연결 확인

다운로드한 환경을 로드하고 선택된 인증 방식을 검사하세요.

. ./workload-identity-idpm_example.env
codex login status

PowerShell에서는 다음을 실행합니다.

$env:OPENAI_FEDERATION_RULE_ID = "idpm_..."
$env:OPENAI_IDENTITY_TOKEN_FILE = "C:\run\openai\identity-token"
codex login status

검사에 성공하면 Logged in using workload identity이 출력됩니다. 이는 Codex가 구성된 페더레이션 규칙을 통해 토큰을 교환했음을 확인합니다. 명령은 확인된 작업 공간, 주체 또는 규칙을 출력하지 않습니다. 워크로드를 시작하기 전에 Admin Portal에서 해당 값을 확인하세요. Codex가 다른 인증 방식을 보고하면 필수 WIF 변수 두 개가 프로세스에 전달되지 않은 것입니다.

공급자에서 Prevent assertion replay를 사용하고 어설션에 jti 클레임이 있으면 이 검사에서 해당 jti을 사용합니다. 다른 Codex 프로세스를 시작하기 전에 새 jti이 있는 새로 발급된 어설션을 기록하세요.

동일한 환경에서 작은 요청을 실행하세요.

codex exec "Reply with only: workload identity is working"

Codex는 업스트림 토큰을 교환하고 OpenAI 액세스 토큰을 메모리에 보관합니다. 어느 자격 증명도 auth.json, 시스템 키링 또는 config.toml에 기록하지 않습니다.

토큰을 최신 상태로 유지

업스트림 토큰이 만료되기 전에 ID 토큰 파일을 갱신하세요. Codex는 다른 OpenAI 액세스 토큰이 필요할 때 파일을 다시 읽습니다. OpenAI 토큰은 업스트림 토큰의 만료 시점과 페더레이션 규칙의 수명 중 더 이른 시점에 만료되며, 최대 한 시간을 초과하지 않습니다.

관리자가 재생 방지를 사용 설정하면 각 업스트림 JWT에 고유한 jti이 있어야 합니다. 장기 실행 프로세스의 갱신을 포함하여 각 교환 전에 새 jti이 있는 새로 발급된 어설션을 기록하세요. jti이 없는 어설션에는 재생 방지가 적용되지 않습니다.

Codex는 각 호스트 프로세스 내부에서 하나의 메모리 내 교환 세션을 공유합니다. 해당 프로세스의 동시 요청은 유효한 OpenAI 액세스 토큰을 재사용하고 만료 시 하나의 갱신을 공유합니다. 별도 프로세스는 별도로 교환하므로 공급자가 각 프로세스의 사용을 허용하는 어설션이 필요합니다.

자격 증명 우선순위

필수 워크로드 ID 변수 두 개는 다른 모든 자격 증명 소스보다 우선합니다.

1. OPENAI_FEDERATION_RULE_ID 또는 OPENAI_IDENTITY_TOKEN_FILE 중 하나라도 있으면 Codex는 워크로드 ID를 선택합니다.
2. 필수 변수 중 하나만 있으면 Codex가 오류를 반환합니다. API key, 액세스 토큰 또는 저장된 로그인으로 대체하지 않습니다.
3. OPENAI_WORKLOAD_IDENTITY_CONTEXT만으로는 워크로드 ID가 선택되지 않습니다.
4. 필수 WIF 변수가 모두 없으면 Codex는 해당 경로의 일반 자격 증명 규칙을 적용합니다. API key 인증을 허용하는 경로에서는 CODEX_API_KEY이 codex exec, codex review, TypeScript SDK 및 codex exec-server --remote에서 우선합니다. 다른 경로에서는 CODEX_ACCESS_TOKEN 또는 저장된 로그인을 사용할 수 있습니다.

SDK apiKey 옵션은 CODEX_API_KEY이 되지만, 필수 WIF 변수 중 하나라도 있으면 WIF가 여전히 우선합니다. WIF를 사용할 때는 워크로드에 사용되지 않는 장기 자격 증명이 포함되지 않도록 이 옵션을 생략하세요.

기존 워크로드를 중단 없이 이전하려면 현재 자격 증명을 계속 사용할 수 있는 동안 WIF를 구성하세요. 필수 WIF 변수 두 개를 모두 사용하여 새 프로세스를 시작합니다. 이전 자격 증명이 여전히 있어도 WIF가 우선합니다. 워크로드가 WIF에서 성공하면 런타임과 비밀 저장소에서 이전 자격 증명을 제거한 후 해지하세요. 해지 전에는 필수 WIF 변수 두 개를 모두 제거하고 새 프로세스를 시작하여 롤백할 수 있습니다.

지원되는 Codex 경로

Codex 프로세스를 소유하는 머신에서 워크로드 ID를 구성하세요.

원격 app-server 및 exec-server 클라이언트는 프로토콜을 통해 업스트림 ID 토큰을 전송하지 않습니다.

액세스 변경 또는 제거

규칙의 주체, 대상, 클레임, CEL 조건, 범위 또는 토큰 수명에 대한 변경 사항은 새 교환에 적용됩니다. 변경 전에 발급된 토큰은 수명이 끝날 때까지 유효할 수 있습니다.

공급자 또는 규칙을 비활성화하면 액세스가 즉시 중지됩니다. 비활성화하면 새 교환이 차단되고 해당 리소스를 통해 이미 발급된 OpenAI 액세스 토큰이 해지됩니다. 보관 처리도 액세스에 동일한 영향을 미치며 실행 취소할 수 없습니다. 공급자 신뢰를 변경하면 새 신뢰가 적용되기 전에 발급된 토큰도 해지됩니다.

변경 사항 감사

공급자 및 페더레이션 규칙의 생성, 업데이트 및 보관 처리는 감사 이벤트를 생성합니다. Compliance API 및 감사 이벤트 지침을 사용하여 작업 공간에서 지원하는 이벤트를 내보내세요. ID 공급자의 발급 로그와 연계하고, 어느 시스템에도 업스트림 어설션이나 OpenAI 액세스 토큰을 기록하지 마세요.

프로세스에서 OPENAI_WORKLOAD_IDENTITY_CONTEXT을 제공하면 성공한 토큰 발급 감사 이벤트에도 위에서 설명한 안정적인 기여 정보 ID와 정규화된 컨텍스트가 포함됩니다.

문제 해결

공급자 확인, 제한 및 CEL 세부 정보는 페더레이션 규칙 참조를 확인하세요.