Federasi identitas beban kerja

Federasi identitas beban kerja memungkinkan otomatisasi tepercaya menggunakan Codex tanpa menyimpan token akses pribadi atau kredensial OpenAI berumur panjang lainnya. Beban kerja Anda menyajikan token identitas berumur pendek dari penyedia yang sudah Anda operasikan. OpenAI memverifikasi token tersebut dan mengembalikan token akses berumur pendek untuk pengguna atau akun layanan di workspace ChatGPT terkelola Anda.

Gunakan identitas beban kerja untuk proses Codex tanpa pengawasan di platform cloud, Kubernetes, sistem CI, dan lingkungan lain yang dapat menerbitkan token OIDC atau SPIFFE JWT-SVID. Untuk model kepercayaan bersama dan alur OpenAI API yang terpisah, lihat ringkasan identitas beban kerja.

Sebelum memulai

Anda memerlukan:

• Izin untuk mengelola identitas beban kerja di OpenAI Admin Portal.
• Workspace ChatGPT terkelola.
• Pengguna atau akun layanan ChatGPT yang merupakan anggota aktif workspace tersebut, atau izin untuk membuatnya selama penyiapan.
• Token OIDC atau SPIFFE JWT-SVID yang penerbit, audiens, dan klaim pengenalannya Anda ketahui.
• Runtime yang dapat menjaga token tersebut tetap mutakhir dalam file terlindungi di jalur absolut.
• Codex 0.148.0 atau yang lebih baru.
• Kebijakan autentikasi Codex efektif yang mengizinkan autentikasi ChatGPT dan workspace yang dipilih oleh aturan federasi. Lihat Menerapkan metode login atau workspace.

OpenAI tidak membuat prinsipal atau keanggotaan workspace selama pertukaran token. Administrator memilih atau membuat prinsipal sebelum beban kerja terhubung. Membuat pengguna manusia memakai satu lisensi workspace dan mengikuti aturan keanggotaan untuk workspace tersebut.

Di Windows native, gunakan Windows sandbox elevated. Mode Windows sandbox lainnya tidak dapat melindungi file token identitas dari perintah yang dikendalikan model.

Mendapatkan token identitas

Runtime beban kerja Anda memperoleh dan memperbarui token identitas hulu. Codex tidak memanggil layanan metadata cloud atau pustaka klien penyedia identitas untuk Anda.

Ikuti panduan untuk penyedia Anda guna mengonfigurasi penerbitan token dan memeriksa token contoh:

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

Dekode token contoh secara lokal dan catat iss, aud, sub, serta setiap klaim lain yang akan Anda percayai. Pendekodean tidak memverifikasi tanda tangan. Jangan tempelkan token produksi ke situs web atau menuliskannya ke log.

Menghubungkan beban kerja

Administrator membuat penyedia dan aturan federasi sebelum memulai Codex.

1. Buka Workload identity di OpenAI Admin Portal, lalu pilih Connect workload.
2. Gunakan kembali penyedia yang dikonfigurasi untuk Codex, atau buat penyedia baru. Preset penyedia mengisi pengaturan umum untuk GitHub Actions, Microsoft Entra ID, Google Cloud, AWS, Kubernetes, SPIFFE, dan penyedia OIDC khusus.
3. Pilih Codex dan workspace terkelola yang boleh digunakan beban kerja.
4. Tambahkan kondisi tersempit yang mengidentifikasi beban kerja. Cocokkan subjek, klaim persis, kondisi CEL, atau kombinasinya. Tambahkan audiens yang diterima untuk membatasi token yang diterima aturan. Setiap pencocok yang dikonfigurasi harus terpenuhi.
5. Petakan aturan ke satu pengguna atau akun layanan ChatGPT yang sudah ada, atau buat satu selama penyiapan.
6. Tinjau penyedia, kondisi, workspace, prinsipal, cakupan, dan masa berlaku token akses. Pilih Connect workload, lalu Download config.

File yang diunduh berisi ID aturan federasi yang bukan rahasia dan jalur tempat Codex akan membaca token identitas. File tersebut tidak berisi kredensial.

Untuk mengotomatiskan penyiapan, gunakan Admin API identitas beban kerja. Untuk perilaku pencocok dan contoh, lihat Referensi aturan federasi.

Mengonfigurasi proses Codex

Proses yang memulai Codex memerlukan dua variabel identitas beban kerja berikut:

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

OPENAI_FEDERATION_RULE_ID bukan rahasia. File token adalah rahasia. Gunakan jalur absolut dalam direktori khusus, seperti /var/run/secrets/openai.com, yang dimiliki oleh akun beban kerja dengan mode 0700. Hanya proses host tepercaya yang boleh menulis di sana. Tempatkan direktori di luar repositori dan jalur lain yang tersedia bagi alat Codex. Jauhkan kredensial dari log, riwayat shell, dan artefak build.

