Authenticating Models with Azure Workload Identity

Solace Agent Mesh can connect to a model in Microsoft Foundry (formerly Azure OpenAI) without an API key or a client secret. With the Azure Workload Identity authentication type, Agent Mesh signs in as a Microsoft Entra identity that you name on the model, using a short-lived token for its Kubernetes service account. The model configuration stores no secret, so there is no key to rotate or leak. This page covers enabling the option for your deployment, the requirements for the Azure identity, and adding the model. For more information about model configurations in general, see Configuring Models.

How Azure Workload Identity Works

The Entrypoint Executor, Agent-Workflow Executor, and Secure Tool Runtime pods of an Agent Mesh deployment run under one Kubernetes service account, and Kubernetes issues them a short-lived token for that service account. When a model that uses Azure Workload Identity sends a request, Agent Mesh exchanges this token with Microsoft Entra ID for an access token of the identity named on the model, and sends the access token to the model's Azure endpoint. The Platform service runs in the Entrypoint Executor pod. The Platform service signs in when you test the model's connection, and the Agent-Workflow Executor signs in when an agent calls the model.

Microsoft Entra ID accepts the exchange only when the identity has a federated credential that trusts the token. A federated credential names four values, and each must match the token exactly:

  • The issuer URL of the Kubernetes cluster that issued the token.

  • The Kubernetes namespace that Agent Mesh runs in.

  • The name of the Agent Mesh service account.

  • The token's audience, api://AzureADTokenExchange by default.

The identity can be a user-assigned managed identity or an app registration, and it requires a role on the Azure resource that serves the model. Each model names its own identity by its client ID and tenant ID, so different models can sign in as different identities. Each of those identities needs its own federated credential for the Agent Mesh service account.

Where Azure Workload Identity Is Available

Agent Mesh offers the Azure Workload Identity authentication type only on deployments that enable it:

  • In a Kubernetes deployment, Azure Workload Identity is off by default. An administrator can enable it by setting the SAM_AZURE_WORKLOAD_IDENTITY_ENABLED environment variable to true. The AZURE_FEDERATED_TOKEN_FILE environment variable must also be set; the Helm chart or the Microsoft Azure Workload Identity webhook sets it. For more information, see Environment Variables. With the Agent Mesh Helm chart, a Helm value sets these variables for you. For more information, see Enabling Azure Workload Identity in a Kubernetes Deployment.

  • In Agent Mesh Cloud, Azure Workload Identity is available. If the Models page does not offer it for your deployment, contact Solace. For more information, see Agent Mesh Cloud.

While the option is disabled, the Models page does not offer Azure Workload Identity, and Agent Mesh rejects a model that uses it. The Edit form keeps showing Azure Workload Identity for a model that uses it, even after the option is disabled for the deployment.

Prerequisites

Before you begin, make sure that you have these items:

  • A Kubernetes cluster, such as Azure Kubernetes Service, Amazon Elastic Kubernetes Service, or Google Kubernetes Engine.
    • Its service account token issuer must be published at a URL that Microsoft Entra ID can reach over the internet. Microsoft Entra ID fetches the issuer's signing keys from that URL.

    • The Microsoft Azure Workload Identity webhook is not required.

  • A Microsoft Foundry (formerly Azure OpenAI) resource with a model deployment.

  • A user-assigned managed identity or an app registration in Microsoft Entra ID, and an Azure administrator who can add a federated credential and a role assignment to it.

  • The model_config:_:create scope in Agent Mesh, to add a model. To see the values for the federated credential, you need the model_config:_:create or model_config:*:update scope. For more information about role-based access control (RBAC) scopes, see RBAC Reference.

Model Endpoints

Agent Mesh sends the Microsoft Entra access token with every request to the model's endpoint, so use an endpoint that you trust. As with the other authentication types, Agent Mesh accepts any endpoint. Typically, the endpoint is the Azure resource itself, such as https://<resource>.openai.azure.com/ or https://<resource>.services.ai.azure.com/.

The scope of the access token that Agent Mesh requests depends on the endpoint's host:

  • For a <resource>.services.ai.azure.com endpoint, the scope is https://ai.azure.com/.default.

  • For any other endpoint, the scope is https://cognitiveservices.azure.com/.default.

