Beheerde identiteiten gebruiken in Azure API Management

VAN TOEPASSING OP: Alle API Management-niveaus

In dit artikel wordt beschreven hoe u een beheerde identiteit maakt voor een Azure API Management-exemplaar en hoe u deze kunt gebruiken voor toegang tot andere resources. Met een beheerde identiteit die door Microsoft Entra ID wordt gegenereerd, kan API Management eenvoudig en veilig toegang krijgen tot andere resources die worden beveiligd door Microsoft Entra, zoals Azure Key Vault. Azure beheert deze identiteiten, zodat u geen geheimen hoeft in te richten of te roteren. Zie Wat zijn beheerde identiteiten voor Azure-resources? voor meer informatie over beheerde identiteiten.

U kunt twee typen van identiteiten toekennen aan een API Management-exemplaar:

• Een door het systeem toegewezen identiteit is gekoppeld aan uw service en wordt verwijderd als uw service wordt verwijderd. De service kan slechts één door het systeem toegewezen identiteit hebben.
• Een door de gebruiker toegewezen identiteit is een autonome Azure-resource die kan worden toegewezen aan uw service. De service kan meerdere door de gebruiker toegewezen identiteiten hebben.

Een door het systeem toegewezen beheerde identiteit maken

Azure Portal

Als u een beheerde identiteit wilt instellen in Azure Portal, maakt u een API Management-exemplaar en schakelt u vervolgens de functie in.

1. Maak een API Management-exemplaar in de portal zoals u dat normaal zou doen. Ga naar de portal.

2. Selecteer beheerde identiteiten in het linkermenu onder Beveiliging.

3. Wijzig op het tabblad Systeem toegewezen de status in Aan. Selecteer Opslaan.

   

Azure PowerShell

De volgende stappen leiden u door het maken van een API Management-exemplaar en het toewijzen van een identiteit met behulp van Azure PowerShell.

1. Als dat nodig is, installeert u Azure PowerShell door de instructies in de Azure PowerShell-handleiding te volgen. Connect-AzAccount Voer vervolgens uit om een verbinding met Azure te maken.

2. Gebruik de volgende code om een exemplaar te maken met een door het systeem toegewezen beheerde identiteit. Zie voorbeelden van API Management PowerShell voor meer voorbeelden van het gebruik van Azure PowerShell met API Management.

   # 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
   

U kunt ook een bestaande instantie bijwerken om de identiteit te vormen.

# 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 (ARM)-sjabloon

U kunt een API Management-exemplaar maken met een door het systeem toegewezen identiteit door de volgende eigenschap op te geven in de resourcedefinitie van de ARM-sjabloon:

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

Met deze eigenschap wordt Azure geïnstrueerd om de identiteit voor uw API Management-exemplaar te maken en te beheren.

Een volledige ARM-sjabloon kan er bijvoorbeeld als volgt uitzien:

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

Wanneer het exemplaar wordt gemaakt, heeft het de volgende aanvullende eigenschappen:

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

De tenantId eigenschap identificeert tot welke Microsoft Entra-tenant de identiteit behoort. De principalId eigenschap is een unieke identificatie voor het nieuwe identiteitselement van het exemplaar. Binnen Microsoft Entra ID heeft de service-principal dezelfde naam die u aan uw API Management-exemplaar hebt gegeven.

Key Vault-toegang configureren met behulp van een beheerde identiteit

De volgende configuraties zijn vereist als u API Management wilt gebruiken voor toegang tot certificaten vanuit een Azure-sleutelkluis.

Toegang tot key vault configureren

1. Ga in de portal naar uw Key Vault.
2. Selecteer in het linkermenu De configuratie van Access. Let op het machtigingsmodel dat is geconfigureerd.
3. Afhankelijk van het machtigingsmodel configureert u ofwel een toegangsbeleid voor key vault of Azure RBAC-toegang voor een beheerde identiteit van API Management.

