openai/openai-python · error · OpenAIError

X.509 workload identity is not supported by Azure clients

Error message

X.509 workload identity is not supported by Azure clients

What it means

The AzureOpenAI client explicitly rejects the X.509 workload-identity option (client-level x509 credentials) because Azure auth uses API keys, AAD tokens, or token providers instead. Passing workload_identity to AzureOpenAI raises OpenAIError at construction.

Source

Thrown at src/openai/lib/azure.py:295

        - `api_version` from `OPENAI_API_VERSION`
        - `azure_endpoint` from `AZURE_OPENAI_ENDPOINT`

        Pass at most one of `api_key`, `azure_ad_token`, or `azure_ad_token_provider`.
        An explicit credential takes precedence over Azure credential environment variables.
        With no explicit credential, `AZURE_OPENAI_AD_TOKEN` takes precedence over `AZURE_OPENAI_API_KEY`.

        Args:
            azure_endpoint: Your Azure endpoint, including the resource, e.g. `https://example-resource.azure.openai.com/`

            azure_ad_token: Your Azure Active Directory token, https://www.microsoft.com/en-us/security/business/identity-access/microsoft-entra-id

            azure_ad_token_provider: A function that returns an Azure Active Directory token, will be invoked on every request.

            azure_deployment: A model deployment, if given with `azure_endpoint`, sets the base client URL to include `/deployments/{azure_deployment}`.
                Not supported with Assistants APIs.
        """
        if is_x509_workload_identity(workload_identity):
            raise OpenAIError("X.509 workload identity is not supported by Azure clients")

        api_key, azure_ad_token, azure_ad_token_provider = _resolve_azure_auth(
            api_key, azure_ad_token, azure_ad_token_provider
        )

        if _enforce_credentials and api_key is None and azure_ad_token is None and azure_ad_token_provider is None:
            raise OpenAIError(
                "Missing credentials. Please pass one of `api_key`, `azure_ad_token`, `azure_ad_token_provider`, or the `AZURE_OPENAI_API_KEY` or `AZURE_OPENAI_AD_TOKEN` environment variables."
            )

        if api_version is None:
            api_version = os.environ.get("OPENAI_API_VERSION")

        if api_version is None:
            raise ValueError(
                "Must provide either the `api_version` argument or the `OPENAI_API_VERSION` environment variable"
            )

View on GitHub (pinned to 9917c6e28e)

Solutions

1. Remove workload_identity and authenticate with api_key, azure_ad_token, or azure_ad_token_provider
2. For managed identity in Azure, use azure_identity.DefaultAzureCredential via azure_ad_token_provider
3. Keep x509 workload identity only for the plain OpenAI client where it is supported

Example fix

# before
client = AzureOpenAI(workload_identity=x509_opts)
# after
from azure.identity import DefaultAzureCredential
client = AzureOpenAI(azure_ad_token_provider=DefaultAzureCredential().get_token, ...)
# or AzureOpenAI(api_key=...)

if workload_identity is not None and using_azure:
    raise ValueError("configure azure_ad_token_provider instead of workload_identity")

def azure_auth_ok(kwargs: dict) -> bool:
    return "workload_identity" not in kwargs and any(
        k in kwargs for k in ("api_key", "azure_ad_token", "azure_ad_token_provider")
    ) or bool(os.environ.get("AZURE_OPENAI_API_KEY"))

try:
    client = AzureOpenAI(**opts)
except OpenAIError as e:
    raise SystemExit(f"Azure client config error: {e}") from e

When it happens

Trigger: Instantiating AzureOpenAI(workload_identity=...) with the cert-based workload identity intended for the base OpenAI client (Google Cloud style).

Common situations: Copy-pasting client setup between OpenAI and Azure flavors; migrating an app to Azure AD while keeping x509 config; config templates that set workload_identity unconditionally.

Related errors

• Missing credentials. Please pass one of `api_key`, `azure_ad
• Must provide either the `api_version` argument or the `OPENA
• Expected `azure_ad_token_provider` argument to return a non-
• "Could not resolve authentication method. Expected either ap
• Pass refreshable Bedrock credentials via `bedrock_token_prov

AI-assisted analysis of openai/openai-python@9917c6e28e (2026-08-28). Data as JSON: /api/errors/d29229fd817e7e77. Report an issue: GitHub.