Authentication

概要

OpenAI モデルを使うときのサインイン方法は 2 つ。ChatGPT でのサインイン（サブスクリプション利用）と API キーでのサインイン（従量課金）。ChatGPT desktop app / Codex CLI / IDE extension はローカル作業で両方に対応する。Codex cloud は ChatGPT でのサインインが必須。

仕様

サインイン方法の違い

サインイン方法によって、適用される管理者コントロールとデータ取り扱いポリシーが変わる
- ChatGPT でサインイン: ChatGPT ワークスペースの権限、RBAC、ChatGPT Enterprise の保持・residency 設定に従う
- API キー: API 組織の保持・データ共有設定に従う
管理されたワークスペースでは認証はアクセス制御の 1 層にすぎない。誰がサインインできるかはワークスペースのメンバーシップとプロビジョニング、どのサーフェスと機能を使えるかは seat とワークスペースロールが決める。デバイス上でエージェントができることは permission profile が制約する

ChatGPT でのサインイン

サーフェス	手順
ChatGPT web	ChatGPT を開いてサインインし、作業するワークスペースを選ぶ。認証済みセッションはブラウザに保持される
ChatGPT desktop app	サインアウト画面で Continue to sign in を選び、ブラウザのフローを完了する
Codex CLI	`codex login` を実行してブラウザのフローを完了する。有効なセッションが無いときの既定の認証経路
IDE extension	サインアウト画面で Sign in with ChatGPT

API キーでのサインイン

サーフェス	手順
ChatGPT desktop app	サインアウト画面で Sign in another way → キーを入力 → Continue
Codex CLI	`printenv OPENAI_API_KEY \| codex login --with-api-key`（stdin でキーを渡す）
IDE extension	サインアウト画面で Use API Key → キーを入力 → OK

API キーの利用は OpenAI Platform アカウントで標準の API レートで課金される
API キー認証はローカルの Codex ワークフローに対応するが、ChatGPT ワークスペースのアクセスや cloud サービスに依存する一部の機能は制限されるか使えない
Codex CLI と ChatGPT desktop app の Codex では、API キー認証でも対応する OpenAI curated plugin を使える。一部の plugin は接続フローが未対応の OAuth 機能を要するため使えない
API キーでサインインすると、ChatGPT プランに含まれるクレジットではなく標準の API 料金になる
API キー認証は CI/CD ジョブのようなプログラム的な CLI ワークフロー向け。untrusted・公開環境で Codex の実行を露出させない

状態確認とサインアウト

サーフェス	方法
ChatGPT web	プロフィールメニューでアカウントとワークスペースを確認。Log out でそのブラウザのセッションを終える
ChatGPT desktop app / IDE extension	プロフィールメニューでアカウントまたは API キーの状態を確認。Log out で資格情報を消す
Codex CLI	`codex login status` で有効な認証方法を確認、`codex logout` で消す

Codex access token（エンタープライズ自動化向け）

ChatGPT Enterprise ワークスペースで、管理者が access token の権限を付与した場合に、許可されたメンバーが Codex access token を作れる
ブラウザのサインイン無しで、ChatGPT ワークスペースのアクセス・ChatGPT 管理の Codex entitlement・エンタープライズのワークスペース制御が必要な自動化に使う
信頼されたスクリプト、スケジューラ、プライベートな CI runner を想定している。一般の OpenAI API 呼び出しには引き続き Platform API キーを使う
CLI では printenv CODEX_ACCESS_TOKEN | codex login --with-access-token

ChatGPT でも API キーでも、サインイン情報はキャッシュされ再利用される。CLI と拡張機能は同じキャッシュを共有するため、どちらかからログアウトすると次回どちらを起動しても再サインインが要る
キャッシュ先は ~/.codex/auth.json の平文ファイル、または OS 固有の資格情報ストア
ChatGPT サインインのセッションでは、期限切れ前に自動でトークンをリフレッシュするため、アクティブなセッションは通常ブラウザ再ログイン無しに継続する

資格情報の保存先

cli_auth_credentials_store で制御する。