Om een toegangsbeleid voor een key vault toe te voegen:

1. Selecteer toegangsbeleid in het linkermenu.
2. Op de pagina Toegangsbeleid, selecteer + Maken.
3. Selecteer Op het tabblad Machtigingen onder Geheime machtigingen de optie Ophalen en weergeven en selecteer vervolgens Volgende.
4. Klik op het tabblad Principal, selecteer Principal, zoek naar de resourcenaam van uw beheerde identiteit en selecteer Vervolgens Volgende. Als u een door het systeem toegewezen identiteit gebruikt, is de principal de naam van uw API Management-exemplaar.
5. Selecteer Volgende opnieuw. Selecteer op het tabblad Beoordelen en maken de optie Maken.

Azure RBAC-toegang configureren:

1. Selecteer toegangsbeheer (IAM) in het linkermenu.
2. Selecteer Op de pagina Toegangsbeheer (IAM) de optie Roltoewijzing toevoegen.
3. Selecteer op het tabblad Rol de Key Vault Certificate User.
4. Op het tabblad Leden selecteer beheerde identiteit>+ Leden selecteren.
5. Selecteer in het venster Beheerde identiteiten selecteren de door het systeem toegewezen beheerde identiteit of een door de gebruiker toegewezen beheerde identiteit die is gekoppeld aan uw API Management-exemplaar en klik vervolgens op Selecteren.
6. Selecteer Controleren + toewijzen.

Vereisten voor Key Vault-firewall

Als Key Vault-firewall is ingeschakeld voor uw sleutelkluis, moet u aan deze vereisten voldoen:

• U moet de door het systeem toegewezen beheerde identiteit van het API Management-exemplaar gebruiken om toegang te krijgen tot de sleutelkluis.

• Schakel in de Key Vault-firewall de optie Vertrouwde Microsoft-services toestaan om deze firewall te omzeilen in.

• Zorg ervoor dat uw lokale client-IP-adres tijdelijk toegang heeft tot de sleutelkluis terwijl u een certificaat of geheim selecteert om toe te voegen aan Azure API Management. Zie Azure Key Vault-netwerkinstellingen configureren voor meer informatie.

  Nadat u de configuratie hebt voltooid, kunt u het clientadres blokkeren in de firewall van de sleutelkluis.

Vereisten voor het virtuele netwerk

Als het API Management-exemplaar wordt geïmplementeerd in een virtueel netwerk, configureert u ook de volgende netwerkinstellingen:

• Schakel een service-eindpunt in voor Key Vault in het API Management-subnet.
• Configureer een regel voor een netwerkbeveiligingsgroep (NSG) om uitgaand verkeer naar de servicetags van AzureKeyVault en AzureActiveDirectory toe te staan.

Zie De netwerkconfiguratie bij het instellen van API Management in een virtueel netwerk voor meer informatie.

Ondersteunde scenario's die gebruikmaken van door het systeem toegewezen identiteit

Hieronder volgen enkele veelvoorkomende scenario's voor het gebruik van een door het systeem toegewezen beheerde identiteit in Azure API Management.

Een aangepast TLS/SSL-certificaat verkrijgen voor het API Management-exemplaar vanuit Key Vault

U kunt de door het systeem toegewezen identiteit van een API Management-exemplaar gebruiken om aangepaste TLS/SSL-certificaten op te halen die zijn opgeslagen in Key Vault. U kunt deze certificaten vervolgens toewijzen aan aangepaste domeinen in het API Management-exemplaar. Neem rekening met deze overwegingen:

• Het inhoudstype van het geheim moet toepassing/x-pkcs12 zijn. Zie Opties voor domeincertificaten voor meer informatie.
• Je moet het certificaatgeheimeindpunt van de Key Vault gebruiken, dat het geheim bevat.