A proxy in front of Azure can serve as the endpoint when it accepts that access token and serves the same request paths as the Azure resource. Agent Mesh does not support the azure_chat_route: deployment model parameter with this authentication type.

Enabling Azure Workload Identity in a Kubernetes Deployment

For a Kubernetes deployment, enable the option with the samDeployment.azureWorkloadIdentity Helm values, which require Agent Mesh Helm chart version 2.2.0 or later. The chart sets the SAM_AZURE_WORKLOAD_IDENTITY_ENABLED and AZURE_FEDERATED_TOKEN_FILE environment variables from these values. In Agent Mesh Cloud, skip this section.

Any pod that runs as the Agent Mesh service account can sign in as every identity that trusts it. Enable Azure Workload Identity only in a Kubernetes namespace that you control and that runs Agent Mesh for a single organization.

To enable Azure Workload Identity, perform these steps:

  1. Add the following block to your values file, for example the production-values.yaml file from Installing Kubernetes for Production:

    # production-values.yaml
    samDeployment:
      serviceAccount:
        name: "sam-solace-agent-mesh-sa"
      azureWorkloadIdentity:
        enabled: true

    The federated credential names the service account exactly, so set samDeployment.serviceAccount.name to keep the name stable. When you leave it empty, the chart names the service account after the release, for example sam-solace-agent-mesh-sa for a release named sam.

  2. Apply the values to your release:

    helm upgrade sam /path/to/solace-agent-mesh-<version>.tar.gz \
      --namespace sam \
      --set-file global.imagePullKey=sam-pull-credentials.json \
      -f production-values.yaml

    The chart mounts a service account token with the audience api://AzureADTokenExchange into the Entrypoint Executor, Agent-Workflow Executor, and Secure Tool Runtime pods. Kubernetes renews the token before it expires. The chart also sets the SAM_AZURE_WORKLOAD_IDENTITY_ENABLED and AZURE_FEDERATED_TOKEN_FILE environment variables, and the pods restart.

  3. Open the Models page (see Opening the Models Page), click Add Model, select Microsoft Foundry as the Model Provider, and confirm that Authentication Type lists Azure Workload Identity. Close the form without saving.

When the Agent Mesh pods already carry the azure.workload.identity/use: "true" pod label, the Microsoft Azure Workload Identity webhook mounts the token instead of the chart. The chart adds that label when you use Azure Blob Storage with workload identity, and you can also add it yourself through samDeployment.podLabels. In that case, the chart sets only SAM_AZURE_WORKLOAD_IDENTITY_ENABLED, and it ignores samDeployment.azureWorkloadIdentity.audience, because the webhook's token always has the audience api://AzureADTokenExchange. For more information about these values, see Deployment in Helm Values Reference.

Azure Identity Requirements

The identity that a model signs in as must meet these requirements in Azure:

  • It has a federated credential that trusts the Agent Mesh service account. The federated credential must match the cluster issuer URL, namespace, service account, and audience of your Agent Mesh deployment.

  • It has a role on the Azure resource that serves the model: Cognitive Services OpenAI User for Azure OpenAI models (for example, GPT), or Cognitive Services User for other Microsoft Foundry models (for example, Claude).

Each identity that your models name must meet both requirements. An Azure administrator configures them in Azure. For more information, see Create Trust Between User-Assigned Managed Identity and External Identity Provider, Create a trust relationship between an app and an external identity provider, and Role-based access control for Microsoft Foundry in the Microsoft documentation.

To get the values for the federated credential, perform these steps:

  1. On the Models page, click Add Model.

  2. Select Microsoft Foundry as the Model Provider.

  3. Set Authentication Type to Azure Workload Identity.

    The form shows Cluster issuer URL, Namespace, Service account, Subject identifier, and Audience. Agent Mesh reads these values from the token of the pod that serves the form, so they are the values that the federated credential must match. Subject identifier combines the namespace and the service account as system:serviceaccount:<namespace>:<service-account>. Use it for a federated credential scenario in Azure that takes a subject identifier instead of a namespace and a service account.

    If the form reports that it is unable to show the federated credential values, the deployment cannot read its Kubernetes service account token. In a Kubernetes deployment, see The Form Cannot Show the Federated Credential Values. In Agent Mesh Cloud, contact Solace.

  4. Click Copy All Values and give the values to the Azure administrator who adds the federated credential. To add the model, you need the identity's client ID and tenant ID.

