Entra Workload Identity

Symptoms seen when AI systems, judges, or data generation authenticate with Microsoft Entra workload identity. Each section is keyed to the literal symptom, so match what you are seeing and skip the rest. Setup is covered in Microsoft Entra Workload Identity.

The Authentication Option Is Missing

Connect AI System lists No Authentication, Bearer Token, and API Key, but not Microsoft Entra Workload Identity. The capability is off on this deployment: set ENABLE_ENTRA_WORKLOAD_IDENTITY_AUTH to "true" on the API, as in step 4 of the setup. An SDK or API request for the same authentication type fails with:

entra_workload_identity authentication is not enabled on this deployment

API Fails to Start

After ENABLE_ENTRA_WORKLOAD_IDENTITY_AUTH is set to "true", the API crash-loops with:

ENABLE_ENTRA_WORKLOAD_IDENTITY_AUTH is enabled but the following required fields are missing: <fields>

Missing Field	Cause	Fix
AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_FEDERATED_TOKEN_FILE	The workload identity webhook did not inject them: the API pod lacks the azure.workload.identity/use label, or its service account lacks the azure.workload.identity/client-id annotation.	Apply both, as in step 3 of the setup.
ENTRA_ALLOWED_ENDPOINT_HOSTS	No endpoint host is allowed.	List the gateway hostnames your AI systems use.

Check the pod label and the service account annotation

kubectl -n <namespace> get pods -l azure.workload.identity/use=true
kubectl -n <namespace> get serviceaccount <service-account> -o jsonpath='{.metadata.annotations.azure\.workload\.identity/client-id}'

Save Fails: Endpoint Host Is Not Permitted

Endpoint host "<host>" is not permitted for Entra workload identity authentication on this deployment.

The endpoint host of the AI system is not in ENTRA_ALLOWED_ENDPOINT_HOSTS. Add the exact, lowercase hostname, with no scheme, port, or path, and roll the API so that it reads the new value.

Save Fails: Entra Token Acquisition Failed

Entra token acquisition failed: <message from Microsoft Entra ID>

The API could not request a token as the platform identity. The Microsoft Entra message names the cause:

Entra Error	Cause	Fix
AADSTS70021	No federated credential on the platform identity matches the API service account: the issuer, subject, or audience differs.	Recreate the federated credential with the values from step 1 of the setup.
AADSTS700016	The client ID does not name an identity in the tenant.	Correct the azure.workload.identity/client-id annotation on the service account.

Save Fails: The APIM Subscription Key Was Rejected

Gateway error: Received 401. The APIM subscription key was rejected.

Azure API Management rejected the request before it checked the token; the status can also be 403. Edit the AI system and enter the subscription key again. A key field left empty during an edit keeps the stored key.

Save Fails: The Identity Is Not Authorized

Authorization error: Received 403. The platform's Entra identity was authenticated but is not authorized for this endpoint - check its Azure role assignment.

The token was issued, but the endpoint refused it. Either the platform identity lacks the role or app role that the endpoint requires, as in step 2 of the setup, or the token was requested for a scope whose audience the gateway does not accept. Check Azure Scope on the AI system.

Save Fails: Client ID or Tenant ID Is Rejected

The UI checks these fields before it submits. An SDK or API request receives one of:

entra_workload_identity type config.client_id and config.tenant_id must be provided together
entra_workload_identity type config.client_id must be a GUID if provided

Set both IDs or neither, each as a GUID.

First Evaluation Fails After Naming a Customer-Owned Identity

The AI system saved without a connection test, because the platform cannot request a token as a customer-owned identity, and the first evaluation then fails with an authentication error. The failed test carries the error; the worker log has the full message. Worker pods are short-lived, so retain one to read its log.

Error in the Run	Cause	Fix
AADSTS70021	The federated credential on the customer-owned identity does not trust the evaluation worker service account.	Correct its subject to system:serviceaccount:<namespace>:<evaluation-worker-service-account>, with the cluster OIDC issuer and the api://AzureADTokenExchange audience.
AADSTS700016	Managed Identity Client ID or Managed Identity Tenant ID on the AI system is wrong.	Correct both on the AI system.
HTTP 401 or 403 from the gateway	The identity lacks the app role that the gateway checks, the gateway expects a different client ID or audience, or the APIM subscription key is wrong.	Confirm the gateway policy with the endpoint owner, and check Azure Scope on the AI system.

Evaluation Worker or Data Processing Fails at Startup

Message	Fix
azure_entra_auth is mutually exclusive with AZURE_API_KEY; unset AZURE_API_KEY when AZURE_ENTRA_AUTH is enabled	Remove AZURE_API_KEY from the evaluation worker.
AZURE_ENTRA_AUTH is mutually exclusive with AZURE_OPENAI_API_KEY; unset AZURE_OPENAI_API_KEY when Entra auth is enabled	Remove AZURE_OPENAI_API_KEY from data processing.
azure_entra_auth credential 'workload_identity' requires the AKS workload identity environment, missing: <variables>	Put the pod on the workload identity, as in step 3 of the setup, including RBAC for the evaluation workers.
ENTRA_WORKLOAD_IDENTITY requires tenant_id, client_id, and a federated token file	The evaluation worker that called an Entra AI system is not on the workload identity. Apply step 3 to the evaluation workers.