Use managed identities in Azure API Management

APPLIES TO: All API Management tiers

This article shows you how to create a managed identity for an Azure API Management instance and how to use it to access other resources. A managed identity generated by Microsoft Entra ID allows your API Management instance to easily and securely access other Microsoft Entra protected resources, such as Azure Key Vault. Azure manages this identity, so you don't have to provision or rotate any secrets. For more information about managed identities, see What are managed identities for Azure resources?.

You can grant two types of identities to an API Management instance:

• A system-assigned identity is tied to your service and is deleted if your service is deleted. The service can have only one system-assigned identity.
• A user-assigned identity is a standalone Azure resource that can be assigned to your service. The service can have multiple user-assigned identities.

Create a system-assigned managed identity

Azure portal

To set up a managed identity in the Azure portal, you'll first create an API Management instance and then enable the feature.

1. Create an API Management instance in the portal as you normally would. Browse to it in the portal.

2. In the left menu, under Security, select Managed identities.

3. On the System assigned tab, switch Status to On. Select Save.

   

Azure PowerShell

The following steps walk you through creating an API Management instance and assigning it an identity by using Azure PowerShell.

1. If needed, install Azure PowerShell by using the instructions in the Azure PowerShell guide. Then run Connect-AzAccount to create a connection with Azure.

2. Use the following code to create the instance with a system-assigned managed identity. For more examples of how to use Azure PowerShell with an API Management instance, see API Management PowerShell samples.

   # Create a resource group.
   New-AzResourceGroup -Name $resourceGroupName -Location $location
   
   # Create an API Management Consumption Sku service.
   New-AzApiManagement -ResourceGroupName $resourceGroupName -Name consumptionskuservice -Location $location -Sku Consumption -Organization contoso -AdminEmail contoso@contoso.com -SystemAssignedIdentity
   

You can also update an existing instance to create the identity:

# Get an API Management instance
$apimService = Get-AzApiManagement -ResourceGroupName $resourceGroupName -Name $apiManagementName

# Update an API Management instance
Set-AzApiManagement -InputObject $apimService -SystemAssignedIdentity

Azure Resource Manager template

You can create an API Management instance with a system-assigned identity by including the following property in the resource definition:

"identity" : {
    "type" : "SystemAssigned"
}

This property tells Azure to create and manage the identity for your API Management instance.

For example, a complete Azure Resource Manager template might look like the following:

{
    "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
    "contentVersion": "0.9.0.0",
    "resources": [{
        "apiVersion": "2021-08-01",
        "name": "contoso",
        "type": "Microsoft.ApiManagement/service",
        "location": "[resourceGroup().location]",
        "tags": {},
        "sku": {
            "name": "Developer",
            "capacity": "1"
        },
        "properties": {
            "publisherEmail": "admin@contoso.com",
            "publisherName": "Contoso"
        },
        "identity": {
            "type": "systemAssigned"
        }
    }]
}

When the instance is created, it has the following additional properties:

"identity": {
    "type": "SystemAssigned",
    "tenantId": "<TENANTID>",
    "principalId": "<PRINCIPALID>"
}

The tenantId property identifies which Microsoft Entra tenant the identity belongs to. The principalId property is a unique identifier for the instance's new identity. Within Microsoft Entra ID, the service principal has the same name that you gave to your API Management instance.

Configure Key Vault access using a managed identity

The following configurations are needed for API Management to access secrets and certificates from an Azure key vault.

Configure access to key vault

1. In the portal, navigate to your key vault.

2. In the left menu, select Access configuration, and note the Permission model that is configured.

3. Depending on the permission model, configure either a key vault access policy or Azure RBAC access for an API Management managed identity.

   To add a key vault access policy:
   

   1. In the left menu, select Access policies.
   2. On the Access policies page,select + Create.
   3. On the Permissions tab, under Secret permissions, select Get and List, then select Next.
   4. On the Principal tab, Select principal, search for the resource name of your managed identity, and then select Next. If you're using a system-assigned identity, the principal is the name of your API Management instance.
   5. Select Next again. On the Review + create tab, select Create.

   To configure Azure RBAC access:
   

   1. In the left menu, select Access control (IAM).
   2. On the Access control (IAM) page, select Add role assignment.
   3. On the Role tab, select Key Vault Secrets User.
   4. On the Members tab, select Managed identity > + Select members.
   5. On the Select managed identity page, select the system-assigned managed identity or a user-assigned managed identity associated with your API Management instance, and then select Select.
   6. Select Review + assign.