Adding a Model That Uses Azure Workload Identity

After the identity trusts Agent Mesh, add the model on the Models page. For more information about the other fields of the form, see Adding a Model.

To add the model, perform these steps:

  1. On the Models page, click Add Model.

  2. Enter a Display Name and a Description.

  3. Select Microsoft Foundry as the Model Provider.

  4. Set Authentication Type to Azure Workload Identity. The form shows the values for the federated credential, and the Microsoft Client ID and Microsoft Tenant ID fields.

  5. Enter the client ID and tenant ID of the identity:

    • Microsoft Client ID — The client ID of the user-assigned managed identity, or the application (client) ID of the app registration.

    • Microsoft Tenant ID — The tenant ID of the user-assigned managed identity, or the directory (tenant) ID of the app registration.

    Both are globally unique identifiers (GUIDs) in the format xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx, and neither is a secret. The form rejects a value in any other format.

  6. Enter the resource's endpoint as the API Base URL, such as https://<resource>.openai.azure.com/ or https://<resource>.services.ai.azure.com/. Enter the resource address without a path such as /anthropic, because Agent Mesh adds the route. For Claude on Microsoft Foundry, use the services.ai.azure.com address, because Claude accepts only the access token that Agent Mesh requests for that host.

  7. (Optional) Enter an API Version.

  8. Enter the Deployment Name as azure/<deployment-name>, where <deployment-name> is the name of the model deployment on the Azure resource.

  9. Click Test Connection. The Platform service signs in as the identity and calls the model. If the test fails with an Azure setup problem, the message shows what to fix. For more information, see Troubleshooting.

  10. Click Add to save the model. Agents can now select it by its display name in the Model picker.

Changing a model's Authentication Type to or from Azure Workload Identity discards the model's stored credentials. Enter the credentials of the new authentication type before you save.

Defining the Model as Code

To manage the model as declarative configuration, set authConfig.type to azure_workload_identity and give the identity's client_id and tenant_id. The provider must be azure_openai, which is the Microsoft Foundry provider in the Agent Mesh UI.

# azure-gpt.yaml
kind: model
name: azure-gpt
description: Microsoft Foundry model that signs in with Azure Workload Identity.
spec:
  provider: azure_openai
  modelName: azure/<deployment-name>
  apiBase: https://<resource>.openai.azure.com/
  authConfig:
    type: azure_workload_identity
    client_id: "<identity-client-id>"
    tenant_id: "<entra-tenant-id>"

The model's endpoint is apiBase, unless you set modelParams.endpoint, which overrides apiBase. That endpoint receives the access token, as Model Endpoints describes. Agent Mesh rejects a model with this authentication type when it also sets any of the following keys:

  • api_key, client_secret, token_url, or a key that starts with oauth_, in authConfig or modelParams.

  • client_id or tenant_id in modelParams.

  • The _file form of any of these keys.

  • modelParams.azure_chat_route: deployment.

For more information about the model kind and how to apply it, see Configuring Models with the CLI.

Troubleshooting

Azure Workload Identity Is Not Listed

The Authentication Type list for Microsoft Foundry shows only API Key and OAuth2. The deployment has not enabled Azure Workload Identity, or its pods have no service account token for it.

To resolve this issue:

  1. In Agent Mesh Cloud, contact Solace to check whether the option is available for your deployment.

  2. In a Kubernetes deployment, check that your values file sets samDeployment.azureWorkloadIdentity.enabled: true, and that you ran helm upgrade with it. Without the Helm chart, check that SAM_AZURE_WORKLOAD_IDENTITY_ENABLED is set to true and that AZURE_FEDERATED_TOKEN_FILE is set.

  3. Check that an Entrypoint Executor pod has both environment variables:

    kubectl exec -n sam <entrypoint-executor-pod> -- env | grep -E 'SAM_AZURE_WORKLOAD_IDENTITY_ENABLED|AZURE_FEDERATED_TOKEN_FILE'

    The output shows SAM_AZURE_WORKLOAD_IDENTITY_ENABLED=true and a file path for AZURE_FEDERATED_TOKEN_FILE. When the pods carry the azure.workload.identity/use label but AZURE_FEDERATED_TOKEN_FILE is missing, the Microsoft Azure Workload Identity webhook is most likely not installed on the cluster, or it was installed after the pods started.

