Använda hanterade identiteter i Azure API Management

GÄLLER FÖR: Alla API Management-nivåer

Den här artikeln visar hur du skapar en hanterad identitet för en Azure API Management-instans och hur du använder den för att komma åt andra resurser. Med en hanterad identitet som genereras av Microsoft Entra ID kan API Management enkelt och säkert komma åt andra resurser som skyddas av Microsoft Entra, till exempel Azure Key Vault. Azure hanterar dessa identiteter, så du behöver inte etablera eller rotera några hemligheter. Mer information om hanterade identiteter finns i Vad är hanterade identiteter för Azure-resurser?.

Du kan bevilja två typer av identiteter till en API Management-instans:

• En systemtilldelad identitet är kopplad till din tjänst och tas bort om tjänsten tas bort. Tjänsten kan bara ha en systemtilldelad identitet.
• En användartilldelad identitet är en fristående Azure-resurs som kan tilldelas till din tjänst. Tjänsten kan ha flera användartilldelade identiteter.

Skapa en systemtilldelad hanterad identitet

Azure Portal

Om du vill konfigurera en hanterad identitet i Azure-portalen skapar du en API Management-instans och aktiverar sedan funktionen.

1. Skapa en API Management-instans i portalen som vanligt. Gå till den i portalen.

2. I den vänstra menyn under Säkerhet väljer du Hanterade identiteter.

3. På fliken Systemtilldelat ändrar du Status till På. Välj Spara.

   

Azure PowerShell

Följande steg leder dig genom att skapa en API Management-instans och tilldela den en identitet med hjälp av Azure PowerShell.

1. Om du behöver det installerar du Azure PowerShell genom att följa anvisningarna i Azure PowerShell-guiden. Kör Connect-AzAccount sedan för att skapa en anslutning till Azure.

2. Använd följande kod för att skapa en instans med en systemtilldelad hanterad identitet. Fler exempel på hur du använder Azure PowerShell med API Management finns i API Management PowerShell-exempel.

   # 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
   

Du kan också uppdatera en befintlig instans för att skapa identiteten:

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

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

Mall för Azure Resource Manager (ARM)

Du kan skapa en API Management-instans med en systemtilldelad identitet genom att inkludera följande egenskap i resursdefinitionen för ARM-mallen:

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

Den här egenskapen instruerar Azure att skapa och hantera identiteten för din API Management-instans.

En fullständig ARM-mall kan till exempel se ut så här:

{
    "$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"
        }
    }]
}

När instansen skapas har den följande ytterligare egenskaper:

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

Egenskapen tenantId identifierar vilken Microsoft Entra-klient som identiteten tillhör. Egenskapen principalId är en unik identifierare för instansens nya identitet. I Microsoft Entra-ID:t har tjänstens huvudnamn samma namn som du gav till DIN API Management-instans.

Konfigurera Key Vault-åtkomst med hjälp av en hanterad identitet

Följande konfigurationer krävs om du vill använda API Management för att komma åt certifikat från ett Azure-nyckelvalv.

Konfigurera åtkomst till nyckelvalv

1. Gå till ditt nyckelvalv i portalen.
2. I den vänstra menyn väljer du Inställningar>Åtkomstkonfiguration. Observera den behörighetsmodell som har konfigurerats.
3. Beroende på behörighetsmodellen konfigurerar du antingen en åtkomstprincip för nyckelvalvet eller Azure RBAC-åtkomst för en hanterad API Management-identitet.

Så här lägger du till en åtkomstprincip för key vault:

1. I den vänstra menyn väljer du Åtkomstprinciper.
2. På sidan Åtkomstprinciper väljer du + Skapa.
3. På fliken Behörigheter går du till Hemliga behörigheter, väljer Hämta och Lista och väljer sedan Nästa.
4. På fliken Huvudnamn söker du efter resursnamnet för din hanterade identitet och väljer sedan Nästa. Om du använder en systemtilldelad identitet är huvudnamnet för din API Management-instans.
5. Välj Nästa igen. På fliken Granska + skapa väljer du Skapa.

Så här konfigurerar du Azure RBAC-åtkomst:

1. Välj Åtkomstkontroll (IAM) i den vänstra menyn.
2. På sidan Åtkomstkontroll (IAM) väljer du Lägg till rolltilldelning.
3. På fliken Roll väljer du Nyckelvalvscertifikatanvändare.
4. På fliken Medlemmar väljer du Hanterad identitet>+ Välj medlemmar.
5. I fönstret Välj hanterade identiteter väljer du den systemtilldelade hanterade identiteten eller en användartilldelad hanterad identitet som är associerad med din API Management-instans och klickar sedan på Välj.
6. Välj Granska + tilldela.

Krav för Key Vault-brandvägg