Requirements for Key Vault firewall

If Key Vault firewall is enabled on your key vault, the following are additional requirements:

• You must use the API Management instance's system-assigned managed identity to access the key vault.

• In Key Vault firewall, enable the Allow Trusted Microsoft Services to bypass this firewall option.

• Ensure that your local client IP address is allowed to access the key vault temporarily while you select a certificate or secret to add to Azure API Management. For more information, see Configure Azure Key Vault networking settings.

  After completing the configuration, you may block your client address in the key vault firewall.

Virtual network requirements

If the API Management instance is deployed in a virtual network, also configure the following network settings:

• Enable a service endpoint to Azure Key Vault on the API Management subnet.
• Configure a network security group (NSG) rule to allow outbound traffic to the AzureKeyVault and AzureActiveDirectory service tags.

For details, see Network configuration when setting up Azure API Management in a VNet.

Supported scenarios using system-assigned identity

Obtain a custom TLS/SSL certificate for the API Management instance from Azure Key Vault

You can use the system-assigned identity of an API Management instance to retrieve custom TLS/SSL certificates stored in Azure Key Vault. You can then assign these certificates to custom domains in the API Management instance. Keep these considerations in mind:

• The content type of the secret must be application/x-pkcs12. Learn more about custom domain certificate requirements.
• Use the Key Vault certificate secret endpoint, which contains the secret.

The following example shows an Azure Resource Manager template that uses the system-assigned managed identity of an API Management service instance to retrieve a custom domain certificate from Key Vault.

Prerequisites

• An API Management service instance configured with a system-assigned managed identity. To create the instance, you can use an Azure Quickstart Template.
• An Azure Key Vault instance in the same resource group, hosting a certificate that will be used as a custom domain certificate in API Management.

The following template contains the following steps.

1. Update the access policies of the Azure Key Vault instance and allow the API Management instance to obtain secrets from it.
2. Update the API Management instance by setting a custom domain name through the certificate from the Key Vault instance.

When you run the template, provide parameter values appropriate for your environment.

{
	"$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
	"contentVersion": "1.0.0.0",
	"parameters": {
        "apiManagementServiceName": {
            "type": "string",
            "minLength": 8,
            "metadata":{
                "description": "The name of the API Management service"
            }
        },
		"publisherEmail": {
			"type": "string",
			"minLength": 1,
			"metadata": {
				"description": "The email address of the owner of the service"
			}
		},
		"publisherName": {
			"type": "string",
			"minLength": 1,
			"metadata": {
				"description": "The name of the owner of the service"
			}
		},
		"sku": {
			"type": "string",
			"allowedValues": ["Developer",
			"Standard",
			"Premium"],
			"defaultValue": "Developer",
			"metadata": {
				"description": "The pricing tier of this API Management service"
			}
		},
		"skuCount": {
			"type": "int",
			"defaultValue": 1,
			"metadata": {
				"description": "The instance size of this API Management service."
			}
		},
        "keyVaultName": {
            "type": "string",
            "metadata": {
                "description": "Name of the key vault"
            }
        },
		"proxyCustomHostname1": {
			"type": "string",
			"metadata": {
				"description": "Gateway custom hostname 1. Example: api.contoso.com"
			}
		},
		"keyVaultIdToCertificate": {
			"type": "string",
			"metadata": {
				"description": "Reference to the key vault certificate. Example: https://contoso.vault.azure.cn/secrets/contosogatewaycertificate"
			}
		}
	},
	 "variables": {
        "apimServiceIdentityResourceId": "[concat(resourceId('Microsoft.ApiManagement/service', parameters('apiManagementServiceName')),'/providers/Microsoft.ManagedIdentity/Identities/default')]"
		    },
	"resources": [ 
   {
        "apiVersion": "2021-08-01",
        "name": "[parameters('apiManagementServiceName')]",
        "type": "Microsoft.ApiManagement/service",
        "location": "[resourceGroup().location]",
        "tags": {
        },
        "sku": {
            "name": "[parameters('sku')]",
            "capacity": "[parameters('skuCount')]"
        },
        "properties": {
            "publisherEmail": "[parameters('publisherEmail')]",
            "publisherName": "[parameters('publisherName')]"
        },
        "identity": {
            "type": "systemAssigned"
        }
    },
    {
        "type": "Microsoft.KeyVault/vaults/accessPolicies",
        "name": "[concat(parameters('keyVaultName'), '/add')]",
        "apiVersion": "2018-02-14",
        "properties": {
            "accessPolicies": [{
                "tenantId": "[reference(variables('apimServiceIdentityResourceId'), '2018-11-30').tenantId]",
                "objectId": "[reference(variables('apimServiceIdentityResourceId'), '2018-11-30').principalId]",
                "permissions": {
                     "secrets": ["get", "list"]
                }
            }]
        }
    },
	{
        "apiVersion": "2021-04-01",
		"type": "Microsoft.Resources/deployments",
        "name": "apimWithKeyVault",
		 "dependsOn": [
        "[resourceId('Microsoft.ApiManagement/service', parameters('apiManagementServiceName'))]"
        ],
        "properties": {
            "mode": "incremental",
            "template": {
                "$schema": "http://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
				"contentVersion": "1.0.0.0",
				"parameters": {},			
				"resources": [{
					"apiVersion": "2021-08-01",
					"name": "[parameters('apiManagementServiceName')]",
					"type": "Microsoft.ApiManagement/service",
					"location": "[resourceGroup().location]",
					"tags": {
					},
					"sku": {
						"name": "[parameters('sku')]",
						"capacity": "[parameters('skuCount')]"
					},
					"properties": {
						"publisherEmail": "[parameters('publisherEmail')]",
						"publisherName": "[parameters('publisherName')]",
						"hostnameConfigurations": [{
							"type": "Proxy",
							"hostName": "[parameters('proxyCustomHostname1')]",
							"keyVaultId": "[parameters('keyVaultIdToCertificate')]"
						}]
					},
					"identity": {
						"type": "systemAssigned"
					}
				}]
		}
		}
	}
]
}