In het volgende voorbeeld ziet u een ARM-sjabloon die gebruikmaakt van de door het systeem toegewezen beheerde identiteit van een API Management-exemplaar om een aangepast domeincertificaat op te halen uit Key Vault.

Vereisten

• Een API Management-exemplaar dat is geconfigureerd met een door het systeem toegewezen beheerde identiteit. Als u de instantie wilt maken, kunt u een Azure-snelstartsjabloon gebruiken.
• Een Key Vault-exemplaar in dezelfde resourcegroep. Het exemplaar moet een certificaat hosten dat wordt gebruikt als een aangepast domeincertificaat in API Management.

De sjabloon bevat de volgende stappen.

1. Werk het toegangsbeleid van de Key Vault bij en sta toe dat de API Management-instance er geheimen uit haalt.
2. Werk het API Management-exemplaar bij door een aangepaste domeinnaam in te stellen via het certificaat van het Key Vault-exemplaar.

Wanneer u de sjabloon uitvoert, geeft u parameterwaarden op die geschikt zijn voor uw omgeving.

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

Benoemde waarden opslaan en beheren vanuit Key Vault

U kunt een door het systeem toegewezen beheerde identiteit gebruiken om toegang te krijgen tot Key Vault voor het opslaan en beheren van geheimen voor gebruik in API Management-beleid. Zie Benoemde waarden gebruiken in Azure API Management-beleid voor meer informatie.

Verifiëren bij een back-end met behulp van een API Management-identiteit

U kunt de door het systeem toegewezen identiteit gebruiken om te authenticeren bij een back-endservice via het beleid authenticatie-beheerde identiteit.

Verbinding maken met Azure-resources achter een IP-firewall met behulp van een door het systeem toegewezen beheerde identiteit

API Management is een vertrouwde Microsoft-service voor de volgende resources. Met deze vertrouwde status kan de service verbinding maken met de volgende resources achter een firewall. Nadat u expliciet de juiste Azure-rol hebt toegewezen aan de door het systeem toegewezen beheerde identiteit voor een resource-exemplaar , komt het toegangsbereik voor het exemplaar overeen met de Azure-rol die is toegewezen aan de beheerde identiteit.

• Vertrouwde toegang voor Key Vault
• Vertrouwde toegang voor Azure Storage
• Vertrouwde toegang voor Azure Services Bus
• Vertrouwde toegang voor Azure Event Hubs

Gebeurtenissen registreren bij een Event Hub

U kunt een door het systeem toegewezen beheerde identiteit configureren en gebruiken om toegang te krijgen tot een Event Hub om gebeurtenissen van een API Management-exemplaar te registreren. Zie Gebeurtenissen registreren bij Event Hubs in Azure API Management voor meer informatie.

Een door de gebruiker toegewezen beheerde identiteit maken

Azure Portal

Als u een beheerde identiteit in de portal wilt instellen, moet u eerst een API Management-exemplaar maken en een door de gebruiker toegewezen identiteit maken. Voltooi vervolgens de volgende stappen.

1. Ga naar uw API Management-exemplaar in de portal.

2. Selecteer beheerde identiteiten in het linkermenu onder Beveiliging.

3. Selecteer Toevoegen op het tabblad Toegewezen gebruiker.

4. Zoek naar de identiteit die u eerder hebt gemaakt en selecteer deze. Selecteer Toevoegen.

   

Azure PowerShell

De volgende stappen leiden u door het maken van een API Management-exemplaar en het toewijzen van een identiteit met behulp van Azure PowerShell.

1. Als dat nodig is, installeert u Azure PowerShell door de instructies in de Azure PowerShell-handleiding te volgen. Connect-AzAccount Voer vervolgens uit om een verbinding met Azure te maken.

2. Gebruik de volgende code om de instantie te maken. Zie voorbeelden van API Management PowerShell voor meer voorbeelden van het gebruik van Azure PowerShell met API Management.

   # 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
   

U kunt ook een bestaande service bijwerken om een identiteit toe te wijzen aan de service:

# 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-template

U kunt een API Management-exemplaar met een identiteit maken door de volgende eigenschap op te neem in de resourcedefinitie:

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

Door het door de gebruiker toegewezen type toe te voegen, wordt Azure geïnformeerd over het gebruik van de door de gebruiker toegewezen identiteit die is opgegeven voor uw exemplaar.

Een volledige ARM-sjabloon kan er bijvoorbeeld als volgt uitzien:

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

Wanneer de service wordt gemaakt, heeft deze de volgende aanvullende eigenschappen:

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

De principalId eigenschap is een unieke id voor de identiteit die wordt gebruikt voor Microsoft Entra-beheer. De clientId eigenschap is een unieke id voor de nieuwe identiteit van de toepassing die wordt gebruikt voor het opgeven van de identiteit die moet worden gebruikt tijdens runtime-aanroepen.

Ondersteunde scenario's die gebruikmaken van door de gebruiker toegewezen beheerde identiteiten

Hieronder volgen enkele veelvoorkomende scenario's voor het gebruik van een door de gebruiker toegewezen beheerde identiteit in Azure API Management.

Een aangepast TLS/SSL-certificaat verkrijgen voor het API Management-exemplaar vanuit Key Vault

U kunt een door de gebruiker toegewezen identiteit gebruiken om een vertrouwensrelatie tot stand te brengen tussen een API Management-exemplaar en Key Vault. Deze vertrouwensrelatie kan vervolgens worden gebruikt om aangepaste TLS/SSL-certificaten op te halen die zijn opgeslagen in Key Vault. U kunt deze certificaten vervolgens toewijzen aan aangepaste domeinen in het API Management-exemplaar.

Neem rekening met deze overwegingen:

• Het inhoudstype van het geheim moet toepassing/x-pkcs12 zijn.
• Je moet het certificaatgeheimeindpunt van de Key Vault gebruiken, dat het geheim bevat.

Benoemde waarden opslaan en beheren vanuit Key Vault

U kunt een door de gebruiker toegewezen beheerde identiteit gebruiken om toegang te krijgen tot Key Vault om geheimen op te slaan en te beheren voor gebruik in API Management-beleid. Zie Benoemde waarden gebruiken in Azure API Management-beleid voor meer informatie.

Verifiëren bij een back-end met behulp van een door de gebruiker toegewezen identiteit

U kunt de door de gebruiker toegewezen identiteit gebruiken om te verifiëren bij een back-endservice via het beleid voor door verificatie beheerde identiteit .

Gebeurtenissen registreren bij een Event Hub

U kunt een door de gebruiker toegewezen beheerde identiteit configureren en gebruiken om toegang te krijgen tot een Event Hub om gebeurtenissen van een API Management-exemplaar te registreren. Zie Gebeurtenissen registreren bij Azure Event Hubs in Azure API Management voor meer informatie.

Een identiteit verwijderen

U kunt een door het systeem toegewezen identiteit verwijderen door de functie via de portal of een ARM-sjabloon uit te schakelen op dezelfde manier als die is gemaakt. Door de gebruiker toegewezen identiteiten kunnen afzonderlijk worden verwijderd. Als u alle identiteiten wilt verwijderen, stelt u het identiteitstype in op "None".

Als u een door het systeem toegewezen identiteit op deze manier verwijdert, wordt deze ook verwijderd uit de Microsoft Entra-id. Door het systeem toegewezen identiteiten worden ook automatisch verwijderd uit Microsoft Entra ID wanneer het API Management-exemplaar wordt verwijderd.

Als u alle identiteiten wilt verwijderen met behulp van een ARM-sjabloon, werkt u deze sectie bij:

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

Verwante inhoud

• Wat zijn beheerde identiteiten voor Azure-resources?
• Azure Resource Manager-sjablonen
• Verifiëren met een beheerde identiteit in een beleid