Om Key Vault-brandväggen är aktiverad i nyckelvalvet måste du uppfylla följande krav:

• Du måste använda API Management-instansens systemtilldelade hanterade identitet för att få åtkomst till nyckelvalvet.

• I Key Vault-brandväggen aktiverar du alternativet Tillåt betrodda Microsoft-tjänster att kringgå den här brandväggen .

• Se till att din lokala klient-IP-adress tillåts komma åt nyckelvalvet tillfälligt medan du väljer ett certifikat eller en hemlighet som ska läggas till i Azure API Management. Mer information finns i Konfigurera nätverksinställningar för Azure Key Vault.

  När du har slutfört konfigurationen kan du blockera din klientadress i nyckelvalvsbrandväggen.

Krav för virtuella nätverk

Om API Management-instansen distribueras i ett virtuellt nätverk konfigurerar du även följande nätverksinställningar:

• Aktivera en tjänstslutpunkt till Key Vault i API Management-undernätet.
• Konfigurera en NSG-regel (network security group) för att tillåta utgående trafik till tjänsttaggar för AzureKeyVault och AzureActiveDirectory.

Mer information finns i Nätverkskonfiguration när du konfigurerar API Management i ett virtuellt nätverk.

Scenarier som stöds och som använder systemtilldelad identitet

Följande är några vanliga scenarier för att använda en systemtilldelad hanterad identitet i Azure API Management.

Hämta ett anpassat TLS/SSL-certifikat för API Management-instansen från Key Vault

Du kan använda den systemtilldelade identiteten för en API Management-instans för att hämta anpassade TLS/SSL-certifikat som lagras i Key Vault. Du kan sedan tilldela dessa certifikat till anpassade domäner i API Management-instansen. Ta hänsyn till följande:

• Hemlighetens innehållstyp måste vara application/x-pkcs12. Mer information finns i Alternativ för domäncertifikat.
• Du måste använda slutpunkten för Key Vault-certifikatets hemlighet, som innehåller hemligheten.

I följande exempel visas en ARM-mall som använder den systemtilldelade hanterade identiteten för en API Management-instans för att hämta ett anpassat domäncertifikat från Key Vault.

Förutsättningar

• En API Management-instans som har konfigurerats med en systemtilldelad hanterad identitet. Om du vill skapa instansen kan du använda en Azure-snabbstartsmall.
• En Key Vault-instans i samma resursgrupp. Instansen måste vara värd för ett certifikat som ska användas som ett anpassat domäncertifikat i API Management.

Mallen innehåller följande steg.

1. Uppdatera åtkomstprinciperna för Key Vault-instansen och gör det möjligt för API Management-instansen att hämta hemligheter från den.
2. Uppdatera API Management-instansen genom att ange ett anpassat domännamn via certifikatet från Key Vault-instansen.

När du kör mallen anger du parametervärden som är lämpliga för din miljö.

{
	"$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 instance"
            }
        },
		"publisherEmail": {
			"type": "string",
			"minLength": 1,
			"metadata": {
				"description": "The email address of the owner of the instance"
			}
		},
		"publisherName": {
			"type": "string",
			"minLength": 1,
			"metadata": {
				"description": "The name of the owner of the instance"
			}
		},
		"sku": {
			"type": "string",
			"allowedValues": ["Developer",
			"Standard",
			"Premium"],
			"defaultValue": "Developer",
			"metadata": {
				"description": "The pricing tier of the API Management instance"
			}
		},
		"skuCount": {
			"type": "int",
			"defaultValue": 1,
			"metadata": {
				"description": "The instance size of the API Management instance"
			}
		},
        "keyVaultName": {
            "type": "string",
            "metadata": {
                "description": "The 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"
					}
				}]
		}
		}
	}
]
}

Lagra och hantera namngivna värden från Key Vault

Du kan använda en systemtilldelad hanterad identitet för att få åtkomst till Key Vault för att lagra och hantera hemligheter för användning i API Management-principer. Mer information finns i Använda namngivna värden i Azure API Management-principer.

Autentisera mot en backend med hjälp av en API Management-identitet

Du kan använda den systemtilldelade identiteten för att autentisera dig mot en backendtjänst via principen authentication-managed-identity.

Ansluta till Azure-resurser bakom en IP-brandvägg med hjälp av en systemtilldelad hanterad identitet

API Management är en betrodd Microsoft-tjänst för följande resurser. Med den här betrodda statusen kan tjänsten ansluta till följande resurser bakom en brandvägg. När du uttryckligen har tilldelat lämplig Azure-roll till den systemtilldelade hanterade identiteten för en resursinstans motsvarar åtkomstomfånget för instansen den Azure-roll som har tilldelats till den hanterade identiteten.

• Betrodd åtkomst för Key Vault
• Betrodd åtkomst för Azure Storage
• Betrodd åtkomst för Azure Services Bus
• Betrodd åtkomst för Azure Event Hubs

Logga händelser till en händelsehubb

Du kan konfigurera och använda en systemtilldelad hanterad identitet för att komma åt en händelsehubb för att logga händelser från en API Management-instans. Mer information finns i Logga händelser till Event Hubs i Azure API Management.

Skapa en användartilldelad hanterad identitet

Azure Portal

Om du vill konfigurera en hanterad identitet i portalen måste du först skapa en API Management-instans och skapa en användartilldelad identitet. Slutför sedan följande steg.

1. Gå till din API Management-instans i portalen.

2. I den vänstra menyn under Säkerhet väljer du Hanterade identiteter.

3. På fliken Användartilldelade väljer du Lägg till.

4. Sök efter den identitet som du skapade tidigare och välj den. Markera Lägga till.

   

Azure PowerShell

Följande steg leder dig genom att skapa en API Management-instans och tilldela den en identitet med hjälp av Azure PowerShell.

1. Om du behöver det installerar du Azure PowerShell genom att följa anvisningarna i Azure PowerShell-guiden. Kör Connect-AzAccount sedan för att skapa en anslutning till Azure.

2. Använd följande kod för att skapa instansen. Fler exempel på hur du använder Azure PowerShell med API Management finns i API Management PowerShell-exempel.

   # Create a resource group.
   New-AzResourceGroup -Name $resourceGroupName -Location $location
   
   # Create a user-assigned identity. This code 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
   

Du kan också uppdatera en befintlig tjänst för att tilldela en identitet till tjänsten:

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

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

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

ARM-mall

Du kan skapa en API Management-instans som har en identitet genom att inkludera följande egenskap i resursdefinitionen:

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

Om du lägger till den användartilldelade typen uppmanas Azure att använda den användartilldelade identitet som har angetts för din instans.

En fullständig ARM-mall kan till exempel se ut så här:

{
    "$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'))]"
        ]
    }]
}

När tjänsten skapas har den följande ytterligare egenskaper:

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

Egenskapen principalId är en unik identifierare för den identitet som används för Microsoft Entra-administration. Egenskapen clientId är en unik identifierare för programmets nya identitet som används för att ange vilken identitet som ska användas under körningsanrop.

Scenarier som stöds som använder användartilldelade hanterade identiteter

Följande är några vanliga scenarier för att använda en användartilldelad hanterad identitet i Azure API Management.

Hämta ett anpassat TLS/SSL-certifikat för API Management-instansen från Key Vault

Du kan använda en användartilldelad identitet för att upprätta förtroende mellan en API Management-instans och Key Vault. Det här förtroendet kan sedan användas för att hämta anpassade TLS/SSL-certifikat som lagras i Key Vault. Du kan sedan tilldela dessa certifikat till anpassade domäner i API Management-instansen.

Ta hänsyn till följande:

• Hemlighetens innehållstyp måste vara application/x-pkcs12.
• Du måste använda slutpunkten för Key Vault-certifikatets hemlighet, som innehåller hemligheten.

Lagra och hantera namngivna värden från Key Vault

Du kan använda en användartilldelad hanterad identitet för att få åtkomst till Key Vault för att lagra och hantera hemligheter för användning i API Management-principer. Mer information finns i Använda namngivna värden i Azure API Management-principer.

Autentisera mot en bakände med hjälp av en användartilldelad identitet

Du kan använda den användartilldelade identiteten för att autentisera mot en backend-tjänst via den autentiseringshanterade identitetsprincipen authentication-managed-identity.

Logga händelser till en händelsehubb

Du kan konfigurera och använda en användartilldelad hanterad identitet för att komma åt en händelsehubb för att logga händelser från en API Management-instans. Mer information finns i Så här loggar du händelser till Azure Event Hubs i Azure API Management.

Ta bort en identitet

Du kan ta bort en systemtilldelad identitet genom att inaktivera funktionen via portalen eller en ARM-mall på samma sätt som den skapades. Användartilldelade identiteter kan tas bort individuellt. Om du vill ta bort alla identiteter anger du identitetstypen till "None".

Om du tar bort en systemtilldelad identitet på det här sättet tas den också bort från Microsoft Entra-ID. Systemtilldelade identiteter tas också bort automatiskt från Microsoft Entra-ID när API Management-instansen tas bort.

Om du vill ta bort alla identiteter med hjälp av en ARM-mall uppdaterar du det här avsnittet:

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

Relaterat innehåll

• Vad är hanterade identiteter för Azure-resurser?
• Azure Resource Manager-mallar
• Autentisera med en hanterad identitet i en policy