値	挙動
`file`	`CODEX_HOME`（既定 `~/.codex`）配下の `auth.json` に保存する
`keyring`	OS の資格情報ストアに保存する
`auto`	OS の資格情報ストアが使えればそれを使い、無ければ `auth.json` にフォールバックする

ファイルベースを使う場合、~/.codex/auth.json はアクセストークンを含むためパスワードと同様に扱う。コミット・貼り付け・共有をしない

ログイン方法とワークスペースの強制

forced_login_method = "chatgpt" または "api" で認証方法を限定する
forced_chatgpt_workspace_id で ChatGPT ログイン時のワークスペースを限定する
有効な資格情報が設定した制約に合わない場合、Codex はユーザーをログアウトさせて終了する
これらは通常、ユーザーごとの設定ではなく managed configuration で適用される

Codex cloud アカウントの保護

Codex cloud はコードベースを直接扱うため、MFA を有効にする
ソーシャルログイン（Google / Microsoft / Apple）を使う場合、ChatGPT アカウントでの MFA 有効化は必須ではないが、プロバイダ側で設定できる
SSO 経由の場合、組織の SSO 管理者が全ユーザーに MFA を強制すべきとされている
メールとパスワードでログインする場合、Codex cloud を使う前に MFA の設定が必須
複数のログイン方法があり、そのうち 1 つがメールとパスワードの場合、別の方法でサインインしていても MFA の設定が必要

ヘッドレス環境でのログイン

ブラウザベースのログイン UI が動かない状況（リモート／ヘッドレス環境、localhost コールバックがネットワーク設定でブロックされる場合）向け。

推奨: device code authentication（beta）
1. ChatGPT のセキュリティ設定（個人アカウント）またはワークスペース権限（管理者）で device code login を有効にする
2. 対話ログイン UI で Sign in with Device Code を選ぶか、codex login --device-auth を実行する
3. リンクをブラウザで開いてサインインし、ワンタイムコードを入力する
フォールバック 1: 別マシンで認証して auth キャッシュをコピーする
- ブラウザが使えるマシンで codex login → ~/.codex/auth.json の存在を確認 → ヘッドレス側の ~/.codex/auth.json にコピーする
- OS が ~/.codex/auth.json ではなく資格情報ストアに保存している場合、この方法は使えないことがある
フォールバック 2: localhost コールバックを SSH でフォワードする
- Codex のローカルコールバックサーバー（既定 localhost:1455）をトンネルする

ログイン診断

直接の codex login 実行は、設定したログディレクトリ配下に専用の codex-login.log を書く。ブラウザログインや device-code の失敗をデバッグするときに使う

カスタム CA バンドル

企業の TLS プロキシやプライベートルート CA を使うネットワークでは、ログイン前に CODEX_CA_CERTIFICATE に PEM バンドルを設定する
CODEX_CA_CERTIFICATE が未設定のとき SSL_CERT_FILE にフォールバックする
同じ CA 設定が、ログイン・通常の HTTPS リクエスト・セキュア WebSocket 接続に適用される

代替モデルプロバイダの認証

カスタムモデルプロバイダを定義したときに選べる方法。

方法	設定
OpenAI 認証	`requires_openai_auth = true`。ChatGPT でも API キーでもサインインできる。LLM プロキシ経由で OpenAI モデルにアクセスする場合に有用。このとき `env_key` は無視される
環境変数認証	`env_key = "<ENV_VARIABLE_NAME>"` でローカル環境変数からプロバイダ固有の API キーを読む
認証なし	`requires_openai_auth` を設定しない（または `false`）かつ `env_key` も設定しない場合、プロバイダは認証不要と見なされる。ローカルモデル向け

設定

# file | keyring | auto
cli_auth_credentials_store = "keyring"

forced_login_method = "chatgpt" # or "api"
forced_chatgpt_workspace_id = "00000000-0000-0000-0000-000000000000"

printenv OPENAI_API_KEY | codex login --with-api-key
printenv CODEX_ACCESS_TOKEN | codex login --with-access-token
codex login --device-auth
codex login status
codex logout

export CODEX_CA_CERTIFICATE=/path/to/corporate-root-ca.pem
codex login

ssh -L 1455:localhost:1455 user@remote