Codex federation rule reference

Codex federation rule reference

페더레이션 규칙은 어떤 검증된 워크로드 아이덴티티가 하나의 ChatGPT 사용자 또는 서비스 계정으로 활동할 수 있는지 결정해요. OpenAI는 Codex 프로세스가 이름을 지정한 규칙만 평가해요. 일치하는 규칙을 찾기 위해 모든 규칙을 검색하지 않아요.

출처: 문서

본문

각 규칙은 하나의 대상 주체를 가지며 하나 또는 여러 업스트림 아이덴티티를 수락할 수 있어요. 하나의 규칙에서 주체 집합을 수락하려면 뒤따르는 접두사 주체 또는 CEL 조건을 사용하세요. 같은 주체에 대해 둘 이상의 규칙을 만들 수도 있어요.

규칙 모델

부분 용도
Provider OpenAI가 신뢰하는 발행자와 서명 키를 정의해요.
Workspace 결과 액세스를 하나의 관리형 ChatGPT 워크스페이스로 제한해요.
Principal 그 워크스페이스에서 기존 사용자 또는 서비스 계정 하나를 선택해요.
Identity checks 어떤 검증된 아이덴티티 토큰이 규칙을 사용할 수 있는지 제한해요.
Scopes 선택적으로 기존 Codex OAuth 스코프를 좁혀요.
Access token lifetime OpenAI 액세스 토큰을 60~3,600초로 제한해요.

주체와 그 워크스페이스 멤버십은 교환 전에 존재해야 해요. 규칙은 워크로드가 연결될 때 사용자, 서비스 계정 또는 멤버십을 만들지 않아요.

아이덴티티 검사가 결합되는 방식

규칙은 다음 검사를 사용할 수 있어요.

검사 동작 용도
Subject 정확한 sub 값 또는 하나의 뒤따르는 * 접두사. 하나의 워크로드 아이덴티티 또는 통제된 주체 네임스페이스.
Accepted audiences 1~32개의 audience 문자열. 토큰은 최소 하나를 포함해야 해요. OpenAI에 특별히 만들어진 토큰.
Exact claims 최대 32개의 정확한 최상위 스칼라 클레임 값. 안정적인 문자열, 숫자, true/false 값 또는 null.
CEL condition assertion이라는 이름의 검증된 클레임 맵에 대한 부울 표현식. 목록, 중첩 클레임 또는 허용 값 집합.

최소 하나의 subject, exact-claim 또는 CEL 검사를 설정하세요. 수락된 audience만으로는 워크로드를 식별하지 못해요. 둘 이상의 검사 유형을 구성하면 각각 통과해야 해요.

제공자 검증이 먼저 일어나요. 규칙은 제공자의 발행자, 서명, 만료, assertion 수명, 재생 또는 제공자 수준 CEL 검사를 재정의할 수 없어요.

주체 일치

하나의 안정적인 sub가 워크로드를 식별할 때마다 정확한 주체를 사용하세요.

repo:example-company/payments:environment:production

하나의 뒤따르는 *는 접두사 일치를 수행해요.

system:serviceaccount:production:codex-*