Menambahkan atribusi audit

Saat instans runtime berbagi aturan federasi, Anda dapat mengidentifikasi setiap instans dalam peristiwa audit penerbitan token. Atur variabel opsional OPENAI_WORKLOAD_IDENTITY_CONTEXT ke objek JSON yang dikodekan sebagai string:

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

Objek tersebut memerlukan instance_id. Objek juga dapat berisi display_name dan hingga delapan label. Objek yang dikodekan dapat berukuran hingga 1.024 byte. instance_id dan display_name dapat berisi hingga 128 karakter. Kunci label dapat berisi hingga 64 karakter, dan nilai label dapat berisi hingga 256 karakter.

Pengenal harus diawali huruf atau angka ASCII. Selanjutnya, nilainya dapat memuat huruf, angka, ., _, :, /, @, dan -. Kunci label mendukung huruf, angka, ., _, dan -.

OpenAI memperlakukan konteks ini sebagai atribusi audit yang dilaporkan klien, bukan sebagai identitas beban kerja yang terverifikasi. Konteks ini tidak memengaruhi autentikasi, otorisasi, pencocokan aturan, cakupan, batas laju, pencabutan, gerbang fitur, atau metrik. Jangan masukkan kredensial, rahasia, data pribadi, prompt, output model, atau Customer Content lainnya ke dalamnya.

Untuk konteks yang valid, OpenAI memperoleh ID atribusi stabil yang dibatasi pada tenant, penyedia, aturan federasi, dan instance_id. Untuk atribusi, token akses berisi ID tersebut tetapi tidak berisi konteks. Peristiwa audit penerbitan token yang berhasil berisi ID dan konteks yang dinormalisasi. Konteks yang melampaui batas atau melanggar skema ini menyebabkan pertukaran gagal dengan invalid_grant.

Codex membaca konteks saat proses dimulai dan tidak meneruskannya, ID aturan, atau jalur file token ke shell, hook, atau server MCP yang dikendalikan model. Mulai ulang Codex setelah mengubah konteks.

Melindungi dan merotasi file token

Untuk deployment Linux terkelola, macOS, dan WSL, tambahkan seluruh direktori token ke permissions.filesystem.deny_read dalam persyaratan terkelola:

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

Tindakan ini memblokir perintah yang dikendalikan model agar tidak membaca token aktif atau pengganti sementara, sementara proses host Codex tetap dapat menggunakan token untuk pertukaran. Untuk volume token terproyeksi, tolak akses ke seluruh titik pemasangan token dan setiap jalur target pendukung atau yang telah diresolusikan di luarnya. Mode file dan pembersihan variabel lingkungan saja tidak melindungi kredensial dari proses lain yang berjalan sebagai pengguna yang sama. Di Windows native, gunakan sandbox elevated yang dijelaskan di atas.

Untuk sumber token yang tidak memproyeksikan file, minta proses host tepercaya menulis setiap pengganti di dalam direktori terlindungi tersebut dan mengganti namanya ke lokasi tujuan. Operasi ganti nama atomik mencegah Codex membaca token yang belum lengkap. Sebagai contoh, sesuaikan skrip pembaruan milik host ini dengan perintah token penyedia Anda. Siapkan direktori sebelum menjalankan skrip:

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"

Jalankan proses pembaruan di luar shell atau alat apa pun yang dapat dikendalikan Codex. Pertahankan penolakan akses baca selama pembaruan dan pembersihan. Meskipun penghentian paksa meninggalkan file sementara, file tersebut harus tetap berada di dalam direktori yang aksesnya ditolak. Jangan tempatkan pengaturan identitas beban kerja di config.toml.

Memverifikasi koneksi

Muat lingkungan yang diunduh dan periksa metode autentikasi yang dipilih:

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

Di PowerShell:

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

Pemeriksaan yang berhasil menampilkan Logged in using workload identity. Ini mengonfirmasi bahwa Codex menukar token melalui aturan federasi yang dikonfigurasi. Perintah tersebut tidak menampilkan workspace, prinsipal, atau aturan yang diresolusikan. Konfirmasikan nilai tersebut di Admin Portal sebelum Anda memulai beban kerja. Jika Codex melaporkan metode autentikasi lain, kedua variabel WIF wajib tidak diteruskan ke proses.

Jika penyedia menggunakan Prevent assertion replay dan pernyataan memiliki klaim jti, pemeriksaan ini menggunakan jti tersebut. Tulis pernyataan yang baru diterbitkan dengan jti baru sebelum memulai proses Codex lain.

Jalankan permintaan kecil dari lingkungan yang sama:

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

Codex menukar token hulu dan menyimpan token akses OpenAI dalam memori. Codex tidak menulis kredensial tersebut ke auth.json, keyring sistem, atau config.toml.

