Použití spravovaných identit ve službě Azure API Management

PLATÍ PRO: Všechny úrovně služby Správa rozhraní API

Tento článek ukazuje, jak vytvořit spravovanou identitu pro instanci služby Azure API Management a jak ji použít pro přístup k dalším prostředkům. Spravovaná identita generovaná id Microsoft Entra umožňuje službě API Management snadno a bezpečně přistupovat k dalším prostředkům chráněným microsoftem Entra, jako je Azure Key Vault. Azure tyto identity spravuje, takže nemusíte zřizovat ani obměňovat tajné kódy. Další informace o spravovaných identitách najdete v tématu Co jsou spravované identity pro prostředky Azure?

Instanci API Management můžete udělit dva typy identit:

Identita přiřazená systémem je svázaná s vaší službou a při odstranění služby se odstraní. Služba může mít pouze jednu identitu přiřazenou systémem.
Identita přiřazená uživatelem je samostatný prostředek Azure, který je možné přiřadit k vaší službě. Služba může mít více identit přiřazených uživatelem.

Poznámka:

Spravované identity jsou specifické pro tenanta Microsoft Entra, ve kterém je vaše předplatné Azure hostované. Neaktualizují se, pokud se předplatné přesune do jiného adresáře. Pokud se předplatné přesune, budete muset znovu vytvořit a znovu nakonfigurovat identity.

Poznámka:

V současné době tato funkce není dostupná v pracovních prostorech.

Vytvoření spravované identity přiřazené systémem

Azure Portal

Pokud chcete nastavit spravovanou identitu na webu Azure Portal, vytvoříte instanci služby API Management a pak tuto funkci povolíte.

Na portálu vytvořte instanci služby API Management jako obvykle. Přejděte na něj na portálu.
V nabídce vlevo v části Zabezpečení vyberte Spravované identity.
Na kartě Přiřazený systém změňte Status na Zapnuto. Zvolte Uložit.

Azure PowerShell

Poznámka:

Při práci s Azure doporučujeme používat modul Azure Az PowerShellu. Začněte tím, že si projdete téma Instalace Azure PowerShellu. Informace o tom, jak migrovat na modul Az PowerShell, najdete v tématu Migrace Azure PowerShellu z AzureRM na Az.

Následující kroky vás provedou vytvořením instance služby API Management a přiřazením identity pomocí Azure PowerShellu.

Pokud potřebujete, nainstalujte Azure PowerShell podle pokynů v průvodci Azure PowerShellem. Pak spusťte příkaz Connect-AzAccount k vytvoření připojení s Azure.

Pomocí následujícího kódu vytvořte instanci se spravovanou identitou přiřazenou systémem. Další příklady použití Azure PowerShellu se službou API Management najdete v ukázkách PowerShellu služby 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

Můžete také aktualizovat existující instanci a vytvořit identitu:

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

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

Šablona Azure Resource Manageru (ARM)

Instanci služby API Management s identitou přiřazenou systémem můžete vytvořit zahrnutím následující vlastnosti do definice prostředku šablony ARM:

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

Tato vlastnost dává Azure pokyn k vytvoření a správě identity pro vaši instanci služby API Management.

Kompletní šablona ARM může vypadat například takto:

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

Při vytvoření instance má následující další vlastnosti:

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

Atribut tenantId určuje, ke kterému tenantovi Microsoft Entra patří identita. Vlastnost principalId je jedinečný identifikátor nové identity instance. V rámci Microsoft Entra ID má principál služby stejný název, který jste dali své instanci API Management.

Poznámka:

Instance služby API Management může mít identity přiřazené systémem i uživatelem. V tomto scénáři je vlastnost typeSystemAssigned,UserAssigned.

Konfigurace přístupu ke službě Key Vault pomocí spravované identity

Pokud chcete pro přístup k certifikátům ze služby Azure Key Vault použít službu API Management, jsou potřeba následující konfigurace.

Konfigurace přístupu k trezoru klíčů

Na portálu přejděte do trezoru klíčů.
V nabídce vlevo vyberte Nastavení>konfigurace přístupu. Všimněte si nakonfigurovaného modelu oprávnění .
V závislosti na modelu oprávnění nakonfigurujte zásady přístupu trezoru klíčů nebo přístup Azure RBAC pro spravovanou identitu služby API Management.

