워크로드 ID 페더레이션

워크로드 ID 페더레이션을 사용하면 신뢰할 수 있는 워크로드가 OpenAI API 키나 ChatGPT 자격 증명을 저장하지 않고도 기존 ID로 인증할 수 있습니다. 워크로드가 ID 공급자로부터 받은 단기 토큰을 제시하면 OpenAI가 이를 단기 OpenAI 액세스 토큰으로 교환합니다.

OpenAI API 워크로드는 X.509 워크로드 ID 페더레이션을 통해 검증된 인증서 ID도 액세스 토큰으로 교환할 수 있습니다.

OpenAI API와 Codex에서는 각각 다음과 같이 워크로드 ID 페더레이션을 사용합니다.

두 방식은 같은 신뢰 모델을 사용하지만 관리 방법과 런타임 설정이 다릅니다. 먼저 아래의 공통 개념과 ID 공급자별 안내를 확인한 다음, 워크로드에서 사용하는 제품에 해당하는 섹션을 따르세요.

• OpenAI API: OpenAI API에서 워크로드 ID 사용으로 이동하세요.
• Codex: Codex에서 워크로드 ID 사용을 참고하세요.

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

작동 방식

워크로드를 연결하기 전에 관리자가 다음 세 가지를 설정합니다.

1. ID 공급자 설정에서는 OpenAI가 신뢰할 외부 발급자와 해당 발급자가 서명한 토큰 또는 인증서 ID를 검증하는 방법을 지정합니다.
2. 액세스 규칙은 OpenAI가 허용하는 토큰 속성과 워크로드가 어떤 OpenAI ID로 작업할 수 있는지를 정의합니다. OpenAI API 설정에서는 이를 서비스 계정 매핑이라고 하고, Codex 설정에서는 페더레이션 규칙이라고 합니다.
3. OpenAI 주체는 이 설정에 따라 액세스 권한을 부여받습니다. OpenAI API에서는 플랫폼 서비스 계정이 주체입니다. Codex에서는 관리형 워크스페이스의 ChatGPT 사용자 또는 서비스 계정이 주체입니다.

런타임에는 다음 순서로 인증이 진행됩니다.

1. 워크로드가 단기 OIDC JWT 또는 SPIFFE JWT-SVID를 받습니다. OpenAI API 워크로드는 대신 X.509 인증서를 제시할 수도 있습니다.
2. 워크로드가 외부 ID를 해당 제품에서 요구하는 ID와 함께 제시합니다.
3. OpenAI가 토큰 또는 인증서를 검증한 다음 설정된 매핑이나 규칙을 평가합니다.
4. OpenAI가 매핑된 주체의 단기 액세스 토큰을 반환합니다.

토큰을 교환할 때 주체, 프로젝트 또는 워크스페이스 멤버십이 생성되지는 않습니다. 관리자가 설정 단계에서 해당 리소스를 생성하거나 선택합니다.

ID 토큰 받기

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

OpenAI는 문서에 안내된 구성에서 SPIFFE JWT-SVID를 비롯한 OIDC 호환 JWT 주체 토큰을 지원합니다. OpenAI API를 사용하는데 OIDC 공급자가 목록에 없다면 OpenAI 지원팀에 문의하세요. Codex의 경우 OpenAI 관리 포털에서 Custom OIDC를 선택하세요.

각 OIDC 공급자 가이드에서는 토큰을 발급하고 내용을 확인하는 방법을 설명합니다. Codex를 사용한다면 토큰 발급 단계만 따른 다음 Codex에서 워크로드 ID 사용으로 돌아가세요. 가이드의 OpenAI 설정과 SDK 예제는 OpenAI API에 연결할 때 적용됩니다. X.509 페더레이션은 OpenAI API 연결만 지원합니다.

OpenAI API에서 워크로드 ID 사용

워크로드가 OpenAI API를 직접 호출하는 경우 이 절차를 따르세요. 조직의 워크로드 ID 공급자와 서비스 계정 매핑을 관리할 권한이 필요합니다.

조직 설정 > 보안 > 워크로드 ID 공급자로 이동하세요. 먼저 공급자를 생성한 다음 공급자 세부 정보 페이지에서 서비스 계정 매핑을 설정하세요.

X.509 공급자