The Form Cannot Show the Federated Credential Values

The form reports that it is unable to show the federated credential values. The Entrypoint Executor cannot read the file that AZURE_FEDERATED_TOKEN_FILE names, or the file does not hold a Kubernetes service account token.

To resolve this issue:

  1. Check that AZURE_FEDERATED_TOKEN_FILE in the Entrypoint Executor pod points to the mounted service account token, using the command in Azure Workload Identity Is Not Listed.

  2. If you set AZURE_FEDERATED_TOKEN_FILE yourself, for example through environmentVariables, remove the override so that the chart or the webhook sets it.

Saving the Model Fails

Agent Mesh does not save the model, and the error message names the field to fix. The following table lists the messages and their fixes.

Message Fix
azure_workload_identity auth is not enabled on this deployment Enable Azure Workload Identity for the deployment. See Azure Workload Identity Is Not Listed.
azure_workload_identity auth requires provider azure_openai Select Microsoft Foundry as the Model Provider, or set provider: azure_openai, and enter the model name as azure/<deployment-name>.
client_id must be a GUID or tenant_id must be a GUID Enter the identity's client ID and tenant ID as GUIDs.
<key> is not allowed with azure_workload_identity auth Remove the key that selects another sign-in, such as api_key or client_secret.
azure_chat_route deployment cannot be used with azure_workload_identity auth Remove azure_chat_route from the model parameters, or set it to v1.

Test Connection or a Chat Fails with an Azure Setup Problem

Test Connection fails with a message that names a cause and a fix. For the causes in the following table, the message also names an error code. In a chat, an agent that uses the model reports the same cause and states that an administrator needs to check the model's Azure setup. The following table lists the causes and their fixes.

Code Cause Fix
AADSTS700016 Azure has no application with this model's client ID in its tenant. Check the client ID and tenant ID on the model.
AADSTS90002 Azure has no tenant with this model's tenant ID. Check the tenant ID on the model.
AADSTS70025 The Azure identity has no federated credentials. Add a federated credential for the deployment's issuer, namespace, service account, and audience to the identity.
AADSTS70021, AADSTS700211, AADSTS700212, or AADSTS700213 No federated credential on the Azure identity matches this deployment. Make the federated credential match the deployment's issuer, namespace, service account, and audience exactly. A new or changed credential can take a few minutes to apply.
AADSTS50166 Microsoft Entra ID is unable to reach the cluster's token issuer. Make the cluster's issuer URL public so that Microsoft Entra ID can fetch the issuer's signing keys.
PermissionDenied The Azure identity is not allowed to call this Azure resource. Grant the identity the Cognitive Services OpenAI User role on the resource for Azure OpenAI models, or Cognitive Services User for other Microsoft Foundry models. A new role assignment can take a few minutes to apply.
DeploymentNotFound Azure OpenAI has no deployment with this model name at this endpoint. Check the model's endpoint and deployment name, and that the deployment still exists.

Two failures happen before Agent Mesh reaches Microsoft Entra ID, so the message names the deployment rather than the identity:

  • Agent Mesh is unable to read the deployment's service account token. Check that AZURE_FEDERATED_TOKEN_FILE points to the service account token mounted in the pod.

  • Agent Mesh is unable to reach Microsoft Entra ID to sign in. Check that the pods can reach login.microsoftonline.com. If they can, Microsoft Entra ID may be briefly unavailable, so try again later.

For any other sign-in failure, the message reports that Agent Mesh is unable to sign in to Azure with the model's workload identity. Check the client ID and tenant ID on the model, and the federated credential on the identity.

Next Steps

Your model signs in to Azure without a stored key, and agents can use it like any other model. For more information about assigning the model to an agent, see Creating Agents.