Codex 페더레이션 규칙 레퍼런스

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

각 규칙은 하나의 보안 주체를 대상으로 하며, 하나 이상의 업스트림 아이덴티티를 허용할 수 있습니다. 하나의 규칙에서 여러 토큰 주체를 허용하려면 주체 값의 끝에 와일드카드를 붙여 접두사를 지정하거나 CEL 조건을 사용하세요. 같은 보안 주체를 대상으로 규칙을 여러 개 만들 수도 있습니다.

규칙 구성

토큰을 교환하려면 보안 주체가 이미 존재하고 해당 워크스페이스의 구성원이어야 합니다. 워크로드가 연결될 때 규칙이 사용자나 서비스 계정을 만들거나 워크스페이스에 구성원을 추가하지는 않습니다.

아이덴티티 검사 조합

규칙에는 다음 검사를 사용할 수 있습니다.

토큰 주체, 클레임 값 일치, CEL 조건 중 하나 이상을 설정하세요. 허용 대상만으로는 워크로드를 식별할 수 없습니다. 여러 유형의 검사를 설정하면 각 검사를 모두 통과해야 합니다.

공급자 검증이 먼저 이루어집니다. 규칙으로는 공급자가 수행하는 발급자, 서명, 만료, 어설션 수명, 재사용 여부 검사나 공급자 수준의 CEL 검사를 재정의할 수 없습니다.

토큰 주체 일치

변하지 않는 하나의 sub 값으로 워크로드를 식별할 수 있다면 그 값을 그대로 지정하세요.

repo:example-company/payments:environment:production

끝에 *를 하나 붙이면 접두사가 일치하는지 검사합니다.

system:serviceaccount:production:codex-*

