Authenticate with managed identity

APPLIES TO: All API Management tiers

Use the authentication-managed-identity policy to authenticate with a backend service using the managed identity. This policy essentially uses the managed identity to obtain an access token from Microsoft Entra ID for accessing the specified resource. After successfully obtaining the token, the policy will set the value of the token in the Authorization header using the Bearer scheme. API Management caches the token until it expires.

On managed gateways, both system-assigned identity and any of the multiple user-assigned identities can be used to request a token. If client-id isn't provided, system-assigned identity is assumed. If the client-id attribute is provided, a token is requested for that user-assigned identity from Microsoft Entra ID.

On a self-hosted gateway, use Microsoft Entra Workload ID by setting authentication-provider="WorkloadIdentity". The policy uses the identity configured for the gateway's workload, not the managed identity assigned to the API Management instance. Don't specify client-id with this provider. See Self-hosted gateway with workload identity.

Note

Set the policy's elements and child elements in the order provided in the policy statement. Learn more about how to set or edit API Management policies.

Caution

Security consideration: Users with permissions to edit API Management policies can use this policy to authenticate as the service's managed identity. However, they can't gain direct access to resources without first assigning a managed identity to the API Management instance. Once a managed identity is assigned, users who can modify policies may be able to exfiltrate the authentication token, propagate it to a backend, or log it for later use. For detailed security guidance and mitigation strategies, see Security considerations for managed identities in the managed identity overview.

Policy statement

<authentication-managed-identity resource="resource" client-id="clientid of user-assigned identity" authentication-provider="BuiltIn|WorkloadIdentity" output-token-variable-name="token-variable" ignore-error="true|false"/>

Attributes

Attribute Description Required Default
resource String. The application ID of the target web API (secured resource) in Microsoft Entra ID. Policy expressions are allowed. Yes N/A
authentication-provider String. The provider used to obtain a token. Allowed values: BuiltIn for the gateway's built-in managed identity authentication, or WorkloadIdentity for Microsoft Entra Workload ID on a self-hosted gateway. Policy expressions aren't allowed. No BuiltIn
client-id String. The client ID of the user-assigned identity in Microsoft Entra ID. Only supported with built-in authentication provider. Policy expressions aren't allowed. No N/A. With BuiltIn, system-assigned identity is used if the attribute isn't present.
output-token-variable-name String. Name of the context variable that will receive token value as an object of type string. Policy expressions aren't allowed. No N/A
ignore-error Boolean. If set to true, the policy pipeline continues to execute even if an access token isn't obtained. No false

Usage

Usage notes

  • If this policy is defined at the global scope, the token obtained will be available in the policy execution context for all APIs, including those in workspaces. If the token should only be available to specific APIs, consider applying the policy at a narrower scope (for example, product or API level) rather than the global policy.

  • Token forwarding is the customer's responsibility. When evaluating this policy, API Management obtains a token from Microsoft Entra ID and forwards it to the backend as-is in the Authorization header. API Management doesn't validate which backend the token is sent to. It's the customer's responsibility to ensure that tokens are only forwarded to intended and trusted backend services. Configure backend entities and other policies carefully to prevent tokens from being sent to unintended destinations.

Self-hosted gateway with workload identity

To use this policy on a self-hosted gateway, configure Microsoft Entra Workload ID for the gateway's workload and set authentication-provider="WorkloadIdentity" in the policy. For setup guidance, see Enable workload identity authentication for the self-hosted gateway.

The linked guide covers authentication to the API Management configuration endpoint. This policy authenticates requests to a backend, so also grant the workload's identity the permissions required to access that backend resource.

Examples

Use managed identity to authenticate with a backend service

<authentication-managed-identity resource="https://microsoftgraph.chinacloudapi.cn"/> 

<authentication-managed-identity resource="https://management.chinacloudapi.cn/"/> <!--Azure Resource Manager-->

<authentication-managed-identity resource="https://vault.azure.cn"/> <!--Azure Key Vault-->

<authentication-managed-identity resource="https://servicebus.chinacloudapi.cn/"/> <!--Azure Service Bus-->

<authentication-managed-identity resource="https://eventhubs.chinacloudapi.cn/"/> <!--Azure Event Hub-->

<authentication-managed-identity resource="https://storage.azure.com/"/> <!--Azure Blob Storage-->

<authentication-managed-identity resource="https://database.chinacloudapi.cn/"/> <!--Azure SQL-->

<authentication-managed-identity resource="https://signalr.azure.com"/> <!--Azure SignalR-->

<authentication-managed-identity resource="AD_application_id"/> <!--Application (client) ID of your own Azure AD Application-->

Use managed identity and set header manually

<authentication-managed-identity resource="AD_application_id"
   output-token-variable-name="msi-access-token" ignore-error="false" /> <!--Application (client) ID of your own Azure AD Application-->
<set-header name="Authorization" exists-action="override">
   <value>@("Bearer " + (string)context.Variables["msi-access-token"])</value>
</set-header>

Use managed identity in send-request policy

<send-request mode="new" timeout="20" ignore-error="false">
    <set-url>https://example.com/</set-url>
    <set-method>GET</set-method>
    <authentication-managed-identity resource="ResourceID"/>
</send-request>

Use workload identity on a self-hosted gateway

The following example authenticates to Azure Key Vault using the gateway workload's identity:

<authentication-managed-identity resource="https://vault.azure.cn" authentication-provider="WorkloadIdentity" />

Related content

For more information about working with policies, see:

  • Last updated on