Använda hanterade identiteter i Azure API Management

Artikel
10/18/2023

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 din API Management-instans enkelt och säkert komma åt andra Microsoft Entra-skyddade resurser, till exempel Azure Key Vault. Azure hanterar den här identiteten, 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.

Kommentar

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

Skapa en systemtilldelad hanterad identitet

Azure Portal

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

Skapa en API Management-instans i portalen som vanligt. Bläddra till den i portalen.
I den vänstra menyn under Säkerhet väljer du Hanterade identiteter.
På fliken Systemtilldelat växlar du Status till På. Välj Spara.

Azure PowerShell

Kommentar

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 beskriver hur du skapar en API Management-instans och tilldelar den en identitet med hjälp av Azure PowerShell.

Om det behövs installerar du Azure PowerShell med hjälp av anvisningarna i Azure PowerShell-guiden. Kör Connect-AzAccount sedan för att skapa en anslutning till Azure.

Använd följande kod för att skapa instansen med en systemtilldelad hanterad identitet. Fler exempel på hur du använder Azure PowerShell med en API Management-instans 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

Azure Resource Manager-mall

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

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

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

En fullständig Azure Resource Manager-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.

Kommentar

En API Management-instans kan ha både systemtilldelade och användartilldelade identiteter samtidigt. I det här fallet skulle egenskapen type vara SystemAssigned,UserAssigned.

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

Följande konfigurationer krävs för att API Management ska få åtkomst till hemligheter och certifikat från ett Azure-nyckelvalv.

Konfigurera åtkomst till nyckelvalv

I portalen navigerar du till ditt nyckelvalv.
I den vänstra menyn väljer du Åtkomstkonfiguration och noterar 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:
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 väljer du huvudnamn, söker 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 Nyckelvalvshemlighetsanvändare.
4. På fliken Medlemmar väljer du Hanterad identitet>+ Välj medlemmar.
5. På sidan Välj hanterad identitet väljer du den systemtilldelade hanterade identiteten eller en användartilldelad hanterad identitet som är associerad med din API Management-instans och väljer sedan Välj.
6. Välj Granska + tilldela.

Krav för Key Vault-brandvägg

Om Key Vault-brandväggen är aktiverad i nyckelvalvet är följande ytterligare 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 klientadressen 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 Azure 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 Azure API Management i ett virtuellt nätverk.

Scenarier som stöds med systemtilldelad identitet

Hämta ett anpassat TLS/SSL-certifikat för API Management-instansen från Azure 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 Azure Key Vault. Du kan sedan tilldela dessa certifikat till anpassade domäner i API Management-instansen. Tänk på följande:

Hemlighetens innehållstyp måste vara application/x-pkcs12. Läs mer om krav för anpassade domäncertifikat.
Använd key vault-certifikatets hemliga slutpunkt, som innehåller hemligheten.

Viktigt!

Om du inte anger objektversionen av certifikatet hämtar API Management automatiskt den nyare versionen av certifikatet inom fyra timmar efter att det har uppdaterats i Key Vault.

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

Förutsättningar

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

Följande mall innehåller följande steg.

Uppdatera åtkomstprinciperna för Azure Key Vault-instansen och låt API Management-instansen 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 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"
					}
				}]
		}
		}
	}
]
}

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

Du kan använda en systemtilldelad hanterad identitet för att få åtkomst till Azure 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 till en serverdel med hjälp av en API Management-identitet

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

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

API Management är en betrodd Microsoft-tjänst för följande resurser. På så sätt 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 den resursinstansen motsvarar åtkomstomfånget för instansen den Azure-roll som tilldelats den hanterade identiteten.

Azure-tjänst	Länk
Azure Key Vault	Betrodd åtkomst till azure-key-vault
Azure Storage	Betrodd åtkomst till azure-storage
Azure Service Bus	Betrodd åtkomst till azure-service-bus
Azure Event Hubs	Betrodd åtkomst till azure-event-hub

Logga händelser till en händelsehubb

