feat(auth): add X.509 workload identity federation for HTTP - #3622

What and why

Implement Phase 1 (HTTP only) of X.509 Workload Identity Federation in OpenAI SDKs: Design Proposal. Customers can exchange workload identity established by their existing mutually authenticated HTTP transport for an OpenAI access token without introducing SDK-owned certificates, private keys, token providers, or a configurable token endpoint.

Both OpenAI and AsyncOpenAI support the same additive, typed public API:

from openai import OpenAI
from openai.auth import x509_workload_identity

client = OpenAI(
    workload_identity=x509_workload_identity(
        identity_provider_id="idp_...",
        service_account_id="svc_acct_...",
    ),
    http_client=caller_configured_mtls_http_client,
)

refresh_buffer_seconds is optional. WorkloadIdentity remains the existing callable, backward-compatible subject-token TypedDict; both OpenAI and AsyncOpenAI accept the explicit typed union WorkloadIdentity | X509WorkloadIdentity. SubjectTokenWorkloadIdentity is a compatibility alias, and the public WorkloadIdentityAuth constructor remains narrowed to subject-token identities. The helper name, snake_case options, TypedDict configuration, SDK exception types, injected-client lifecycle, typed copy()/with_options(), and explicit sync/async implementations follow neighboring Python SDK patterns. Azure/Bedrock overriding copy signatures retain Python-compatible parameter variance without changing their provider authentication behavior. Async refresh uses AnyIO-compatible locking and sleep; it never runs an asynchronous exchange through blocking thread work.

Security, transport ownership, and compatibility

• Exchange tokens only with POST https://mtls.auth.openai.com/oauth/token; the JSON structurally omits subject_token, the exchange URL is not public configuration, and redirects are disabled per request.
• Reuse the effective caller-configured HTTPX2 or legacy HTTPX client for the exchange and the subsequent API request. Certificate chains, private keys, passphrases, trust, proxies, HSM integration, pooling, and rotation remain entirely owned by that native transport.
• Never mutate caller transport settings, retain certificate/key material, or include token/provider-controlled error details in exceptions or logs. Preserve the SDK's existing HTTP-client close/aclose ownership behavior.
• Use monotonic, bounded token caching with positive finite expires_in validation, half-TTL refresh-buffer clamping, sync and async single-flight refresh, cancellation-safe async waiters, bounded transient retries, and Retry-After handling.
• Invalidate once after a 401 and replay only genuinely replayable requests. Seekable uploads are rewound to their original offsets; one-shot upload streams and non-replayable bodies are never replayed.
• Default only X.509-mode clients without an explicit/environment base URL to https://mtls.api.openai.com/v1. Existing API-key authentication, JWT/ID-token workload identity, their separate exchange client, explicit base URLs, Python support policy, and dependency set are unchanged.
• Realtime/WebSockets are explicitly excluded; they belong to Phase 2.

Verification

The focused X.509 tests cover exact host/path/body and absence of subject_token, redirect refusal, transport/certificate ownership, transient retries and Retry-After, sync/async concurrency and cancellation, invalid/expired token responses and refresh windows, replayable versus one-shot upload/body behavior, safe error redaction, and API-key/JWT/ID-token regressions.

Formatting baseline disclosure: the unmodified upstream src/openai/resources/responses/responses.py already fails a whole-repository ruff format --check . on the exact base revision. The repository's actual ./scripts/lint, every changed file, and the other 1,717 files all pass; this PR intentionally does not modify unrelated generated code.

Maintainability and Python idiom review

The required strict thermo-nuclear-code-quality-review was completed against the complete exact fourteen-file publication diff: no structural blockers. X.509 logic is isolated in one 269-line handwritten auth module; neither new production nor test files exceed 1,000 lines. Mode selection occurs once in each existing sync/async constructor, subject-token and X.509 implementations share one properly initialized generic auth/cache base without identity casts, existing auth/retry/error layers remain canonical, and sync/async differences stay explicit.

The Python idiom review compared neighboring auth TypedDict/provider helpers, OpenAI/AsyncOpenAI injection and ownership, HTTPX/HTTPX2 request semantics, AnyIO cancellation, native SSLContext/transport boundaries, existing exception chaining/retry constants, pytest fixture style, and README examples. The result preserves established Python SDK naming, caller-client lifecycle, sync/async parity, and existing auth behavior without cross-language builder abstractions or hidden transport mutation.