X.509 공급자는 클라이언트 인증서에서 워크로드 ID 속성을 도출합니다. OpenAI는 조직의 기존 상호 TLS 설정을 기준으로 이 인증서를 검증합니다. X.509 공급자는 인증서를 저장하거나 별도의 신뢰 저장소를 유지하지 않습니다.

공급자를 생성하기 전에 조직 설정 > 보안 > 상호 TLS에서 클라이언트 인증서의 신뢰 기준이 되는 인증서를 설정하고 활성화하세요. 상호 TLS 가이드에서는 권한, 인증서 요구 사항, 활성화 범위, mTLS 호스트, 인증서 체인의 동작 방식, CEL 필터, 인증서 교체를 설명합니다.

다음으로 X.509 공급자를 생성하고 비어 있지 않은 openai.subject 값 하나를 도출하세요. 해당 ID를 워크로드에 필요한 권한만 가진 프로젝트 서비스 계정에 매핑하세요. 워크로드는 X.509 토큰 엔드포인트에 인증서를 제시해 단기 전달자 토큰을 받은 다음, 전달자 토큰과 허용된 클라이언트 인증서를 API mTLS 엔드포인트로 전송합니다.

대시보드 설정부터 요청 전송까지의 전체 절차는 X.509 인증서 설정 가이드를 따르세요.

OIDC 워크로드 ID 공급자 설정

신뢰하는 외부 발급자마다 워크로드 ID 공급자를 생성하세요. OpenAI API의 워크로드 ID는 OIDC JWT 주체 토큰을 지원합니다. 설정 항목은 다음과 같습니다.

사용자 지정 OIDC 검색과 업로드한 JWKS는 함께 사용할 수 없습니다. 사용자 지정 검색을 활성화하면 업로드한 JWKS 옵션이 숨겨집니다. 사용자 지정 검색 URL은 공개 HTTPS URL이어야 하며 자격 증명, 사용자 지정 포트, 쿼리 또는 프래그먼트를 포함할 수 없습니다.

대시보드에 OIDC 검색에 사용자 지정 URL 사용 옵션이 표시되지 않으면 표준 OIDC 검색을 사용하거나 토큰 검증에 업로드한 JWKS 사용 옵션을 활성화하세요. ID 공급자가 게시한 공개 JWKS를 사용하고, 공급자가 서명 키를 교체할 때 JWKS도 업데이트하세요.

토큰 발급자와 검색 호스트가 다르면 OIDC 발급자 URL 값은 토큰의 iss 클레임으로 설정하고, 사용자 지정 OIDC 검색 URL 값은 공급자의 검색 문서를 게시하는 호스트로 설정하세요. OpenAI는 이 경우에도 설정된 발급자를 기준으로 토큰을 검증합니다. 사용자 지정 URL은 검색 메타데이터와 공개 서명 키를 가져올 위치만 결정합니다.

CEL로 토큰 클레임 변환

속성 변환에는 Common Expression Language(CEL)를 사용합니다. OpenAI는 langdef.md에 정의된 표준 CEL 연산자를 지원하며 워크로드 ID 페더레이션 전용 함수를 추가로 제공하지 않습니다. 각 표현식은 루트 객체 하나를 입력으로 받습니다.

• assertion: 검증된 JWT 클레임 집합입니다.

대시보드는 openai. 접두사를 자동으로 붙입니다. 접미사에는 subject와 같은 값을, 표현식에는 assertion.sub와 같은 값을 입력하세요. 이 예에서 API는 도출된 속성을 openai.subject로 저장합니다.

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

CEL 언어 사양에 정의된 구문을 사용하세요. 예를 들어 assertion.sub 또는 assertion.repository와 같은 표현식으로 클레임 값을 읽을 수 있습니다. 지원되지 않는 구문이나 함수를 사용하면 매핑을 결정할 수 없습니다.