Du kan konfigurera och använda en systemtilldelad hanterad identitet för att få åtkomst till en händelsehubb för loggning av 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.

Skapa en användartilldelad hanterad identitet

Kommentar

Du kan associera en API Management-instans med upp till 10 användartilldelade hanterade identiteter.

Azure Portal

Om du vill konfigurera en hanterad identitet i portalen skapar du först en API Management-instans och skapar en användartilldelad identitet. Aktivera sedan funktionen.

Skapa en API Management-instans i portalen som vanligt. Bläddra till den 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

Kommentar

Följande steg beskriver hur du skapar en API Management-instans och tilldelar den en identitet med hjälp av Azure PowerShell.

Om det behövs installerar du Azure PowerShell med hjälp av anvisningarna i Azure PowerShell-guiden. Kör Connect-AzAccount sedan 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 en API Management-instans finns i API Management PowerShell-exempel.

# 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

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 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-mall

Du kan skapa en API Management-instans med 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 angetts för din instans.

En fullständig Azure Resource Manager-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.

Kommentar

En API Management-instans kan ha både systemtilldelade och användartilldelade identiteter samtidigt. I det här fallet skulle egenskapen type vara SystemAssigned,UserAssigned.

Scenarier som stöds med användartilldelad hanterad identitet

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

Du kan använda en användartilldelad identitet för att upprätta förtroende mellan en API Management-instans och Azure Key Vault. Det här förtroendet kan sedan användas för att hämta anpassade TLS/SSL-certifikat som lagras i Azure 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. I Key Vault-brandväggen måste alternativet Tillåt betrodda Microsoft-tjänster att kringgå den här brandväggen också vara aktiverat.

Tänk på följande:

Hemlighetens innehållstyp måste vara application/x-pkcs12.
Använd key vault-certifikatets hemliga slutpunkt, som innehåller hemligheten.

Viktigt!

Om du inte anger objektversionen av certifikatet hämtar API Management automatiskt den nyare versionen av certifikatet inom fyra timmar efter att det har uppdaterats i Key Vault.

Den fullständiga mallen finns i API Management with Key Vault based SSL using User Assigned Identity (API Management med Key Vault-baserad SSL med användartilldelad identitet).

I den här mallen distribuerar du:

Azure API Management-instans
Användartilldelad hanterad identitet i Azure
Azure Key Vault för lagring av SSL/TLS-certifikatet

Om du vill köra distributionen automatiskt väljer du följande knapp:

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

Du kan använda en användartilldelad hanterad identitet för att få åtkomst till Azure 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.

Kommentar

Autentisera till en serverdel med hjälp av en användartilldelad identitet

Du kan använda den användartilldelade identiteten för att autentisera till en serverdelstjänst via principen 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 loggning av 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 Azure Resource Manager-mallen 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 Azure Resource Manager-mallen 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 avblockera dig själv genom att växla från ett Azure Key Vault-certifikat till ett infogat kodat certifikat och sedan inaktivera den hanterade identiteten. Mer information finns i Konfigurera ett anpassat domännamn.

Nästa steg

Läs mer om hanterade identiteter för Azure-resurser:

Använda hanterade identiteter i Azure API Management

Skapa en systemtilldelad hanterad identitet

Azure Portal

Azure PowerShell

Azure Resource Manager-mall

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

Konfigurera åtkomst till nyckelvalv

Krav för Key Vault-brandvägg

Krav för virtuella nätverk

Scenarier som stöds med systemtilldelad identitet

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

Förutsättningar

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

Autentisera till en serverdel med hjälp av en API Management-identitet

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

Logga händelser till en händelsehubb

Skapa en användartilldelad hanterad identitet

Azure Portal

Azure PowerShell

Azure Resource Manager-mall

Scenarier som stöds med användartilldelad hanterad identitet

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

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

Autentisera till en serverdel med hjälp av en användartilldelad identitet

Logga händelser till en händelsehubb

Ta bort en identitet

Nästa steg

Ytterligare resurser