Naveen Gopalakrishna

Posted on Sep 29 Originally published at naveenneog.github.io

Run Codex CLI on Azure OpenAI Without an API Key: Entra ID Step-by-Step

#azure #ai #devtools #security

OpenAI's Codex CLI can run against your own Azure OpenAI
deployment, authenticated with Microsoft Entra ID — az login on a workstation. No API key on
disk, no proxy, no WSL.

That sentence contradicts the official documentation. This article shows the measurement that
settles it, then the procedure.

Verified on 29 Sep 2026, codex-cli 0.153.0, Node 26.1.0, Windows 11 + PowerShell 7,
against gpt-5.3-codex on an Azure AI Services account with local authentication disabled.

Note
Resource names in the screenshots are placeholders (contoso-aoai). Everything else — commands,
errors, output — is captured verbatim from a real run.

The problem

The documented setup passes an Azure OpenAI API key through an environment variable named by
env_key in ~/.codex/config.toml
(MS Learn).

In an enterprise subscription that path is often closed before you start. Cognitive Services
accounts commonly carry disableLocalAuth = true, which does not merely hide keys — it means no
key exists to list:

That is not a permissions gap you can fix with a role assignment. It is a tenant security posture.
In the subscription this was built against, all 14 OpenAI and AI Services accounts were set that
way.

So you look for the Entra ID route, and the same MS Learn page says, under Troubleshooting:

Entra ID support is currently not available for Codex.

Read together, the two statements leave no working configuration.

The measurement

Both statements are true, and the conclusion drawn from them is wrong.

Codex transmits the env_key value as an Authorization: Bearer header. The Azure v1 API
surface (/openai/v1) accepts Microsoft Entra access tokens on that header. So a token obtained
from az and placed in that variable authenticates — no key involved.

You can confirm this in two commands, before installing anything:

200 OK. The endpoint accepts the token.

What the documentation means is that Codex has no native Entra integration: it never calls
Microsoft Entra ID, never notices az login, and never refreshes a token when one expires. It does
not reject one. That distinction is the whole article — and it is also the catch, which
Known limits returns to.

Prerequisites

Requirement	Notes
An Azure subscription with an Azure OpenAI or AI Services account	Local auth may be disabled; that is the point
A deployed reasoning model	`gpt-5.3-codex`, `gpt-5-codex`, `gpt-5`, `gpt-6-astra`, …
Azure CLI, signed in	`az login`
An RBAC role granting data-plane inference	Cognitive Services OpenAI User on the account
Node.js 20+	Verified on 26.1.0
Codex CLI	`npm install -g @openai/codex@0.153.0` — pin it, see Step 1

WSL is not required. The MS Learn prerequisites list WSL2 for Windows; the CLI was verified
running natively in PowerShell.

Step 1 — Install Codex CLI (and pin the version)

npm install -g @openai/codex@0.153.0
codex --version

Important
Do not run a bare npm install -g @openai/codex. At the time of writing, the latest dist-tag
resolved to 0.155.0-alpha.9-win32-x64 — a platform-specific prerelease that declares
"bin": null and ships the executable under vendor/<target-triple>/bin/. npm installs it and
creates no shim, so codex disappears from PATH entirely. This is how I lost a working
install mid-session.

Check the dist-tag yourself before upgrading:

npm dist-tag ls @openai/codex

Step 2 — Confirm your deployment

Find the account name and deployment name. The account name is what you need — not a hostname.

az cognitiveservices account list --query "[].{name:name,group:resourceGroup}" -o table
az cognitiveservices account deployment list -n <resource> -g <group> --query "[].name" -o tsv

Note
AI Services accounts publish *.cognitiveservices.azure.com as their primary endpoint. That is
not the inference host. The same account also publishes an *.openai.azure.com endpoint, and
that is the one Codex needs. You can see both under properties.endpoints.

Step 3 — Grant data-plane access

Reading the account with az is control-plane access; calling the model is not. Assign the
data-plane role to yourself if you do not already hold it:

az role assignment create `
  --assignee "<your-upn>" `
  --role "Cognitive Services OpenAI User" `
  --scope "/subscriptions/<sub>/resourceGroups/<group>/providers/Microsoft.CognitiveServices/accounts/<resource>"

A missing role shows up later as 401 or 403 from the model endpoint, not as a configuration
error.

Step 4 — Understand the configuration Codex needs

This is the file the wrapper in Step 5 generates for you. It is worth reading once, because three of
the five lines are the ones people get wrong:

model = "gpt-5.3-codex"          # your DEPLOYMENT name, not the model family
model_provider = "azure"
model_reasoning_effort = "medium"

[model_providers.azure]
name = "Azure OpenAI"
base_url = "https://<resource>.openai.azure.com/openai/v1"   # /openai/v1, no /responses
env_key = "AZURE_OPENAI_API_KEY"                             # a VARIABLE NAME, never the value
wire_api = "responses"                                       # required for GPT-5+ / reasoning models

Key	Common mistake
`base_url`	Using the `cognitiveservices.azure.com` host, omitting `/openai/v1`, or appending `/responses` — Codex appends it for you, giving `/responses/responses`
`env_key`	Pasting the credential in directly. It must name an environment variable
`wire_api`	Leaving it as `chat`. GPT-5+ reasoning models need `responses`, otherwise you get `OperationNotSupported`
`model`	Using the model family name instead of your deployment name

Step 5 — Install the wrapper

The token has to be fetched and injected on every launch, because it expires. That is what
codex-on-azure does — a zero-dependency Node
wrapper that acquires a fresh Entra token, writes the config above into a local CODEX_HOME, and
starts Codex with the token passed in memory only.

git clone https://github.com/naveenneog/codex-on-azure.git
cd codex-on-azure
npm link

It installs nothing: the tool uses only the Node standard library.

Tip
Your existing ~/.codex/config.toml is never read or modified. The generated configuration goes
to a separate .codex-azure/ directory and is passed via CODEX_HOME, so a personal Codex setup
keeps working untouched.

Step 6 — Point it at your deployment

Nothing about any tenant is baked into the repo. Configure it with two environment variables:

$env:CODEX_AZURE_RESOURCE   = "<your-account-name>"
$env:CODEX_AZURE_DEPLOYMENT = "<your-deployment-name>"

or with a codex-azure.targets.json for several deployments:

{
  "default": "codex",
  "targets": {
    "codex": { "resource": "contoso-aoai", "deployment": "gpt-5.3-codex" },
    "fast":  { "resource": "contoso-aoai", "deployment": "gpt-5-mini" }
  }
}

Then confirm what it resolved, without launching anything:

Step 7 — Run it

codex-azure                                   # interactive TUI
codex-azure -- exec "explain this repo"       # one-shot
codex-azure -m fast                           # another configured deployment

The session header is the proof: provider: azure, your deployment, and no key anywhere.

How the token reaches Codex safely

Two things in the wrapper are worth calling out, because both came from getting them wrong first.

The token never touches disk. It is passed to the child process in the environment, never
written into config.toml, never returned to callers, and never placed on a command line. A
generated config that somehow contained a credential is rejected before it is written.

No child process is spawned through a shell. The first implementation used shell: true with
hand-written argument quoting, because npm installs codex as a .cmd shim on Windows and Node
refuses to spawn those otherwise. A review proved that exploitable: cmd.exe parses the command line
before the callee does, has no backslash escape for quotes, and expands %VAR% even inside them.
An ordinary prompt containing a quote followed by & executed an arbitrary command — and could read
the live Entra token straight out of the child's environment.

The fix was not better escaping. It was removing the shell: resolve the real executable (the Node
entry the shim wraps) and spawn with shell: false and an argument array. A second finding in the
same review: a bare az was resolvable from the current directory before PATH, so a planted
az.bat in any repository would have run against a signed-in user. Same fix, applied to both.

That story, with the options considered and rejected, is
ADR-0003
in the repo.

Step 8 — Verify

The repo ships its own proof, and you can run it:

node --test                               # offline suite
npm run test:live                         # adds a real Azure round trip
node scripts/mutate.mjs                   # mutation harness
node .ironclad/gate.mjs --stage packet    # definition of done

The middle one matters most. A passing test suite proves nothing on its own, so mutate.mjs breaks
one guarded behaviour at a time — including re-enabling shell: true — and fails if the tests do
not notice. 31 of 31 caught. It also fails when a mutation's anchor is missing or matches more
than once, which caught a mutation that had been silently measuring the wrong line.

Known limits

Read these before you rely on it.

Limit	Detail
Token lifetime ~55–60 min	Codex cannot refresh a credential. A session running past expiry fails with `401`. A fresh token is acquired per launch, so restarting fixes it
Bearer forwarding is observed, not contracted	Codex forwarding `env_key` as a bearer token is current behaviour, not documented API. A live test fails on a real request if that ever changes
Token is in Codex's environment	Processes Codex spawns inherit it. It is a delegated user token, short-lived but broad
One launch at a time	The generated config directory is shared between launches
`gpt-6-astra` warns	`Model metadata not found` on 0.141.0 and 0.153.0, which MS Learn lists as validated. It still answers; `gpt-5.3-codex` runs clean

Troubleshooting

Symptom	Cause and fix
`Failed to list key. disableLocalAuth is set to be true`	Working as intended. There is no key; use this guide
`401` / `403` from the model	Missing data-plane role. Assign Cognitive Services OpenAI User (Step 3)
`401` after about an hour	Token expired. Relaunch
`OperationNotSupported`	`wire_api` is not `responses`
`404` or `/responses/responses` in the URL	`base_url` is wrong — it must end at `/openai/v1`
`codex` not found after upgrading	The `latest` npm tag has no `bin`. Pin `@openai/codex@0.153.0` (Step 1)
`ENOTFOUND` / DNS error	`base_url` uses the `cognitiveservices.azure.com` host instead of `openai.azure.com`

Why the repo looks like that

codex-on-azure was built test-first, with every
architectural decision written down as an ADR and an executable gate as the definition of done.

The most useful file is docs/UNKNOWNS.md:
a register where each thing that was not known is closed either by a measurement with a date, or by
an explicitly labelled assumption with the detector that would catch it being wrong. "Does Codex
send the key as a bearer token?" started life there as an open question, not an assumption — which
is the only reason the contradiction in the docs got resolved by measuring instead of by guessing.

Both security defects in this tool were found by review, not by tests. The tests at the time
covered & and | — but never next to a quote, which is exactly where the bug lived.

Reference

💻 Repo: github.com/naveenneog/codex-on-azure
📄 Codex with Azure OpenAI — Microsoft Learn
📄 Azure OpenAI v1 API lifecycle
📄 Codex CLI configuration reference
🔐 ADR-0002 — why an Entra token is injected
🔐 ADR-0003 — why no child process uses a shell

Doing the same thing with Anthropic's tooling? See
Run Claude Code on Microsoft Foundry.

DEV Community