Chcete-li přidat zásadu přístupu k trezoru klíčů:

V nabídce vlevo vyberte Zásady přístupu.
Na stránce Zásady přístupu vyberte + Vytvořit.
Na kartě Oprávnění v sekci Oprávnění pro tajné vyberte Získat a Vypsat a pak vyberte Další.
Na kartě Hlavní vyhledejte název prostředku vaší spravované identity a poté vyberte Další. Pokud používáte identitu přiřazenou systémem, principál je název vaší instance služby API Management.
Znovu vyberte Další . Na kartě Revize a vytvoření vyberte Vytvořit.

Konfigurace přístupu Azure RBAC:

V nabídce vlevo vyberte Řízení přístupu (IAM).
Na stránce Řízení přístupu (IAM) vyberte Přidat roli přiřazení.
Na kartě Role vyberte uživatele certifikátu služby Key Vault.
Na kartě Členové vyberte Spravovaná identita>+ Vybrat členy.
V okně Vybrat spravované identity vyberte spravovanou identitu přiřazenou systémem nebo spravovanou identitu přiřazenou uživatelem přidruženou k vaší instanci služby API Management a klikněte na vybrat.
Vyberte Zkontrolovat + přiřadit.

Požadavky na bránu firewall služby Key Vault

Pokud je ve vašem klíčovém trezoru povolená brána firewall služby Key Vault, je potřeba splňovat následující požadavky:

Pro přístup k trezoru klíčů musíte použít spravovanou identitu přiřazenou systémem instance služby API Management.
V bráně firewall služby Key Vault povolte možnost Povolit důvěryhodným službám Microsoftu obejít tuto bránu firewall.
Ujistěte se, že vaše IP adresa místního klienta má povolený přístup k trezoru klíčů dočasně, když vyberete certifikát nebo tajný klíč pro přidání do služby Azure API Management. Další informace najdete v tématu Konfigurace nastavení sítě služby Azure Key Vault.

Po dokončení konfigurace můžete zablokovat adresu klienta v bráně firewall trezoru klíčů.

Požadavky na virtuální síť

Pokud je instance služby API Management nasazená ve virtuální síti, nakonfigurujte také následující nastavení sítě:

Povolte koncový bod služby Key Vault na podsíti API Management.
Nakonfigurujte pravidlo skupiny zabezpečení sítě (NSG), které povolí odchozí provoz do značek služeb AzureKeyVault a AzureActiveDirectory.

Podrobnosti najdete v tématu Konfigurace sítě při nastavování služby API Management ve virtuální síti.

Podporované scénáře, které používají identitu přiřazenou systémem

Následuje několik běžných scénářů použití spravované identity přiřazené systémem ve službě Azure API Management.

Získání vlastního certifikátu TLS/SSL pro instanci služby API Management ze služby Key Vault

Identitu přiřazenou systémem instance služby API Management můžete použít k načtení vlastních certifikátů TLS/SSL uložených ve službě Key Vault. Tyto certifikáty pak můžete přiřadit k vlastním doménám v instanci služby API Management. Vezměte v úvahu tyto aspekty:

Typ obsahu tajného kódu musí být application/x-pkcs12. Další informace najdete v tématu Možnosti certifikátu domény.
Musíte použít koncový bod tajného kódu certifikátu služby Key Vault, který obsahuje tajný klíč.

Důležité

Pokud nezadáte verzi objektu certifikátu, služba API Management automaticky získá novou verzi certifikátu do čtyř hodin od aktualizace ve službě Key Vault.

Následující příklad ukazuje šablonu ARM, která používá spravovanou identitu přiřazenou systémem instance služby API Management k načtení vlastního certifikátu domény ze služby Key Vault.

Požadavky

Instance služby API Management, která je nakonfigurovaná se spravovanou identitou přiřazenou systémem. K vytvoření instance můžete použít šablonu rychlého startu Azure.
Instance služby Key Vault v rámci stejné skupiny prostředků. Instance musí hostovat certifikát, který se použije jako vlastní certifikát domény ve službě API Management.

Šablona obsahuje následující kroky.

Aktualizujte zásady přístupu instance služby Key Vault a povolte instanci služby API Management získat z ní tajné kódy.
Aktualizujte instanci služby API Management nastavením vlastního názvu domény prostřednictvím certifikátu z instance služby Key Vault.

