Edit

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.

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 variable is provided, token is requested for that user-assigned identity from Microsoft Entra ID.

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" 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
client-id String. The client ID of the user-assigned identity in Microsoft Entra ID. Policy expressions aren't allowed. No N/A. System-assigned identity is used if 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.

Examples

Use managed identity to authenticate with a backend service

<authentication-managed-identity resource="https://graph.microsoft.com"/> 

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

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

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

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

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

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

<authentication-managed-identity resource="https://database.windows.net/"/> <!--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>

Related content

For more information about working with policies, see:

  • Last updated on