Menjaga token tetap mutakhir

Perbarui file token identitas sebelum token hulu kedaluwarsa. Codex membaca ulang file saat memerlukan token akses OpenAI lain. Token OpenAI kedaluwarsa pada waktu yang lebih awal antara waktu kedaluwarsa token hulu dan masa berlaku aturan federasi, dan tidak pernah berlaku lebih dari satu jam.

Saat administrator mengaktifkan perlindungan pemutaran ulang, setiap JWT hulu harus memiliki jti unik. Tulis pernyataan yang baru diterbitkan dengan jti baru sebelum setiap pertukaran, termasuk pembaruan dalam proses yang berjalan lama. Pernyataan tanpa jti tidak mendapatkan perlindungan pemutaran ulang.

Codex berbagi satu sesi pertukaran dalam memori di dalam setiap proses host. Permintaan bersamaan dalam proses tersebut menggunakan kembali token akses OpenAI yang valid dan berbagi satu proses pembaruan saat token kedaluwarsa. Proses terpisah melakukan pertukaran terpisah, sehingga memerlukan pernyataan yang diizinkan penyedia untuk digunakan.

Prioritas kredensial

Kedua variabel identitas beban kerja wajib diprioritaskan di atas setiap sumber kredensial lain:

1. Jika OPENAI_FEDERATION_RULE_ID atau OPENAI_IDENTITY_TOKEN_FILE tersedia, Codex memilih identitas beban kerja.
2. Jika hanya satu variabel wajib yang tersedia, Codex mengembalikan kesalahan. Codex tidak beralih ke API key, token akses, atau login tersimpan.
3. OPENAI_WORKLOAD_IDENTITY_CONTEXT saja tidak memilih identitas beban kerja.
4. Jika kedua variabel WIF wajib tidak tersedia, Codex menerapkan aturan kredensial normal untuk permukaan tersebut. Untuk permukaan yang mengizinkan autentikasi API key, CODEX_API_KEY diprioritaskan pada codex exec, codex review, TypeScript SDK, dan codex exec-server --remote. Permukaan lain dapat menggunakan CODEX_ACCESS_TOKEN atau login tersimpan.

Opsi SDK apiKey menjadi CODEX_API_KEY, tetapi WIF tetap diprioritaskan jika salah satu variabel WIF wajib tersedia. Hilangkan opsi tersebut saat menggunakan WIF agar beban kerja tidak membawa kredensial berumur panjang yang tidak digunakan.

Untuk memindahkan beban kerja yang sudah ada tanpa waktu henti, konfigurasikan WIF selagi kredensialnya saat ini masih tersedia. Mulai proses baru dengan kedua variabel WIF wajib; WIF diprioritaskan meskipun kredensial lama masih tersedia. Setelah beban kerja berhasil menggunakan WIF, hapus kredensial lama dari runtime dan penyimpanan rahasianya, lalu cabut kredensial tersebut. Sebelum pencabutan, Anda dapat melakukan rollback dengan menghapus kedua variabel WIF wajib dan memulai proses baru.

Permukaan Codex yang didukung

Konfigurasikan identitas beban kerja pada mesin yang memiliki proses Codex.

Klien app-server dan exec-server jarak jauh tidak pernah mengirim token identitas hulu melalui protokolnya.

Mengubah atau menghapus akses

Perubahan pada subjek, audiens, klaim, kondisi CEL, cakupan, atau masa berlaku token suatu aturan berlaku untuk pertukaran baru. Token yang diterbitkan sebelum perubahan dapat tetap valid hingga masa berlakunya berakhir.

Nonaktifkan penyedia atau aturan untuk segera menghentikan akses. Penonaktifan memblokir pertukaran baru dan mencabut token akses OpenAI yang telah diterbitkan melalui sumber daya tersebut. Pengarsipan memiliki efek akses yang sama dan tidak dapat dibatalkan. Mengubah kepercayaan penyedia juga mencabut token yang telah diterbitkan sebelum kepercayaan baru mulai berlaku.

Mengaudit perubahan

Pembuatan, pembaruan, dan pengarsipan penyedia serta aturan federasi menghasilkan peristiwa audit. Gunakan Compliance API dan panduan peristiwa audit untuk mengekspor peristiwa yang didukung workspace Anda. Korelasikan peristiwa tersebut dengan log penerbitan penyedia identitas Anda, dan jangan catat pernyataan hulu atau token akses OpenAI di kedua sistem.

Saat proses menyediakan OPENAI_WORKLOAD_IDENTITY_CONTEXT, peristiwa audit penerbitan token yang berhasil juga berisi ID atribusi stabil dan konteks yang dinormalisasi seperti dijelaskan di atas.

Pemecahan masalah

Untuk verifikasi penyedia, batas, dan detail CEL, lihat referensi aturan federasi.