Při spuštění šablony zadejte hodnoty parametrů, které jsou vhodné pro vaše prostředí.

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

Ukládání a správa pojmenovaných hodnot ze služby Key Vault

Spravovanou identitu přiřazenou systémem můžete použít pro přístup ke službě Key Vault k ukládání a správě tajných kódů pro použití v zásadách služby API Management. Další informace najdete v tématu Použití pojmenovaných hodnot v zásadách služby Azure API Management.

Ověřování v back-endu pomocí identity služby API Management

Identitu přiřazenou systémem můžete použít k ověření u back-endové služby prostřednictvím zásady ověřování spravované identity.

Připojení k prostředkům Azure za bránou firewall protokolu IP pomocí spravované identity přiřazené systémem

API Management je důvěryhodná služba společnosti Microsoft pro následující prostředky. Tento důvěryhodný stav umožňuje službě připojit se k následujícím prostředkům za firewallem. Jakmile explicitně přiřadíte příslušnou roli Azure spravované identitě přiřazené systémem pro instanci prostředku, rozsah přístupu pro instanci odpovídá roli Azure, která je přiřazená spravované identitě.

Protokolování událostí do událostního centra

Spravovanou identitu přiřazenou systémem můžete nakonfigurovat a použít pro přístup k centru událostí pro protokolování událostí z instance služby API Management. Další informace najdete v tématu Protokolování událostí do služby Event Hubs ve službě Azure API Management.

Vytvořit spravovanou identitu přiřazenou uživatelem

Poznámka:

Instanci služby API Management můžete přidružit až k 10 spravovaným identitám přiřazeným uživatelem.

Azure Portal

Pokud chcete nastavit spravovanou identitu na portálu, musíte nejprve vytvořit instanci služby API Management a vytvořit identitu přiřazenou uživatelem. Pak proveďte následující kroky.

Na portálu přejděte ke své instanci služby API Management.
V nabídce vlevo v části Zabezpečení vyberte Spravované identity.
Na kartě Přiřazeno uživatelem vyberte Přidat.
Vyhledejte identitu, kterou jste vytvořili dříve, a vyberte ji. Vyberte Přidat.

Azure PowerShell

Poznámka:

Následující kroky vás provedou vytvořením instance služby API Management a přiřazením identity pomocí Azure PowerShellu.

Pokud potřebujete, nainstalujte Azure PowerShell podle pokynů v průvodci Azure PowerShellem. Pak spusťte příkaz Connect-AzAccount k vytvoření připojení s Azure.

K vytvoření instance použijte následující kód. Další příklady použití Azure PowerShellu se službou API Management najdete v ukázkách PowerShellu služby 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

Existující službu můžete také aktualizovat tak, aby přiřadil identitu ke službě:

# 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

šablona ARM

Instanci služby API Management, která má identitu, můžete vytvořit zahrnutím následující vlastnosti do definice prostředku:

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

Přidání typu přiřazeného uživatelem informuje Azure, aby používala identitu přiřazenou uživatelem, která je pro vaši instanci zadaná.

Kompletní šablona ARM může vypadat například takto:

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

Při vytváření služby má následující další vlastnosti:

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

Vlastnost principalId je jedinečný identifikátor identity, která se používá pro správu Microsoft Entra. Vlastnost clientId je jedinečný identifikátor nové identity aplikace, která se používá k určení identity, která se má použít při volání modulu runtime.

Poznámka:

Instance služby API Management může mít identity přiřazené systémem i uživatelem. V tomto scénáři by vlastnost type byla SystemAssigned,UserAssigned.

Podporované scénáře, které používají spravované identity přiřazené uživatelem

Následuje několik běžných scénářů použití spravované identity přiřazené uživatelem ve službě Azure API Management.

Získání vlastního certifikátu TLS/SSL pro instanci služby API Management ze služby Key Vault

Identitu přiřazenou uživatelem můžete použít k navázání vztahu důvěryhodnosti mezi instancí služby API Management a službou Key Vault. Tento vztah důvěryhodnosti se pak dá použít k načtení vlastních certifikátů TLS/SSL uložených ve službě Key Vault. Tyto certifikáty pak můžete přiřadit k vlastním doménám v instanci služby API Management.