와일드카드는 비어 있지 않은 접두사 뒤에 와야 하며 반드시 마지막 문자여야 합니다. OpenAI는 *, repo:*:production, repo/*/main을 허용하지 않습니다.

더 안정적인 클레임으로 권한이 높은 워크로드를 구분할 수 있다면 범위가 넓은 접두사를 사용하지 마세요. 예를 들어 GitHub 규칙은 한 조직이 소유한 모든 리포지터리를 허용하기보다 특정 리포지터리, 워크플로우 파일, ref 또는 보호된 환경과 일치하는지 검사해야 합니다.

클레임 값 일치

클레임 값 일치 검사에서는 최상위 JWT 클레임의 타입을 변환하지 않고 값을 비교합니다. 문자열은 동일한 문자열과만, 불리언은 동일한 불리언 값과만 일치하며, 숫자는 수치가 같으면 일치합니다. 목록과 객체는 이 검사의 비교 값으로 지원되지 않습니다.

예를 들어 다음과 같이 지정할 수 있습니다.

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

클레임 값 일치 검사에 사용하는 맵에는 sub를 넣지 마세요. 토큰 주체 필드나 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 이외의 식별자는 지원되지 않습니다. 표현식은 짧게 작성하고, 같은 정책을 표현할 수 있다면 정확한 값 일치 검사를 우선 사용하세요.

클레임이 없거나 지원되지 않는 연산을 사용하거나 결과가 불리언이 아니거나 평가 중 오류가 발생하면 토큰 교환이 거부됩니다.

대상 일치

공급자에는 예상 대상을 하나 설정할 수 있습니다. 그 대신 규칙에서 하나 이상의 허용 대상을 지정할 수도 있습니다. 규칙에 허용 대상 목록이 있으면 토큰의 aud 클레임 값 중 하나 이상이 해당 목록에 있어야 합니다.

공급자가 전용 대상을 지원한다면 OpenAI 전용 대상을 사용하세요. SPIFFE JWT-SVID 규칙에는 허용 대상을 반드시 설정해야 합니다. 공급자 수준에서 대상을 지정하지 않았다면 OIDC 규칙에도 허용 대상을 설정해야 합니다.

대상 일치 검사와 아이덴티티 검사는 모두 적용됩니다. 대상이 일치하더라도 토큰 주체, 클레임 값 일치 또는 CEL 검사에 실패하면 토큰을 교환할 수 없습니다.

규칙과 보안 주체의 대응 관계

하나의 규칙은 정확히 하나의 보안 주체에 매핑됩니다.

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

따라서 워크로드 복제본, 작업 또는 승인된 토큰 주체들이 같은 사용자나 서비스 계정으로 동작할 수 있습니다. 하나의 규칙이 클레임에 따라 서로 다른 보안 주체를 선택할 수는 없습니다. 워크로드마다 다른 보안 주체, 워크스페이스, 스코프 또는 토큰 수명이 필요하다면 규칙을 별도로 만드세요.

여러 규칙이 같은 보안 주체를 대상으로 할 수 있습니다. 워크로드별로 수명 주기를 독립적으로 관리하거나 감사 시 각 워크로드의 활동을 명확하게 구분해야 한다면 규칙을 분리하세요.

스코프와 권한 부여

규칙은 발급되는 액세스 토큰의 OAuth 스코프를 좁힐 수 있습니다. 대상 보안 주체나 워크스페이스에 없는 권한을 부여할 수는 없습니다.

스코프를 생략하면 OpenAI는 표준 Codex 스코프인 openid, profile, email과 Codex 로컬 액세스를 사용합니다. 관리 API로 스코프를 설정할 때는 chatgpt.workspace.feature.allow-codex-local-access.access를 포함하고, 지원되는 이 네 가지 값만 사용하세요.

먼저 필요한 최소 권한만 가진 보안 주체를 선택하고 워크스페이스 권한도 최소한으로 설정하세요. 규칙의 스코프는 이렇게 정한 권한 범위를 한 번 더 제한하는 용도로 사용하세요.

토큰 수명

OpenAI 액세스 토큰의 수명은 60~3,600초로 설정하세요. OpenAI는 다음 두 기간 중 더 짧은 쪽을 적용합니다.

• 업스트림 아이덴티티 토큰의 남은 수명
• 규칙에 설정된 액세스 토큰 수명

수명을 짧게 설정하면 정책 변경 후 기존 토큰이 유효한 기간은 줄어들지만 토큰을 더 자주 교환해야 합니다. 워크로드 특성상 이 두 요소의 균형을 다르게 잡아야 하는 경우가 아니라면 10분으로 시작하는 것이 적절합니다.

재사용 방지

공급자 수준의 재사용 방지 기능은 JWT의 jti 클레임을 사용합니다. 관리자가 어설션 재사용 방지 기능을 켜고 토큰에 비어 있지 않은 jti가 있으면, OpenAI는 어설션이 만료될 때까지 해당 공급자에서 그 jti를 한 번만 허용합니다.

워크로드는 토큰을 교환하기 전에 매번 새로운 jti가 있는 어설션을 새로 받아야 합니다. 이전 교환의 성공 여부를 알 수 없어 재시도하는 경우에도 마찬가지입니다. jti가 없는 어설션은 계속 사용할 수 있지만 재사용 방지는 적용되지 않습니다. jti 값이 비어 있거나 null이거나 문자열이 아니면 검증을 통과하지 못합니다.

변경, 비활성화 및 보관 처리

아이덴티티 검사, 스코프 또는 토큰 수명에 대한 일반적인 변경 사항은 이후의 토큰 교환부터 적용됩니다. 변경 전에 발급된 액세스 토큰은 기존 TTL이 끝날 때까지 유효할 수 있습니다.

규칙이나 공급자를 비활성화하면 새 토큰 교환이 차단되고 해당 규칙이나 공급자를 통해 발급된 OpenAI 액세스 토큰도 폐기됩니다. 보관 처리해도 동일한 효과가 있으며, 보관 처리는 되돌릴 수 없습니다. 발급자나 JWKS 설정 등 공급자의 신뢰 설정을 변경하면 새 설정이 적용되기 전에 이미 발급된 토큰이 폐기됩니다.

긴급하게 중단하거나 잠시 멈춰야 할 때는 비활성화하세요. 리소스가 더 이상 필요하지 않을 때만 보관 처리하세요.

제한 사항

신뢰 경계별로 발급자, 키, 재사용 방지 또는 수명 주기를 독립적으로 관리해야 한다면 공급자를 분리하세요. 신뢰 설정은 같지만 서로 다른 보안 주체나 액세스 정책이 필요한 워크로드에는 같은 공급자 아래에 별도의 규칙을 만드세요.