Федерация удостоверений рабочих нагрузок

Федерация удостоверений рабочих нагрузок позволяет доверенной автоматизации использовать Codex без хранения персонального токена доступа или других долгосрочных учетных данных OpenAI. Рабочая нагрузка предоставляет краткосрочный токен удостоверения от уже используемого вами поставщика. OpenAI проверяет этот токен и возвращает краткосрочный токен доступа для пользователя или сервисной учетной записи в вашей управляемой рабочей области ChatGPT.

Используйте удостоверение рабочей нагрузки для автономных процессов Codex на облачных платформах, в Kubernetes, системах CI и других средах, способных выдавать токены OIDC или SPIFFE JWT-SVID. Общая модель доверия и отдельный процесс OpenAI API описаны в обзоре удостоверений рабочих нагрузок.

Перед началом работы

Вам потребуются:

• Разрешение на управление удостоверениями рабочих нагрузок в OpenAI Admin Portal.
• Управляемая рабочая область ChatGPT.
• Пользователь или сервисная учетная запись ChatGPT, являющиеся активным участником этой рабочей области, либо разрешение создать такую учетную запись во время настройки.
• Токен OIDC или SPIFFE JWT-SVID с известными вам издателем, аудиторией и идентифицирующими утверждениями.
• Среда выполнения, способная поддерживать актуальность этого токена в защищенном файле по абсолютному пути.
• Codex 0.148.0 или более поздней версии.
• Действующая политика аутентификации Codex, разрешающая аутентификацию ChatGPT и рабочую область, выбранную правилом федерации. См. раздел Принудительное применение метода входа или рабочей области.

OpenAI не создает субъект или членство в рабочей области во время обмена токенами. Администратор выбирает или создает субъект до подключения рабочей нагрузки. Создание пользователя-человека занимает место в рабочей области и подчиняется правилам членства этой рабочей области.

В нативной Windows используйте elevated песочницу Windows. Другие режимы песочницы Windows не могут защитить файл токена удостоверения от команд, контролируемых моделью.

Получите токен удостоверения

Среда выполнения рабочей нагрузки получает и обновляет исходный токен удостоверения. Codex не вызывает от вашего имени сервисы облачных метаданных или клиентские библиотеки поставщика удостоверений.

Следуйте руководству для своего поставщика, чтобы настроить выдачу токенов и проверить пример токена:

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

Декодируйте пример токена локально и запишите его iss, aud, sub и любые другие утверждения, которым планируете доверять. Декодирование не проверяет подпись. Не вставляйте производственный токен на веб-сайт и не записывайте его в журналы.

Подключите рабочую нагрузку

До запуска Codex администратор создает поставщика и правило федерации.

1. Откройте раздел Workload identity в OpenAI Admin Portal, затем выберите 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.

Загруженный файл содержит несекретный идентификатор правила федерации и путь, по которому Codex будет читать токен удостоверения. Учетных данных в нем нет.

Для автоматизации настройки используйте Admin API удостоверений рабочих нагрузок. Поведение критериев сопоставления и примеры приведены в справочнике по правилам федерации.

Настройте процесс Codex

Процессу, запускающему Codex, требуются следующие две переменные удостоверения рабочей нагрузки:

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

OPENAI_FEDERATION_RULE_ID не является секретом. Файл токена — является. Используйте абсолютный путь в выделенном каталоге, например /var/run/secrets/openai.com, принадлежащем учетной записи рабочей нагрузки и имеющем режим 0700. Записывать туда должны только доверенные процессы хоста. Разместите каталог вне репозиториев и других путей, доступных инструментам 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 и до восьми меток. Размер закодированного объекта не может превышать 1 024 байта. instance_id и display_name могут содержать до 128 символов. Ключи меток могут содержать до 64 символов, а значения меток — до 256 символов.

Идентификаторы должны начинаться с ASCII-буквы или цифры. Далее значения могут содержать буквы, цифры, ., _, :, /, @ и -. Ключи меток поддерживают буквы, цифры, ., _ и -.

OpenAI рассматривает этот контекст как предоставленную клиентом атрибуцию аудита, а не как проверенное удостоверение рабочей нагрузки. Он не влияет на аутентификацию, авторизацию, сопоставление правил, области действия, ограничения частоты запросов, отзыв доступа, функциональные ограничения или метрики. Не помещайте в него учетные данные, секреты, персональные данные, запросы, результаты модели или другой Пользовательский контент.

Для допустимого контекста OpenAI формирует стабильный идентификатор атрибуции в пределах арендатора, поставщика, правила федерации и instance_id. Для атрибуции токен доступа содержит идентификатор, но не контекст. Событие аудита успешной выдачи токена содержит идентификатор и нормализованный контекст. Если контекст превышает ограничение или нарушает эту схему, обмен завершается ошибкой invalid_grant.