Důležité

Pokud je ve vašem trezoru klíčů povolená brána firewall služby Key Vault, nemůžete pro přístup ze služby API Management použít identitu přiřazenou uživatelem. Místo toho můžete použít identitu přiřazenou systémem. V nastavení brány firewall služby Key Vault musí být povolena možnost Povolit důvěryhodným službám Microsoftu obejít tuto bránu firewall.

Vezměte v úvahu tyto aspekty:

Typ obsahu tajného kódu musí být application/x-pkcs12.
Musíte použít koncový bod tajného kódu certifikátu služby Key Vault, který obsahuje tajný klíč.

Důležité

Pokud nezadáte verzi objektu certifikátu, služba API Management automaticky získá novou verzi certifikátu do čtyř hodin od aktualizace ve službě Key Vault.

Ukládání a správa pojmenovaných hodnot ze služby Key Vault

Spravovanou identitu přiřazenou uživatelem můžete použít pro přístup ke službě Key Vault a ukládat a spravovat tajné kódy pro použití v zásadách služby API Management. Další informace najdete v tématu Použití pojmenovaných hodnot v zásadách služby Azure API Management.

Poznámka:

Ověřování v back-endu pomocí identity přiřazené uživatelem

Identitu přiřazenou uživatelem můžete použít k ověření ve službě back-end prostřednictvím zásady ověřování spravované identity.

Protokolování událostí do událostního centra

Spravovanou identitu přiřazenou uživatelem můžete nakonfigurovat a použít pro přístup k centru událostí pro protokolování událostí z instance služby API Management. Další informace najdete v tématu Protokolování událostí do služby Azure Event Hubs ve službě Azure API Management.

Odstraňte identitu

Identitu přiřazenou systémem můžete odebrat zakázáním funkce prostřednictvím portálu nebo šablony ARM stejným způsobem, jakým byla vytvořena. Identity přiřazené uživatelem je možné odebrat jednotlivě. Pokud chcete odebrat všechny identity, nastavte typ identity na "None".

Odebrání identity přiřazené systémem tímto způsobem ji také odstraní z Microsoft Entra ID. Identity přiřazené systémem se také automaticky odeberou z ID Microsoft Entra při odstranění instance služby API Management.

Pokud chcete odebrat všechny identity pomocí šablony ARM, aktualizujte tuto část:

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

Důležité

Pokud je instance služby API Management nakonfigurovaná s vlastním certifikátem SSL ze služby Key Vault a pokusíte se zakázat spravovanou identitu, požadavek selže.

Tento problém můžete vyřešit tak, že přepnete z certifikátu služby Key Vault na vložený certifikát a potom zakážete spravovanou identitu. Další informace najdete v tématu Konfigurace vlastního názvu domény.

Váš názor

Byla tato stránka užitečná?

Last updated on 2025-06-02

Sdílet prostřednictvím

Použití spravovaných identit ve službě Azure API Management

Vytvoření spravované identity přiřazené systémem

Azure Portal

Azure PowerShell

Šablona Azure Resource Manageru (ARM)

Konfigurace přístupu ke službě Key Vault pomocí spravované identity

Konfigurace přístupu k trezoru klíčů

Požadavky na bránu firewall služby Key Vault

Požadavky na virtuální síť

Podporované scénáře, které používají identitu přiřazenou systémem

Získání vlastního certifikátu TLS/SSL pro instanci služby API Management ze služby Key Vault

Požadavky

Ukládání a správa pojmenovaných hodnot ze služby Key Vault

Ověřování v back-endu pomocí identity služby API Management

Připojení k prostředkům Azure za bránou firewall protokolu IP pomocí spravované identity přiřazené systémem

Protokolování událostí do událostního centra

Vytvořit spravovanou identitu přiřazenou uživatelem

Azure Portal

Azure PowerShell

šablona ARM

Podporované scénáře, které používají spravované identity přiřazené uživatelem

Získání vlastního certifikátu TLS/SSL pro instanci služby API Management ze služby Key Vault

Ukládání a správa pojmenovaných hodnot ze služby Key Vault

Ověřování v back-endu pomocí identity přiřazené uživatelem

Protokolování událostí do událostního centra

Odstraňte identitu

Související obsah

Váš názor

Další materiály