Store and manage named values from Azure Key Vault

You can use a system-assigned managed identity to access Azure Key Vault to store and manage secrets for use in API Management policies. For more information, see Use named values in Azure API Management policies.

Authenticate to a backend by using an API Management identity

You can use the system-assigned identity to authenticate to a backend service through the authentication-managed-identity policy.

Connect to Azure resources behind IP firewall using system-assigned managed identity

API Management is a trusted Microsoft service to the following resources. This allows the service to connect to the following resources behind a firewall. After you explicitly assign the appropriate Azure role to the system-assigned managed identity for that resource instance, the scope of access for the instance corresponds to the Azure role assigned to the managed identity.

Azure Service	Link
Azure Key Vault	Trusted-access-to-azure-key-vault
Azure Storage	Trusted-access-to-azure-storage
Azure Service Bus	Trusted-access-to-azure-service-bus
Azure Event Hubs	Trusted-access-to-azure-event-hub

Log events to an event hub

You can configure and use a system-assigned managed identity to access an event hub for logging events from an API Management instance. For more information, see How to log events to Azure Event Hubs in Azure API Management.

Create a user-assigned managed identity

Azure portal

To set up a managed identity in the portal, you'll first create an API Management instance and create a user-assigned identity. Then, enable the feature.

1. Create an API Management instance in the portal as you normally would. Browse to it in the portal.

2. In the left menu, under Security, select Managed identities.

3. On the User assigned tab, select Add.

4. Search for the identity that you created earlier and select it. Select Add.

   

Azure PowerShell

The following steps walk you through creating an API Management instance and assigning it an identity by using Azure PowerShell.

1. If needed, install the Azure PowerShell by using the instructions in the Azure PowerShell guide. Then run Connect-AzAccount to create a connection with Azure.

2. Use the following code to create the instance. For more examples of how to use Azure PowerShell with an API Management instance, see API Management PowerShell samples.

   # Create a resource group.
   New-AzResourceGroup -Name $resourceGroupName -Location $location
   
   # Create a user-assigned identity. This requires installation of the "Az.ManagedServiceIdentity" module.
   $userAssignedIdentity = New-AzUserAssignedIdentity -Name $userAssignedIdentityName -ResourceGroupName $resourceGroupName
   
   # Create an API Management Consumption Sku service.
   $userIdentities = @($userAssignedIdentity.Id)
   
   New-AzApiManagement -ResourceGroupName $resourceGroupName -Location $location -Name $apiManagementName -Organization contoso -AdminEmail admin@contoso.com -Sku Consumption -UserAssignedIdentity $userIdentities
   