Codex считывает контекст при запуске процесса и не передает его, идентификатор правила или путь к файлу токена в контролируемые моделью оболочки, хуки или серверы MCP. После изменения контекста перезапустите Codex.

Защитите и ротируйте файл токена

Для управляемых развертываний Linux, macOS и WSL добавьте весь каталог токена в permissions.filesystem.deny_read в управляемых требованиях:

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

Это блокирует чтение активного токена или временной замены командами, контролируемыми моделью, при этом процесс хоста Codex по-прежнему может использовать токен для обмена. Для томов с проецируемыми токенами запретите доступ ко всему подключению токена и ко всем вспомогательным или разрешенным целевым путям за его пределами. Одних режимов файлов и удаления переменных среды недостаточно для защиты учетных данных от другого процесса, запущенного от имени того же пользователя. В нативной Windows используйте описанную выше elevated sandbox.

Для источников токенов, не проецирующих файл, доверенный процесс хоста должен записывать каждую замену в защищенный каталог и атомарно переименовывать ее в рабочий файл. Атомарное переименование не позволяет 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. Сохраняйте запрет чтения во время обновления и очистки. Даже если принудительная остановка оставит временный файл, он должен оставаться внутри запрещенного каталога. Не помещайте параметры удостоверения рабочей нагрузки в 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. Запишите новое утверждение с новым jti перед запуском другого процесса Codex.

Выполните небольшой запрос из той же среды:

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

Codex обменивает исходный токен и хранит токен доступа OpenAI в памяти. Он не записывает ни одни из этих учетных данных в auth.json, системное хранилище ключей или config.toml.

Поддерживайте актуальность токена

Обновляйте файл токена удостоверения до истечения срока действия исходного токена. Codex повторно считывает файл, когда ему требуется новый токен доступа OpenAI. Срок действия токена OpenAI истекает при наступлении более раннего из двух событий: истечения срока исходного токена или срока, заданного правилом федерации, и никогда не превышает одного часа.

Если администратор включает защиту от повторного использования, каждый исходный JWT должен иметь уникальное значение jti. Перед каждым обменом, включая обновления в долгоживущем процессе, записывайте новое утверждение с новым jti. Утверждения без jti не защищены от повторного использования.

Codex использует один сеанс обмена в памяти внутри каждого процесса хоста. Параллельные запросы в этом процессе повторно используют действующий токен доступа OpenAI и совместно выполняют одно обновление после истечения его срока. Отдельные процессы выполняют отдельные обмены, поэтому им требуются утверждения, использование которых разрешено поставщиком.

Приоритет учетных данных

Две обязательные переменные удостоверения рабочей нагрузки имеют приоритет над всеми остальными источниками учетных данных:

1. Если присутствует OPENAI_FEDERATION_RULE_ID или OPENAI_IDENTITY_TOKEN_FILE, Codex выбирает удостоверение рабочей нагрузки.
2. Если присутствует только одна обязательная переменная, Codex возвращает ошибку. Он не использует в качестве резерва API key, токен доступа или сохраненный вход.
3. Одного OPENAI_WORKLOAD_IDENTITY_CONTEXT недостаточно для выбора удостоверения рабочей нагрузки.
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.

Удаленные клиенты app-server и exec-server никогда не отправляют исходный токен удостоверения по своим протоколам.

Измените или удалите доступ

Изменения субъектов, аудиторий, утверждений, условия CEL, областей действия или срока действия токена в правиле применяются к новым обменам. Токен, выданный до изменения, может оставаться действительным до окончания своего срока.

Отключите поставщика или правило, чтобы немедленно прекратить доступ. Отключение блокирует новые обмены и отзывает уже выданные через этот ресурс токены доступа OpenAI. Архивирование оказывает такое же воздействие на доступ, и его нельзя отменить. Изменение доверия к поставщику также отзывает выданные токены до вступления нового доверия в силу.

Аудит изменений

Создание, обновление и архивирование поставщика и правила федерации создают события аудита. Используйте Compliance API и рекомендации по событиям аудита, чтобы экспортировать поддерживаемые вашей рабочей областью события. Сопоставляйте их с журналами выдачи вашего поставщика удостоверений и не записывайте исходные утверждения или токены доступа OpenAI ни в одной из систем.

Если процесс предоставляет OPENAI_WORKLOAD_IDENTITY_CONTEXT, события аудита успешной выдачи токенов также содержат стабильный идентификатор атрибуции и нормализованный контекст, описанные выше.

Устранение неполадок

Сведения о проверке поставщика, ограничениях и CEL см. в справочнике по правилам федерации.