For the complete documentation index, see llms.txt. Markdown versions of all docs pages are available by appending .md to any docs URL.

Authenticate to an Azure service from the gateway with a Microsoft Entra ID token.

Attaches to:

About

The azure backend authentication method gets a Microsoft Entra ID token and writes it to the Authorization header of every request that agentgateway forwards to the backend. Agentgateway requests the token for the Azure Cognitive Services scope, or for the Azure AI scope when the backend is an Azure AI Foundry endpoint, and it caches the credential after the first successful use.

The method has three forms.

• implicit detects the credential from the environment, through the full DefaultAzureCredential chain. Use this form in production when the host supplies the identity, such as a virtual machine with a managed identity.
• developerImplicit uses the Azure CLI login only. Use this form on a workstation, where it fails fast instead of trying the production sources first.
• explicitConfig names one credential source: a service principal, a managed identity, or a workload identity.

Configuration examples

Each example shows the backendAuth policy only. Attach it to a backend under backends[].policies, or to a route under routes[].policies.

backendAuth:
  azure:
    implicit: {}

backendAuth:
  azure:
    developerImplicit: {}

backendAuth:
  azure:
    explicitConfig:
      clientSecret:
        tenant_id: "$AZURE_TENANT_ID"
        client_id: "$AZURE_CLIENT_ID"
        client_secret: "$AZURE_CLIENT_SECRET"

backendAuth:
  azure:
    explicitConfig:
      managedIdentity: {}

backendAuth:
  azure:
    explicitConfig:
      managedIdentity:
        userAssignedIdentity:
          clientId: "<your-client-id>"

backendAuth:
  azure:
    explicitConfig:
      workloadIdentity: {}

Error: routes[0]: data did not match any variant of untagged enum BackendAuthCompat

How agentgateway resolves an implicit credential

With implicit, agentgateway tries the following credential sources in order and stops at the first one that returns a token. The chain matches the DefaultAzureCredential chain of the Azure SDK.

1. Environment credential. A service principal, used when AZURE_TENANT_ID, AZURE_CLIENT_ID, and AZURE_CLIENT_SECRET are all set.
2. Workload identity credential. A federated token, used when AZURE_FEDERATED_TOKEN_FILE, AZURE_TENANT_ID, and AZURE_CLIENT_ID are set.
3. Managed identity credential. The identity of the Azure host, read from the instance metadata service. A user-assigned identity is selected with AZURE_CLIENT_ID.
4. Developer tools credential. The cached login of the Azure CLI (az login) or the Azure Developer CLI (azd auth login).

Agentgateway caches the source that first returns a token and uses it for every later request. Each azure policy keeps its own cache, so two backends that name different service principals do not share a credential.

Two behaviors of this chain are worth knowing.

• The managed identity step is guarded by a probe. Before it tries the instance metadata service, agentgateway opens a TCP connection to 169.254.169.254:80 and waits one second. If the connection does not succeed, agentgateway skips the step. Without the probe, the Azure SDK retries for about 99 seconds on a host that is not an Azure virtual machine, which would stall every request on the route. Agentgateway skips the probe when IDENTITY_ENDPOINT or MSI_ENDPOINT is set, because the SDK then uses that endpoint instead of the metadata service.
• The developer tools step needs a command that agentgateway does not bundle. Agentgateway calls az or azd when it needs a token. It does not open an interactive flow, and it does not run az login or azd auth login for you. Mounting a credential directory such as ~/.azure into a container makes a cached login available, but it does not install the command. In a container, use a service principal, a managed identity, or a workload identity instead.

Troubleshoot

A request that agentgateway cannot authenticate returns a 500.

backend authentication failed: the credential provider was not enabled