core/core-agent-ide
8
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
core-agent-ide/docs/auth-login-logging-plan.md
Josh McKinney 4e68fb96e2
feat: add auth login diagnostics (#13797) 
## Problem

Browser login failures historically leave support with an incomplete
picture. HARs can show that the browser completed OAuth and reached the
localhost callback, but they do not explain why the native client failed
on the final `/oauth/token` exchange. Direct `codex login` also relied
mostly on terminal stderr and the browser error page, so even when the
login crate emitted better sign-in diagnostics through TUI or app-server
flows, the one-shot CLI path still did not leave behind an easy artifact
to collect.

## Mental model

This implementation treats the browser page, the returned `io::Error`,
and the normal structured log as separate surfaces with different safety
requirements. The browser page and returned error preserve the detail
that operators need to diagnose failures. The structured log stays
narrower: it records reviewed lifecycle events, parsed safe fields, and
redacted transport errors without becoming a sink for secrets or
arbitrary backend bodies.

Direct `codex login` now adds a fourth support surface: a small
file-backed log at `codex-login.log` under the configured `log_dir`.
That artifact carries the same login-target events as the other
entrypoints without changing the existing stderr/browser UX.

## Non-goals

This does not add auth logging to normal runtime requests, and it does
not try to infer precise transport root causes from brittle string
matching. The scope remains the browser-login callback flow in the
`login` crate plus a direct-CLI wrapper that persists those events to
disk.

This also does not try to reuse the TUI logging stack wholesale. The TUI
path initializes feedback, OpenTelemetry, and other session-oriented
layers that are useful for an interactive app but unnecessary for a
one-shot login command.

## Tradeoffs

The implementation favors fidelity for caller-visible errors and
restraint for persistent logs. Parsed JSON token-endpoint errors are
logged safely by field. Non-JSON token-endpoint bodies remain available
to the returned error so CLI and browser surfaces still show backend
detail. Transport errors keep their real `reqwest` message, but attached
URLs are surgically redacted. Custom issuer URLs are sanitized before
logging.

On the CLI side, the code intentionally duplicates a narrow slice of the
TUI file-logging setup instead of sharing the full initializer. That
keeps `codex login` easy to reason about and avoids coupling it to
interactive-session layers that the command does not need.

## Architecture

The core auth behavior lives in `codex-rs/login/src/server.rs`. The
callback path now logs callback receipt, callback validation,
token-exchange start, token-exchange success, token-endpoint non-2xx
responses, and transport failures. App-server consumers still use this
same login-server path via `run_login_server(...)`, so the same
instrumentation benefits TUI, Electron, and VS Code extension flows.

The direct CLI path in `codex-rs/cli/src/login.rs` now installs a small
file-backed tracing layer for login commands only. That writes
`codex-login.log` under `log_dir` with login-specific targets such as
`codex_cli::login` and `codex_login::server`.

## Observability

The main signals come from the `login` crate target and are
intentionally scoped to sign-in. Structured logs include redacted issuer
URLs, redacted transport errors, HTTP status, and parsed token-endpoint
fields when available. The callback-layer log intentionally avoids
`%err` on token-endpoint failures so arbitrary backend bodies do not get
copied into the normal log file.

Direct `codex login` now leaves a durable artifact for both failure and
success cases. Example output from the new file-backed CLI path:

Failing callback:

```text
2026-03-06T22:08:54.143612Z  INFO codex_cli::login: starting browser login flow
2026-03-06T22:09:03.431699Z  INFO codex_login::server: received login callback path=/auth/callback has_code=false has_state=true has_error=true state_valid=true
2026-03-06T22:09:03.431745Z  WARN codex_login::server: oauth callback returned error error_code="access_denied" has_error_description=true
```

Succeeded callback and token exchange:

```text
2026-03-06T22:09:14.065559Z  INFO codex_cli::login: starting browser login flow
2026-03-06T22:09:36.431678Z  INFO codex_login::server: received login callback path=/auth/callback has_code=true has_state=true has_error=false state_valid=true
2026-03-06T22:09:36.436977Z  INFO codex_login::server: starting oauth token exchange issuer=https://auth.openai.com/ redirect_uri=http://localhost:1455/auth/callback
2026-03-06T22:09:36.685438Z  INFO codex_login::server: oauth token exchange succeeded status=200 OK
```

## Tests

- `cargo test -p codex-login`
- `cargo clippy -p codex-login --tests -- -D warnings`
- `cargo test -p codex-cli`
- `just bazel-lock-update`
- `just bazel-lock-check`
- manual direct `codex login` smoke tests for both a failing callback
and a successful browser login

---------

Co-authored-by: Codex <noreply@openai.com>
2026-03-06 15:00:37 -08:00

8.4 KiB
Raw Blame History

Auth Login Logging

Problem

Customer-side auth failures are hard to diagnose because the most important browser-login step, the final POST https://auth.openai.com/oauth/token after the localhost callback, historically does not show up as a first-class application event.

In the failing HARs and Slack thread, browser auth succeeds, workspace selection succeeds, and the browser reaches http://localhost:1455/auth/callback. Support can usually confirm that:

  • the user reached the browser sign-in flow
  • the browser returned to the localhost callback
  • Codex showed a generic sign-in failure

What support cannot reliably determine from Codex-owned logs is why the final token exchange failed. That leaves the most important diagnostic question unanswered:

  • was this a backend non-2xx response
  • a transport failure talking to auth.openai.com
  • a proxy, TLS, DNS, or connectivity issue
  • some other local client-side failure after browser auth completed

This documentation explains how the current instrumentation closes that gap without broadening the normal logging surface in unsafe ways.

Mental Model

The browser-login flow has three separate outputs, and they do not serve the same audience:

  • the browser-facing error page
  • the caller-visible returned io::Error
  • the normal structured application log

Those outputs now intentionally diverge.

The browser-facing page and returned error still preserve the backend detail needed by developers, sysadmins, and support engineers to understand what happened. The structured log stays narrower: it emits explicitly reviewed fields, redacted URLs, and redacted transport errors so the normal log file is useful without becoming a credential sink.

Non-goals

This does not add auth logging to every runtime request.

  • The instrumentation is scoped to the initial browser-login callback flow.
  • The refresh-token path in codex-core remains a separate concern.
  • This does not attempt to classify every transport failure into a specific root cause from string matching.

Tradeoffs

This implementation prefers fidelity for caller-visible errors and restraint for structured logs.

  • Non-2xx token endpoint responses log parsed safe fields such as status, error, and error_description when available.
  • Non-JSON token endpoint bodies are preserved in the returned error so CLI/browser flows still surface the backend detail that operators need.
  • The callback-layer structured log does not log %err for token endpoint failures, because that would persist arbitrary backend response text into the normal log file.
  • Transport failures keep the underlying reqwest error text, but attached URLs are redacted before they are logged or returned.
  • Caller-supplied issuer URLs are sanitized before they are logged, including custom issuers with embedded credentials or sensitive query params.

The result is not maximally detailed in one place. It is intentionally split so each surface gets the level of detail it can safely carry.

Architecture

The browser-login callback flow lives in codex-rs/login/src/server.rs.

The key behavior is:

  • the callback handler logs whether the callback was received and whether state validation passed
  • the token exchange logs start, success, and non-2xx responses as structured events
  • transport failures log the redacted reqwest error plus is_timeout, is_connect, and is_request
  • the browser-facing Codex Sign-in Error page remains intact
  • the returned io::Error continues to carry useful backend detail for CLI/browser callers

App-server consumers use the same login-server path rather than a separate auth implementation.

  • account/login/start calls into run_login_server(...)
  • app-server waits for server.block_until_done()
  • app-server emits account/login/completed with wrapped success/error state

That means the login-crate instrumentation benefits:

  • direct CLI / TUI login
  • Electron app login
  • VS Code extension login

Direct codex login also writes a small file-backed log through the CLI crate.

  • the file is codex-login.log under the configured log_dir
  • this uses a deliberately small tracing setup local to the CLI login commands
  • it does not try to reuse the TUI logging stack wholesale, because the TUI path also installs feedback, OpenTelemetry, and other interactive-session layers that are not needed for a one-shot login command
  • the duplication is intentional: it keeps the direct CLI behavior easy to reason about while still giving support a durable artifact from the same codex_login::server events

Observability

The main new signals are emitted from the login crate target, for example codex_login::server, so they stay aligned with the code that produces them.

The useful events are:

  • callback received
  • callback state mismatch
  • OAuth callback returned error
  • OAuth token exchange started
  • OAuth token exchange transport failure
  • OAuth token exchange returned non-success status
  • OAuth token exchange succeeded

The structured log intentionally uses a narrower payload than the returned error:

  • issuer URLs are sanitized before logging
  • sensitive URL query keys such as code, state, token, access_token, refresh_token, id_token, client_secret, and code_verifier are redacted
  • embedded credentials and fragments are stripped from logged URLs
  • parsed token-endpoint fields are logged individually when available
  • arbitrary non-JSON token endpoint bodies are not logged into the normal application log

This split is the main privacy boundary in the implementation.

Failure Modes

The current instrumentation is most useful for these cases:

  • browser auth succeeds but the final token exchange fails
  • custom issuer deployments need confirmation that the callback reached the login server
  • operators need to distinguish backend non-2xx responses from transport failures
  • transport failures need the underlying reqwest signal without leaking sensitive URL parts

It is intentionally weaker for one class of diagnosis:

  • it does not try to infer specific transport causes such as proxy, TLS, or DNS from message string matching, because that kind of over-classification can mislead operators

Security and Sensitivity Notes

This implementation treats the normal application log as a persistent surface that must be safe to collect and share.

That means:

  • user-supplied issuer URLs are sanitized before logging
  • transport errors redact attached URLs instead of dropping them entirely
  • known secret-bearing query params are redacted surgically rather than removing all URL context
  • non-JSON token endpoint bodies are preserved only for the returned error path, not the structured-log path

This behavior reflects two review-driven constraints that are already fixed in the code:

  • custom issuers no longer leak embedded credentials or sensitive query params in the starting oauth token exchange log line
  • non-JSON token endpoint bodies are once again preserved for caller-visible errors, but they no longer get duplicated into normal structured logs through callback-layer %err logging

Debug Path

For a failed sign-in, read the evidence in this order:

  1. Browser/HAR evidence: confirm the browser reached http://localhost:1455/auth/callback.
  2. Login-crate structured logs: check whether the callback was received, whether state validation passed, and whether the token exchange failed as transport or non-2xx.
  3. Caller-visible error: use the CLI/browser/app error text to recover backend detail that is intentionally not copied into the normal log file.
  4. App-server wrapper: if the flow runs through app-server, use account/login/completed and its wrapped Login server error: ... result as the client-facing envelope around the same login-crate behavior.

The most important invariant is simple: browser success does not imply login success. The native client still has to exchange the auth code successfully after the callback arrives.

Tests

The codex-login test suite covers the new redaction and parsing boundaries:

  • parsed token endpoint JSON fields still surface correctly
  • plain-text token endpoint bodies still remain available to the caller-visible error path
  • sensitive query values are redacted selectively
  • URL shape is preserved while credentials, fragments, and known secret-bearing params are removed
  • issuer sanitization redacts custom issuer credentials and sensitive params before logging