12345678910[
  {
    "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는 워크로드 ID 공급자에 설정된 키 소스를 사용해 OIDC 주체 토큰을 검증합니다.

• OIDC 검색: OpenAI는 발급자의 /.well-known/openid-configuration을 가져온 다음, 여기서 확인한 jwks_uri에서 키를 가져옵니다. OpenAI는 검색 문서와 원격 JWKS 데이터를 600초 동안 캐시합니다.
• 사용자 지정 OIDC 검색: OpenAI는 설정된 사용자 지정 검색 기본 URL에서 /.well-known/openid-configuration을 가져온 다음, 여기서 확인한 jwks_uri에서 키를 가져옵니다. 이 경우에도 토큰의 iss 클레임은 OIDC 발급자 URL과 일치해야 합니다.
• 키를 찾지 못한 경우: 캐시된 JWKS에서 토큰의 kid를 찾지 못하면 OpenAI는 토큰을 거부하기 전에 JWKS를 새로 가져와 키를 다시 조회합니다.
• 업로드한 JWKS: 토큰 검증에 업로드한 JWKS 사용 옵션을 활성화하면 OpenAI는 공급자에 저장된 JWKS를 사용합니다. OIDC 검색을 수행하거나 원격 JWKS를 가져오지 않습니다. 공급자 업데이트가 토큰 교환에 반영되면 이후 교환부터 저장된 JWKS를 사용합니다.
• 키 집합: JWKS 하나에 여러 공개 키를 포함할 수 있습니다. 각 키의 kid는 비어 있지 않고 고유해야 합니다.

서명 키를 교체하는 동안에는 발급자의 JWKS에 기존 공개 키와 새 공개 키를 함께 게시하세요. 그러면 기존 키로 서명한 토큰을 계속 사용할 수 있고 OpenAI가 새 키로 서명한 토큰도 허용합니다. 업로드한 JWKS를 사용하는 경우 새 kid로 토큰을 발급하기 전에 공급자를 업데이트하세요. OpenAI는 설정된 JWKS에 없는 키로 서명한 토큰을 거부합니다.

서비스 계정 매핑 설정

서비스 계정 매핑은 어떤 외부 ID로 OpenAI 서비스 계정의 액세스 토큰을 발급받을 수 있는지 정의합니다.

X.509 공급자의 매핑 키에는 변환을 통해 도출된 openai.* 속성을 사용합니다. 가급적 openai.subject 값이 정확히 일치하도록 매핑하세요. sub, aud, iss와 같은 원본 JWT 클레임은 OIDC 공급자에만 적용됩니다.

매핑 설정 항목은 다음과 같습니다.

속성 값은 JSON 스칼라 값이어야 합니다. 문자열 값에는 repo:example/*처럼 비어 있지 않은 접두사 뒤에 와일드카드 하나를 붙일 수 있습니다. 와일드카드를 단독으로 사용하거나 값 중간에 넣는 방식은 지원되지 않습니다.

사용할 수 있는 와일드카드 값의 예는 다음과 같습니다.

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

다음 와일드카드 값은 지원되지 않습니다.

• *
• repo:*:prod
• repo/*/main

대시보드에서는 매핑의 액세스 제한을 권한 항목에 표시합니다. 토큰 교환 응답에서는 같은 제한을 scope 속성에 OAuth 범위로 표시합니다. 매핑에는 관리 API 범위를 포함할 수 없으며, 이후 API 호출에도 일반적인 권한 검사가 적용됩니다.

매핑 결정 예제

OpenAI는 외부 ID를 검증한 다음 적용할 매핑을 결정합니다. 요청에 지정된 identity_provider_id와 service_account_id에 해당하는 매핑을 조회하고 비활성화된 매핑은 건너뜁니다. 각 매핑에 필요한 속성만 평가하며, 설정된 모든 속성과 일치하는 활성 매핑이 정확히 하나일 때만 토큰을 발급합니다.

GitHub Actions 토큰에 다음 클레임이 있다고 가정해 보겠습니다.

1234567{
  "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"
}

공급자는 다음과 같이 속성을 도출할 수 있습니다.

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

그러면 서비스 계정 매핑에서 원본 속성과 파생 속성이 모두 일치하도록 요구할 수 있습니다.

세 값이 모두 일치해야 합니다. sub 값은 끝에 와일드카드가 있으므로 repo:my-org/my-repo:로 시작하는 모든 값과 일치합니다. openai.repository_ref 키의 값은 속성 변환으로 결정하며, 이름이 같은 원본 토큰 클레임은 사용하지 않습니다.

교환 요청에 일치하는 활성 매핑이 둘 이상이면 OpenAI는 요청을 거부합니다. OpenAI는 각 (provider, service account) 쌍에 대해 매핑이 하나만 일치해야 한다는 조건을 적용하며 서로 다른 매핑의 권한을 합치지 않습니다.

워크로드 연결

ID 공급자 가이드의 SDK 예제를 사용하거나 토큰 교환 엔드포인트를 직접 호출하세요. 요청 및 응답 필드, 권한 부여 방식, 현재 제한 사항은 워크로드 ID 토큰 교환 레퍼런스를 참고하세요.

액세스 토큰 갱신

토큰 교환을 직접 관리하는 경우 토큰 서비스에서 애플리케이션으로 자격 증명을 전달할 때 access_token과 expires_at을 함께 전달하세요. expires_at 필드는 절대 만료 시각(UTC)을 초 단위 Unix 타임스탬프로 나타냅니다. 시스템 간 시계 차이와 요청 지연 시간을 고려해 만료 전에 갱신하도록 일정을 설정하세요.

expires_in 필드는 토큰 발급 시점부터 만료까지의 시간을 초 단위로 나타냅니다. 예를 들어 12:00 UTC에 expires_in: 3600으로 발급한 토큰은 다른 서비스가 12:05 UTC에 받더라도 13:00 UTC에 만료됩니다. 전송과 처리에 걸리는 시간만큼 토큰의 유효 기간이 늘어나지는 않습니다. 자세한 내용은 응답 필드를 참고하세요.

토큰 교환 시 갱신 토큰은 반환되지 않습니다. 액세스 토큰을 갱신하려면 유효한 외부 ID 토큰이나 클라이언트 인증서로 교환을 다시 요청하세요.

Codex에서 워크로드 ID 사용

관리형 ChatGPT 워크스페이스에서 신뢰할 수 있는 Codex 자동화를 실행하는 경우 이 절차를 따르세요. Codex는 워크로드를 API 플랫폼 서비스 계정 대신 ChatGPT 사용자 또는 서비스 계정에 매핑합니다.

페더레이션 규칙 레퍼런스에서는 규칙 하나로 여러 외부 주체를 허용하면서 하나의 ChatGPT 주체에 매핑하는 방법을 설명합니다.

연결 문제 해결

OpenAI가 ID 토큰을 거부하는 경우

토큰을 로컬에서 디코딩한 다음 iss, aud, sub, exp, iat 및 공급자별 클레임을 공급자 설정과 비교하세요. 프로덕션 토큰을 타사 JWT 도구에 붙여넣지 마세요.

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

OpenAI API 매핑이 일치하지 않는 경우

요청에 의도한 ID 공급자 ID와 서비스 계정 ID가 지정되어 있는지, 매핑이 활성 상태인지, 일치하는 매핑이 정확히 하나인지 확인하세요. 오류 유형별 자세한 내용은 토큰 교환 오류 레퍼런스를 참고하세요.

Codex에서 설정이 불완전하다고 표시하는 경우

Codex 프로세스에 필수 워크로드 ID 환경 변수 두 개가 모두 설정되어 있고 OPENAI_IDENTITY_TOKEN_FILE 값이 현재 유효한 토큰 파일의 절대 경로인지 확인하세요. 파일과 상위 디렉터리의 권한도 확인하세요.

Codex가 다른 자격 증명을 사용하는 경우

필수 워크로드 ID 환경 변수 두 개를 모두 Codex 프로세스에 로드하세요. 둘 중 하나만 있어도 Codex는 API 키, 액세스 토큰, 저장된 로그인 정보보다 워크로드 ID 페더레이션(WIF)을 우선 선택합니다. 다운로드한 설정을 로드한 상태로 새 프로세스를 시작한 다음 codex login status를 다시 실행하세요.

보안 권장 사항

• 애플리케이션 또는 워크로드마다 전용 주체를 사용하세요.
• 프로덕션 환경과 비프로덕션 환경을 분리하세요.
• 광범위한 패턴보다 클레임 값이 정확히 일치하는 조건을 우선 사용하세요.
• 워크로드에 필요한 권한만 부여하세요.
• 액세스 토큰의 유효 기간을 짧게 설정하세요.
• 공급자, 매핑, 규칙을 검토하고 사용하지 않는 항목을 제거하세요.
• 토큰 교환 오류와 예상치 못한 액세스 패턴을 검토하세요.

관련 문서

• Codex 페더레이션 규칙 레퍼런스
• 워크로드 ID 토큰 교환 레퍼런스
• Codex 인증
• Codex 환경 변수
• Codex 비대화형 모드