Refreshed upstream base: 10ee3f0da2ac6f93345c1204bd7bb1a2faa79ff2

Validated publication head: 9512899eb98aab917ec9cf4c59342c77eb45c394

Prior independent installed-artifact mTLS validation

Built the exact committed wheel with .venv/bin/python -m build --no-isolation --outdir /private/tmp/openai-python-x509-round3-dist, installed that wheel into a clean temporary virtual environment, and executed /private/tmp/openai-python-x509-round3-venv/bin/python /private/tmp/openai-python-x509-second-round-e2e.py from outside the repository. The harness generates an ephemeral CA plus fresh server/client certificates, requires and verifies client-certificate presentation on every local HTTPS request, and connects the unmodified native HTTPX2 transport to the exact pinned authentication and API origins through a hermetic local CONNECT proxy.

Result: 19 sync/async scenarios passed; 48 real mTLS requests carried a verified client certificate (24 token exchanges, 24 API requests). Scenarios cover pinned host/path and token JSON without subject_token, bearer injection, token caching, actual clock-based refresh, transient retry/Retry-After, 401 refresh/replay, non-replayable multipart uploads that invalidate rejected tokens without replay, typed with_options() client copies that preserve their effective mTLS transport, async single-flight and waiter cancellation, sync/async timeouts, exchange/API redirect refusal including overridden auth, malformed token JSON, OAuth-error redaction, and the original callable WorkloadIdentity public API.

Residual scope limitation: no customer-enrolled production identity provider was contacted or required; the independent end-to-end exchange uses a real local mutually authenticated TLS service with freshly generated certificates.

Current exact-head independent verification

Final independently verified head: 9512899eb98aab917ec9cf4c59342c77eb45c394; fresh mergeable base: 10ee3f0da2ac6f93345c1204bd7bb1a2faa79ff2 (zero commits behind).

• Addressed all eight latest automated-review findings with 36 new sync/async regression cases: compare-and-invalidate rejected replay tokens; record and restore every seekable multipart upload's original file offset; support API-key-to-X.509 and X.509-to-API-key copies while preserving custom origins and resetting implicit defaults; prevent caller HTTP auth from leaking to the token endpoint or replacing exchanged API bearer tokens; explicitly reject X.509 identities from Azure copies; and reject malformed/missing-ID identities with typed errors. Each review thread has an exact fix explanation and is resolved.
• Built both wheel and source distribution from this exact committed tree with rye build --clean, installed the wheel into a freshly created virtual environment, and ran an external consumer through public OpenAI / AsyncOpenAI with a native HTTPX2 transport, ephemeral CA/server/client certificates, and a hermetic local CONNECT proxy. 32 independently reproduced scenarios passed over 78 real client-certificate-verified HTTPS requests: 38 exact-origin token exchanges and 40 API requests. The exchange body never contains subject_token and never inherits caller Authorization; scenarios also prove actual BasicAuth suppression, bearer injection, cache reuse/real-time refresh, transient retry, 401 replay and rejected-replay invalidation, real seekable multipart upload replay, one-shot upload invalidation, bidirectional API-key/X.509 mode switching, redirect refusal, timeout, cancellation/single-flight, typed/redacted errors, malformed identity rejection, and Azure boundaries.
• Ran the complete OpenAPI-mock-backed installed-wheel suite on every supported Python release: Python 3.10, 3.11, 3.12, 3.13, and 3.14 each passed 7,255 tests with 31 expected skips. The additional Python 3.10/Pydantic 1 suite passed 7,241 tests with 45 expected skips; the independently reproduced dedicated legacy HTTPX lane passed 130 tests.
• ./scripts/lint passes Ruff, Pyright (0 errors / 0 warnings), mypy (1,547 source files), and import validation. Python support-policy validation, Python 3.9 wheel rejection, Bedrock wheel validation, HTTPX2/aiohttp/legacy wheel validation, README formatting, changed-file formatting, Python compilation, and git diff --check all pass.
• The independently reproduced uv lock --check failure and one unrelated generated-file ruff format --check . failure are present unchanged on the exact upstream base; neither dependency locks nor generated baseline code were altered.
• Strict thermo-nuclear maintainability review and a separate Python-idiom review found no remaining structural or compatibility blocker. Scope remains HTTP-only; Realtime/WebSockets are Phase 2, and no production endpoint or customer credentials were used.