You can also update an existing service to assign an identity to the service:

# Get an API Management instance
$apimService = Get-AzApiManagement -ResourceGroupName $resourceGroupName -Name $apiManagementName

# Create a user-assigned identity. This requires installation of the "Az.ManagedServiceIdentity" module.
$userAssignedIdentity = New-AzUserAssignedIdentity -Name $userAssignedIdentityName -ResourceGroupName $resourceGroupName

# Update an API Management instance
$userIdentities = @($userAssignedIdentity.Id)
Set-AzApiManagement -InputObject $apimService -UserAssignedIdentity $userIdentities

Azure Resource Manager template

You can create an API Management instance with an identity by including the following property in the resource definition:

"identity": {
    "type": "UserAssigned",
    "userAssignedIdentities": {
        "<RESOURCEID>": {}
    }
}

Adding the user-assigned type tells Azure to use the user-assigned identity specified for your instance.

For example, a complete Azure Resource Manager template might look like the following:

{
    "$schema": "https://schema.management.azure.com/schemas/2014-04-01-preview/deploymentTemplate.json#",
    "contentVersion": "0.9.0.0",
    "resources": [{
        "apiVersion": "2021-08-01",
        "name": "contoso",
        "type": "Microsoft.ApiManagement/service",
        "location": "[resourceGroup().location]",
        "tags": {},
        "sku": {
            "name": "Developer",
            "capacity": "1"
        },
        "properties": {
            "publisherEmail": "admin@contoso.com",
            "publisherName": "Contoso"
        },
        "identity": {
            "type": "UserAssigned",
             "userAssignedIdentities": {
                "[resourceId('Microsoft.ManagedIdentity/userAssignedIdentities', variables('identityName'))]": {}
             }
        },
         "dependsOn": [
          "[resourceId('Microsoft.ManagedIdentity/userAssignedIdentities', variables('identityName'))]"
        ]
    }]
}

When the service is created, it has the following additional properties:

"identity": {
    "type": "UserAssigned",
    "userAssignedIdentities": {
        "<RESOURCEID>": {
            "principalId": "<PRINCIPALID>",
            "clientId": "<CLIENTID>"
        }
    }
}

The principalId property is a unique identifier for the identity that's used for Microsoft Entra administration. The clientId property is a unique identifier for the application's new identity that's used for specifying which identity to use during runtime calls.

Supported scenarios using user-assigned managed identity

Obtain a custom TLS/SSL certificate for the API Management instance from Azure Key Vault

You can use a user-assigned identity to establish trust between an API Management instance and Azure Key Vault. This trust can then be used to retrieve custom TLS/SSL certificates stored in Azure Key Vault. You can then assign these certificates to custom domains in the API Management instance.

Keep these considerations in mind:

• The content type of the secret must be application/x-pkcs12.
• Use the Key Vault certificate secret endpoint, which contains the secret.

Store and manage named values from Azure Key Vault

You can use a user-assigned managed identity to access Azure Key Vault to store and manage secrets for use in API Management policies. For more information, see Use named values in Azure API Management policies.

Authenticate to a backend by using a user-assigned identity

You can use the user-assigned identity to authenticate to a backend service through the authentication-managed-identity policy.

Log events to an event hub

You can configure and use a user-assigned managed identity to access an event hub for logging events from an API Management instance. For more information, see How to log events to Azure Event Hubs in Azure API Management.

Remove an identity

You can remove a system-assigned identity by disabling the feature through the portal or the Azure Resource Manager template in the same way that it was created. User-assigned identities can be removed individually. To remove all identities, set the identity type to "None".

Removing a system-assigned identity in this way will also delete it from Microsoft Entra ID. System-assigned identities are also automatically removed from Microsoft Entra ID when the API Management instance is deleted.

To remove all identities by using the Azure Resource Manager template, update this section:

"identity": {
    "type": "None"
}

Next steps

Learn more about managed identities for Azure resources:

• What are managed identities for Azure resources?
• Azure Resource Manager templates
• Authenticate with a managed identity in a policy