Use managed identities in Azure API Management

This article shows you how to create a managed identity for an Azure API Management instance and how to access other resources. A managed identity generated by Azure Active Directory (Azure AD) allows your API Management instance to easily and securely access other Azure AD-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. Select Managed identities.

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

    Selections for enabling a system-assigned managed identity

Azure PowerShell

Note

This article has been updated to use the new Azure PowerShell Az module. You can still use the AzureRM module, which will continue to receive bug fixes until at least December 2020. To learn more about the new Az module and AzureRM compatibility, see Introducing the new Azure PowerShell Az module. For Az module installation instructions, see Install 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. 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
    
  3. 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 an 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/2014-04-01-preview/deploymentTemplate.json#",
	"contentVersion": "0.9.0.0",
	"resources": [{
		"apiVersion": "2019-01-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 what Azure AD tenant the identity belongs to. The principalId property is a unique identifier for the instance's new identity. Within Azure AD, 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.

Supported scenarios

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.
  • 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 contains the following steps:

  1. Create an API Management instance with a managed identity.
  2. Update the access policies of an Azure Key Vault instance and allow the API Management instance to obtain secrets from it.
  3. Update the API Management instance by setting a custom domain name through a certificate from the Key Vault instance.
{
	"$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
	"contentVersion": "1.0.0.0",
	"parameters": {
		"publisherEmail": {
			"type": "string",
			"minLength": 1,
			"metadata": {
				"description": "The email address of the owner of the service"
			}
		},
		"publisherName": {
			"type": "string",
			"defaultValue": "Contoso",
			"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 instance"
			}
		},
		"skuCount": {
			"type": "int",
			"defaultValue": 1,
			"metadata": {
				"description": "The instance size of this API Management instance."
			}
		},
		"keyVaultName": {
			"type": "string",
			"metadata": {
				"description": "Name of the vault"
			}
		},
		"proxyCustomHostname1": {
			"type": "string",
			"metadata": {
				"description": "Proxy Custom hostname."
			}
		},
		"keyVaultIdToCertificate": {
			"type": "string",
			"metadata": {
				"description": "Reference to the Key Vault certificate. https://contoso.vault.azure.net/secrets/contosogatewaycertificate."
			}
		}
	},
	"variables": {
		"apiManagementServiceName": "[concat('apiservice', uniqueString(resourceGroup().id))]",
		"apimServiceIdentityResourceId": "[concat(resourceId('Microsoft.ApiManagement/service', variables('apiManagementServiceName')),'/providers/Microsoft.ManagedIdentity/Identities/default')]"
	},
	"resources": [{
		"apiVersion": "2019-01-01",
		"name": "[variables('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": "2015-06-01",
		"dependsOn": [
			"[resourceId('Microsoft.ApiManagement/service', variables('apiManagementServiceName'))]"
		],
		"properties": {
			"accessPolicies": [{
				"tenantId": "[reference(variables('apimServiceIdentityResourceId'), '2015-08-31-PREVIEW').tenantId]",
				"objectId": "[reference(variables('apimServiceIdentityResourceId'), '2015-08-31-PREVIEW').principalId]",
				"permissions": {
					"secrets": ["get"]
				}
			}]
		}
	},
	{
		"apiVersion": "2017-05-10",
		"name": "apimWithKeyVault",
		"type": "Microsoft.Resources/deployments",
		"dependsOn": [
		"[resourceId('Microsoft.ApiManagement/service', variables('apiManagementServiceName'))]"
		],
		"properties": {
			"mode": "incremental",
			"templateLink": {
				"uri": "https://raw.githubusercontent.com/solankisamir/arm-templates/master/basicapim.keyvault.json",
				"contentVersion": "1.0.0.0"
			},
			"parameters": {
				"publisherEmail": { "value": "[parameters('publisherEmail')]"},
				"publisherName": { "value": "[parameters('publisherName')]"},
				"sku": { "value": "[parameters('sku')]"},
				"skuCount": { "value": "[parameters('skuCount')]"},
				"proxyCustomHostname1": {"value" : "[parameters('proxyCustomHostname1')]"},
				"keyVaultIdToCertificate": {"value" : "[parameters('keyVaultIdToCertificate')]"}
			}
		}
	}]
}

Authenticate to the back end by using an API Management identity

You can use the system-assigned identity to authenticate to the back end through the authentication-managed-identity policy.

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 then enable the feature.

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

  2. 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.

    Selections for enabling a user-assigned managed identity

Azure PowerShell

Note

This article has been updated to use the new Azure PowerShell Az module. You can still use the AzureRM module, which will continue to receive bug fixes until at least December 2020. To learn more about the new Az module and AzureRM compatibility, see Introducing the new Azure PowerShell Az module. For Az module installation instructions, see Install 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
    
  3. 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": "2019-12-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 Azure AD 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

Authenticate to the back end by using a user-assigned identity

You can use the user-assigned identity to authenticate to the back end through the authentication-managed-identity policy.

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 Azure AD. System-assigned identities are also automatically removed from Azure AD 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: