Microsoft Entra Workload Identity

Use Microsoft Entra workload identity when an AI system, or the LLM that DynamoEval uses for judging and data generation, accepts only Microsoft Entra ID access tokens. A common case is an Azure AI Foundry or Azure OpenAI deployment behind Azure API Management (APIM). DynamoEval mints a short-lived access token for each call and refreshes it before it expires, so an evaluation that runs for hours keeps authenticating. No token or client secret is stored.

This page sets the capability up on an AKS deployment. Variable names, release availability, and save-time behavior are in the Entra Workload Identity Reference.

Before You Begin

Requirement	Detail	Verify
Platform release	3.26.8 or later. A customer-owned identity requires 3.26.11 or later.	Confirm which build is running.
AKS workload identity	The OIDC issuer and workload identity are enabled on the cluster, as described in the Azure workload identity dependency.	az aks show --name <cluster> --resource-group <resource-group> --query "[oidcIssuerProfile.enabled, securityProfile.workloadIdentity.enabled]" returns true twice.
Platform identity	A user-assigned managed identity for the platform. The steps below federate it with the platform service accounts and authorize it on each endpoint.	az identity show --name <platform-identity> --resource-group <resource-group> --query clientId --output tsv returns its client ID.
Endpoint that accepts Entra tokens	The endpoint, or the gateway in front of it, validates Entra access tokens issued for the scope you configure: for example, an APIM validate-jwt policy, or an Azure AI Foundry resource with Microsoft Entra authentication enabled.	The endpoint owner confirms the accepted scope and the role or app role it requires; the connection test in step 5 proves it.

Enable Workload Identity for the Platform

1. Federate the platform identity with the platform service accounts. The API tests each Entra AI system when it is saved, and the evaluation workers call it during runs, so both service accounts need a federated credential. If both run under the same service account, one credential covers them.

   Create a federated credential for a platform service account

   az identity federated-credential create \
     --name <credential-name> \
     --identity-name <platform-identity> \
     --resource-group <resource-group> \
     --issuer "$(az aks show --name <cluster> --resource-group <resource-group> --query oidcIssuerProfile.issuerUrl --output tsv)" \
     --subject system:serviceaccount:<namespace>:<service-account> \
     --audience api://AzureADTokenExchange

   Verify that one subject is listed per service account:

   List the federated credentials on the platform identity

   az identity federated-credential list --identity-name <platform-identity> --resource-group <resource-group> --output table

2. Authorize the platform identity on each endpoint. For an Azure OpenAI or Azure AI Foundry resource, assign a role that permits inference, such as Cognitive Services OpenAI User. For an API registered in Microsoft Entra ID, assign the app role that the API, or its gateway policy, requires.

   Assign an inference role on an Azure OpenAI resource

   az role assignment create \
     --assignee <platform-identity-principal-id> \
     --role "Cognitive Services OpenAI User" \
     --scope <azure-openai-resource-id>

   Verify that the role is listed:

   List the role assignments on the resource

   az role assignment list --assignee <platform-identity-principal-id> --scope <azure-openai-resource-id> --output table

3. Run the platform pods as the identity. The AKS workload identity webhook injects the token file and the AZURE_* variables into a pod only when both settings below are present. Your DynamoAI deployment engineer applies them through the chart values.

   Object	Setting
   Platform service account	Annotation azure.workload.identity/client-id: <platform-identity-client-id>
   API pods, evaluation worker pods, and any data processing pods that use Entra	Label azure.workload.identity/use: "true"

   Do not set AZURE_CLIENT_ID, AZURE_TENANT_ID, or AZURE_FEDERATED_TOKEN_FILE in a values file. On AKS the webhook owns them; a hand-set value overrides the webhook and breaks the token exchange. The evaluation workers also need RBAC enabled in the DynamoEval chart: without it, the worker pods run as the default service account, which no federated credential matches.

   Verify that the webhook injected the identity into the API:

   Confirm the injected identity variables

   kubectl -n <namespace> exec deploy/<api-deployment> -- sh -c 'env | grep ^AZURE_'

4. Turn the capability on in the API. Set ENABLE_ENTRA_WORKLOAD_IDENTITY_AUTH to "true", and list each endpoint host in ENTRA_ALLOWED_ENDPOINT_HOSTS, as described in the API environment variables.

   Verify that the API starts and stays running. With the capability on, the API refuses to start when an identity variable or the host list is missing, and names what is missing; see API Fails to Start.

   Confirm the API rolled out

   kubectl -n <namespace> rollout status deploy/<api-deployment>

5. Connect the AI system. In Connect AI System, choose Microsoft Entra Workload Identity as the authentication type. The fields are described in Custom API Language Models.

   Verify that saving succeeds. Before it saves, the platform requests a token as the platform identity and sends a test request to the endpoint.

6. Optional: route judge, attacker, and data generation calls through Entra. Set the evaluation worker variables and, where DynamoGuard policy data generation uses Azure OpenAI, the data processing variables.

   Verify that an evaluation worker logs this line when it sets up its judge models. Worker pods are short-lived; retain one to read its logs.

   Azure provider credentials validated

Use a Customer-Owned Identity for One AI System

Some endpoint owners require a dedicated managed identity that only the evaluation workers can present, rather than the platform identity, which other platform workloads also use. Name that identity on the one AI system that needs it. Every other call keeps using the platform identity.

1. Platform operator: if the evaluation workers share a service account with other platform workloads, give them their own first; a federated credential that trusts a shared service account trusts every workload that runs as it. In the DynamoEval chart, set dynamoai-common.rbac.serviceAccount.create to true and dynamoai-common.rbac.serviceAccount.name to a dedicated name, then federate the platform identity with the new service account as in step 1.
2. Platform operator: share the AKS OIDC issuer URL, the namespace, and the evaluation worker service account name with the endpoint owner.
3. Endpoint owner: create a user-assigned managed identity. It needs no secret.
4. Endpoint owner: add a federated credential to that identity that trusts only the evaluation worker service account: the command in step 1, with --subject system:serviceaccount:<namespace>:<evaluation-worker-service-account>.
5. Endpoint owner: authorize the identity on the endpoint, for example with an app role on the API's app registration that the gateway checks along with the token issuer, audience, and client ID.
6. Endpoint owner: share the client ID, the tenant ID, the scope (for example, api://<application-id>/.default), the endpoint host, and the APIM subscription key, if the gateway requires one.
7. Platform operator: add the endpoint host to ENTRA_ALLOWED_ENDPOINT_HOSTS.
8. AI system owner: set Managed Identity Client ID and Managed Identity Tenant ID on the AI system, and save.

The platform does not test the connection when it saves an AI system that names its own identity, because only the evaluation workers can request a token as that identity. The first evaluation run is the test.

Verify that a short evaluation against the AI system completes. If authentication fails, the run fails with the Entra error; see First Evaluation Fails.

Any federated identity can be named

In release 3.26, the platform accepts any client ID on an AI system. Anyone who can create AI systems can therefore name any identity whose federated credential trusts the evaluation worker service account. Federate only identities intended for evaluation, and limit who can create AI systems.