와일드카드는 마지막 문자여야 하고 비어 있지 않은 접두사 뒤에 와야 해요. OpenAI는 *, repo:*:production 또는 repo/*/main을 수락하지 않아요.

더 안정적인 클레임이 특권 워크로드를 분리할 수 있다면 넓은 접두사를 사용하지 마세요. 예를 들어 GitHub 규칙은 한 조직이 소유한 모든 레포지토리보다는 레포지토리, 워크플로 파일, ref 또는 보호된 환경을 일치시켜야 해요.

정확한 클레임

정확한 클레임은 유형을 변환하지 않고 최상위 JWT 클레임을 비교해요. 문자열은 같은 문자열과만 일치하고, 부울은 같은 부울과만 일치하며, 숫자는 같은 숫자 값과 일치해요. 목록과 객체는 정확한 값으로 지원되지 않아요.

예를 들어:

{
  "repository": "example-company/payments",
  "ref": "refs/heads/main",
  "environment": "production"
}

sub를 exact-claims 맵에 포함하지 마세요. subject 필드 또는 CEL을 사용하세요. 중첩 제공자 클레임과 목록 멤버십에는 CEL을 사용하세요.

CEL 조건

CEL 조건은 완전한 검증된 JWT 클레임 맵을 assertion으로 받고 true 또는 false를 반환해야 해요. OpenAI는 규칙 평가를 예측 가능하게 유지하기 위해 제한된 CEL 하위 집합을 지원해요.

하나의 규칙에서 정확한 주체 집합을 허용하려면:

assertion.sub in [
  "repo:example-company/payments:environment:production",
  "repo:example-company/billing:environment:production"
]

레포지토리와 두 ref 중 하나를 요구하려면:

assertion.repository == "example-company/payments" &&
assertion.ref in ["refs/heads/main", "refs/heads/release"]

중첩 또는 선택적 클레임을 읽으려면:

has(assertion.environment) &&
assertion.environment == "production"

지원되는 헬퍼는 has, size, contains, startsWith, endsWith를 포함해요. 정규식 일치, all 또는 exists 같은 컬렉션 반복 매크로, 임의 함수, assertion 이외의 식별자는 지원되지 않아요. 표현식을 짧게 유지하고 같은 정책을 표현할 수 있을 때 정확한 검사를 선호하세요.

없는 클레임, 지원되지 않는 연산, 비부울 결과 또는 평가 오류는 교환을 거부해요.

Audience 일치

제공자는 하나의 예상 audience를 설정할 수 있어요. 규칙은 대신 하나 이상의 수락된 audience를 설정할 수 있어요. 규칙에 audience 목록이 있으면 토큰의 aud 클레임에 있는 값 중 최소 하나가 그 목록에 나타나야 해요.

제공자가 지원하면 OpenAI 전용 audience를 사용하세요. SPIFFE JWT-SVID 규칙은 수락된 audience를 설정해야 해요. 제공자가 제공자 수준 audience를 정의하지 않으면 OIDC 규칙도 하나를 설정해야 해요.

Audience 일치와 아이덴티티 검사는 누적돼요. 일치하는 audience는 통과하지 못한 subject, exact-claim 또는 CEL 검사를 보상하지 않아요.

주체 카디널리티

하나의 규칙은 정확히 하나의 주체에 매핑돼요.

many accepted external identities -> one federation rule -> one OpenAI principal

이것은 워크로드 복제본, 작업 또는 승인된 주체가 같은 사용자 또는 서비스 계정으로 활동하는 것을 지원해요. 하나의 규칙이 클레임에 따라 다른 주체를 선택하게 하지는 않아요. 워크로드가 다른 주체, 워크스페이스, 스코프 또는 토큰 수명이 필요하면 별도의 규칙을 만드세요.

둘 이상의 규칙이 같은 주체를 대상으로 할 수 있어요. 각 워크로드에 독립적인 수명 주기 제어나 더 명확한 감사 귀속이 필요하면 별도의 규칙을 사용하세요.

스코프와 권한 부여

규칙은 발행된 액세스 토큰의 OAuth 스코프를 좁힐 수 있어요. 대상 주체 또는 워크스페이스가 이미 갖지 못한 권한을 부여할 수는 없어요.

스코프를 생략하면 OpenAI는 표준 Codex 스코프 openid, profile, email 및 Codex 로컬 액세스를 사용해요. Admin API를 통해 스코프를 설정하면 chatgpt.workspace.feature.allow-codex-local-access.access를 포함하고 지원되는 네 값만 사용하세요.

먼저 최소 권한 주체와 워크스페이스 권한을 선택하세요. 규칙 스코프를 주요 권한 부여 경계가 아니라 두 번째 제한으로 취급하세요.

토큰 수명

OpenAI 액세스 토큰 수명을 60~3,600초로 설정하세요. OpenAI는 다음 중 더 짧은 것을 사용해요.

  • 업스트림 아이덴티티 토큰의 남은 수명.
  • 규칙의 구성된 액세스 토큰 수명.

더 짧은 수명은 발행된 토큰이 정책 편집을 얼마나 오래 초과할 수 있는지 줄이지만 교환 빈도를 늘려요. 워크로드가 다른 균형이 필요하지 않으면 10분 수명이 실용적인 시작점이에요.

재생 보호

제공자 수준 재생 보호는 JWT jti 클레임을 사용해요. 관리자가 Prevent assertion replay를 켜고 토큰에 비어 있지 않은 jti가 있으면 OpenAI는 그 jti를 assertion이 만료될 때까지 그 제공자에 대해 한 번만 수락해요.

워크로드는 결과가 알려지지 않은 교환 후의 재시도를 포함해 매 교환 전에 새 jti가 있는 새 assertion을 받아야 해요. jti가 없는 assertion은 사용 가능하지만 재생 보호를 받지 못해요. 빈, null 또는 비문자열 jti 값은 검증을 통과하지 못해요.

변경, 비활성화, 보관

아이덴티티 검사, 스코프 또는 토큰 수명에 대한 일반적인 편집은 새 교환에 적용돼요. 편집 전에 발행된 액세스 토큰은 기존 TTL이 끝날 때까지 유효할 수 있어요.

규칙이나 제공자를 비활성화하면 새 교환이 차단되고 이를 통해 발행된 OpenAI 액세스 토큰이 취소돼요. 보관(archiving)도 같게 하며 되돌릴 수 없어요. 발행자나 JWKS 설정 같은 제공자 신뢰를 변경하면 새 신뢰 구성이 활성화되기 전에 발행된 토큰이 취소돼요.

긴급 중지나 임시 중단에는 비활성화를 사용하세요. 더 이상 필요하지 않을 때만 리소스를 보관하세요.

한계

리소스 한계
조직당 비보관 제공자 50
제공자당 비보관 규칙 50
규칙당 정확한 클레임 32
규칙당 수락된 audience 32개의 고유 값
주체 길이 4,096바이트
Exact-claim 맵 또는 CEL 조건 16KiB
액세스 토큰 수명 60~3,600초

독립적인 발행자, 키, 재생 또는 수명 주기 제어가 필요한 신뢰 경계에 대해 별도의 제공자를 만드세요. 신뢰를 공유하지만 다른 주체나 액세스 정책이 필요한 워크로드에 대해 한 제공자 아래 별도의 규칙을 만드세요.

더 알아보기 (Learn more)