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.
Note
Managed identities are specific to the Microsoft Entra tenant where your Azure subscription is hosted. They don't get updated if a subscription is moved to a different directory. If a subscription is moved, you'll need to recreate and configure the identities.
Note
Currently, this feature isn't available in workspaces.
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.
Create an API Management instance in the portal as you normally would. Browse to it in the portal.
In the left menu, under Security, select Managed identities.
On the System assigned tab, switch Status to On. Select Save.
Azure PowerShell
Note
We recommend that you use the Azure Az PowerShell module to interact with Azure. To get started, see Install Azure PowerShell. To learn how to migrate to the Az PowerShell module, see Migrate Azure PowerShell from AzureRM to Az.
The following steps walk you through creating an API Management instance and assigning it an identity by using Azure PowerShell.
If needed, install Azure PowerShell by using the instructions in the Azure PowerShell guide. Then run
Connect-AzAccountto create a connection with Azure.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.
Note
An API Management instance can have both system-assigned and user-assigned identities at the same time. In this case, the type property would be SystemAssigned,UserAssigned.
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
In the portal, navigate to your key vault.
In the left menu, select Access configuration, and note the Permission model that is configured.
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:
- In the left menu, select Access policies.
- On the Access policies page,select + Create.
- On the Permissions tab, under Secret permissions, select Get and List, then select Next.
- 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.
- Select Next again. On the Review + create tab, select Create.
To configure Azure RBAC access:
- In the left menu, select Access control (IAM).
- On the Access control (IAM) page, select Add role assignment.
- On the Role tab, select Key Vault Certificate User.
- On the Members tab, select Managed identity > + Select members.
- 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.
- 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.
Important
If you don't provide the object version of the certificate, API Management will automatically obtain the newer version of the certificate within four hours after it's updated in Key Vault.
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.
- Update the access policies of the Azure Key Vault instance and allow the API Management instance to obtain secrets from it.
- 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.net/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
Note
You can associate an API Management instance with up to 10 user-assigned managed identities.
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.
Create an API Management instance in the portal as you normally would. Browse to it in the portal.
In the left menu, under Security, select Managed identities.
On the User assigned tab, select Add.
Search for the identity that you created earlier and select it. Select Add.
Azure PowerShell
Note
We recommend that you use the Azure Az PowerShell module to interact with Azure. To get started, see Install Azure PowerShell. To learn how to migrate to the Az PowerShell module, see Migrate Azure PowerShell from AzureRM to Az.
The following steps walk you through creating an API Management instance and assigning it an identity by using Azure PowerShell.
If needed, install the Azure PowerShell by using the instructions in the Azure PowerShell guide. Then run
Connect-AzAccountto create a connection with Azure.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.
Note
An API Management instance can have both system-assigned and user-assigned identities at the same time. In this case, the type property would be SystemAssigned,UserAssigned.
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.
Important
If Key Vault firewall is enabled on your key vault, you can't use a user-assigned identity for access from API Management. You can use the system-assigned identity instead. In Key Vault firewall, the Allow Trusted Microsoft Services to bypass this firewall option must also be enabled.
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.
Important
If you don't provide the object version of the certificate, API Management will automatically obtain the newer version of the certificate within four hours after it's updated in Key Vault.
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.
Note
If Key Vault firewall is enabled on your key vault, you can't use a user-assigned identity for access from API Management. You can use the system-assigned identity instead. In Key Vault firewall, the Allow Trusted Microsoft Services to bypass this firewall option must also be enabled.
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"
}
Important
If an API Management instance is configured with a custom SSL certificate from Key Vault and you try to disable a managed identity, the request will fail.
You can unblock yourself by switching from an Azure Key Vault certificate to an inline encoded certificate, and then disabling the managed identity. For more information, see Configure a custom domain name.
Next steps
Learn more about managed identities for Azure resources: