Not
Åtkomst till den här sidan kräver auktorisering. Du kan prova att logga in eller ändra kataloger.
Åtkomst till den här sidan kräver auktorisering. Du kan prova att ändra kataloger.
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.
Anteckning
Hanterade identiteter är specifika för den Microsoft Entra-klientorganisation där din Azure-prenumeration finns. De uppdateras inte om en prenumeration flyttas till en annan katalog. Om en prenumeration flyttas måste du återskapa och konfigurera om identiteterna.
Anteckning
För närvarande är den här funktionen inte tillgänglig på arbetsytor.
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.
Skapa en API Management-instans i portalen som vanligt. Gå till den i portalen.
I den vänstra menyn under Säkerhet väljer du Hanterade identiteter.
På fliken Systemtilldelat ändrar du Status till På. Välj Spara.
Azure PowerShell
Anteckning
Vi rekommenderar att du använder Azure Az PowerShell-modulen för att interagera med Azure. Se Installera Azure PowerShell för att komma igång. Information om hur du migrerar till Az PowerShell-modulen finns i artikeln om att migrera Azure PowerShell från AzureRM till Az.
Följande steg leder dig genom att skapa en API Management-instans och tilldela den en identitet med hjälp av Azure PowerShell.
Om du behöver det installerar du Azure PowerShell genom att följa anvisningarna i Azure PowerShell-guiden. Kör
Connect-AzAccountsedan för att skapa en anslutning till Azure.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.
Anteckning
En API Management-instans kan ha både systemtilldelade och användartilldelade identiteter. I det scenariot är type-egenskapen SystemAssigned,UserAssigned.
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
- Gå till ditt nyckelvalv i portalen.
- I den vänstra menyn väljer du Inställningar>Åtkomstkonfiguration. Observera den behörighetsmodell som har konfigurerats.
- 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:
- I den vänstra menyn väljer du Åtkomstprinciper.
- På sidan Åtkomstprinciper väljer du + Skapa.
- På fliken Behörigheter går du till Hemliga behörigheter, väljer Hämta och Lista och väljer sedan Nästa.
- 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.
- Välj Nästa igen. På fliken Granska + skapa väljer du Skapa.
Så här konfigurerar du Azure RBAC-åtkomst:
- Välj Åtkomstkontroll (IAM) i den vänstra menyn.
- På sidan Åtkomstkontroll (IAM) väljer du Lägg till rolltilldelning.
- På fliken Roll väljer du Nyckelvalvscertifikatanvändare.
- På fliken Medlemmar väljer du Hanterad identitet>+ Välj medlemmar.
- 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.
- 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.
Se till att API Management-instansen har en nätverkslinje som är synlig för nyckelvalvet. Beroende på dina scenarier konfigurerar du något av följande alternativ för nätverksåtkomst i nyckelvalvet:
Tillåt offentlig åtkomst från alla nätverk.
Ange en nätverkssäkerhetsregel för att tillåta API Management-trafik baserat på IP-adressen eller den virtuella nätverksanslutningen.
Skydda trafik från API Management med Private Link-anslutning.
Använd en nätverkssäkerhetsperimeter för att skydda ditt nyckelvalv och tillåta trafik från API Management.
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.
Viktigt!
Från och med mars 2026 kommer stöd inte längre att finnas för betrodd tjänstanslutning till Azure Key Vault från API Management genom att aktivera inställningen Tillåt betrodda Microsoft-tjänster att förbigå denna brandväggsinställning för nyckelvalvet. Om du vill fortsätta använda Key Vault med API Management efter den här ändringen kontrollerar du att du väljer ett alternativ för nätverksåtkomst som stöds enligt beskrivningen ovan. Läs mer.
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.
Viktigt!
Om du inte anger objektversionen av certifikatet hämtar API Management automatiskt en nyare version av certifikatet inom fyra timmar efter att det har uppdaterats i Key Vault.
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.
- 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.
- 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
I vissa scenarier kan API Management kommunicera med resurser i följande tjänster med hjälp av en systemtilldelad hanterad identitet som konfigurerats med en lämplig rolltilldelning:
- Azure 密钥保管库
- Azure Storage
- Azure Service Bus (Azure-tjänstbuss)
- Azure Event Hubs
- Azure Container Registry (containerregistertjänst från Azure)
- Azure Managed HSM
För resurser i dessa tjänster som skyddas av en IP-brandvägg kontrollerar du att du har en nätverkslinje från API Management. Konfigurera något av följande alternativ för nätverksåtkomst på resursen:
Tillåt offentlig åtkomst från alla nätverk.
Ange en nätverkssäkerhetsregel för att tillåta API Management-trafik baserat på IP-adressen eller den virtuella nätverksanslutningen.
Skydda trafik från API Management med Private Link-anslutning.
Använd en nätverkssäkerhetsperimeter för att skydda resursen och tillåta trafik från API Management.
Viktigt!
Från och med mars 2026 stöds inte längre betrodd tjänstanslutning till Azure-tjänster från API Management genom att möjliggöra inställningen Tillåt betrodda Microsoft-tjänster att kringgå denna brandvägg. Om du vill fortsätta att komma åt dessa tjänster från API Management efter den här ändringen kontrollerar du att du väljer ett alternativ för nätverksåtkomst som stöds enligt beskrivningen ovan. Läs mer
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
Anteckning
Du kan associera en API Management-instans med så många som 10 användartilldelade hanterade identiteter.
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.
Gå till din API Management-instans i portalen.
I den vänstra menyn under Säkerhet väljer du Hanterade identiteter.
På fliken Användartilldelade väljer du Lägg till.
Sök efter den identitet som du skapade tidigare och välj den. Markera Lägga till.
Azure PowerShell
Anteckning
Vi rekommenderar att du använder Azure Az PowerShell-modulen för att interagera med Azure. Se Installera Azure PowerShell för att komma igång. Information om hur du migrerar till Az PowerShell-modulen finns i artikeln om att migrera Azure PowerShell från AzureRM till Az.
Följande steg leder dig genom att skapa en API Management-instans och tilldela den en identitet med hjälp av Azure PowerShell.
Om du behöver det installerar du Azure PowerShell genom att följa anvisningarna i Azure PowerShell-guiden. Kör
Connect-AzAccountsedan för att skapa en anslutning till Azure.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.
Anteckning
En API Management-instans kan ha både systemtilldelade och användartilldelade identiteter. I det scenariot skulle egenskapen type vara SystemAssigned,UserAssigned.
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.
Viktigt!
Om Key Vault-brandväggen är aktiverad i ditt nyckelvalv kan du inte använda en användartilldelad identitet för åtkomst från API Management. Du kan använda den systemtilldelade identiteten i stället. Mer information finns i avsnittet Krav för key vault-brandväggen.
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.
Viktigt!
Om du inte anger objektversionen av certifikatet hämtar API Management automatiskt en nyare version av certifikatet inom fyra timmar efter att det har uppdaterats i Key Vault.
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.
Anteckning
Om Key Vault-brandväggen är aktiverad i ditt nyckelvalv kan du inte använda en användartilldelad identitet för åtkomst från API Management. Du kan använda den systemtilldelade identiteten i stället. Mer information finns i avsnittet Krav för key vault-brandväggen.
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"
}
Viktigt!
Om en API Management-instans har konfigurerats med ett anpassat SSL-certifikat från Key Vault och du försöker inaktivera en hanterad identitet misslyckas begäran.
Du kan lösa detta genom att växla från ett Key Vault-certifikat till ett infogat kodat certifikat och sedan inaktivera den hanterade identiteten. Mer information finns i Konfigurera ett anpassat domännamn.