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

Článek
10/18/2023

PLATÍ PRO: Všechny úrovně služby API Management

V tomto článku se dozvíte, 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 vaší instanci služby API Management snadno a bezpečně přistupovat k dalším prostředkům chráněným Microsoft Entra, jako je Azure Key Vault. Tuto identitu spravuje Azure, 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, kde 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 nakonfigurovat identity.

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

portál Azure

Pokud chcete nastavit spravovanou identitu na webu Azure Portal, nejprve 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 přepněte stav 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.

V případě potřeby nainstalujte Azure PowerShell podle pokynů v průvodci Azure PowerShellem. Pak spusťte a Connect-AzAccount vytvořte připojení k 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 s instancí služby 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

Instanci služby API Management s identitou přiřazenou systémem můžete vytvořit tak, že do definice prostředku zahrnete následující vlastnost:

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

Tato vlastnost říká Azure, aby vytvořila a spravuje identitu vaší instance služby API Management.

Kompletní šablona Azure Resource Manageru 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>"
}

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

Poznámka:

Instance API Management může mít současně identity přiřazené systémem i uživatelem. V tomto případě type by vlastnost byla SystemAssigned,UserAssigned.

Konfigurace přístupu Key Vault pomocí spravované identity

Pro přístup k tajným kódům a certifikátům ze služby Azure Key Vault 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 konfiguraci accessu a poznamenejte si nakonfigurovaný model 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.

Přidání zásady přístupu trezoru klíčů:
1. V nabídce vlevo vyberte Zásady přístupu.
2. Na stránce Zásady přístupu vyberte + Vytvořit.
3. Na kartě Oprávnění v části Oprávnění vyberte Získat a Seznam a pak vyberte Další.
4. Na kartě Objekt zabezpečení vyberte objekt zabezpečení, vyhledejte název prostředku vaší spravované identity a pak vyberte Další. Pokud používáte identitu přiřazenou systémem, objekt zabezpečení je název vaší instance služby API Management.
5. Znovu vyberte Další . Na kartě Revize a vytvoření vyberte Vytvořit.
Konfigurace přístupu Azure RBAC:
1. V nabídce vlevo vyberte Řízení přístupu (IAM).
2. Na stránce Řízení přístupu (IAM) vyberte Přidat přiřazení role.
3. Na kartě Role vyberte uživatele tajných kódů služby Key Vault.
4. Na kartě Členové vyberte Spravovaná identita> + Vybrat členy.
5. Na stránce Vybrat spravovanou identitu 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 pak vyberte Vybrat.
6. Vyberte Zkontrolovat + přiřadit.

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

Pokud je ve vašem trezoru klíčů povolená brána firewall služby Key Vault, jsou další 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, aby tuto možnost brány firewall vynechala důvěryhodná služba Microsoftu.
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 do služby Azure Key Vault v podsíti služby 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 Azure API Management ve virtuální síti.

Podporované scénáře s využitím identity přiřazené systémem

Získání vlastního certifikátu TLS/SSL pro instanci API Management z Azure Key Vault

K načtení vlastních certifikátů TLS/SSL uložených v Azure Key Vault můžete použít identitu instance API Management přiřazenou systémem. Tyto certifikáty pak můžete přiřadit k vlastním doménám v instanci služby API Management. Mějte na paměti tyto aspekty:

Typ obsahu tajného kódu musí být application/x-pkcs12. Přečtěte si další informace o požadavcích na vlastní certifikát domény.
Použijte 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á novější verzi certifikátu do čtyř hodin od aktualizace ve službě Key Vault.

Následující příklad ukazuje šablonu Azure Resource Manageru, 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 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 Azure Key Vault ve stejné skupině prostředků hostující certifikát, který se použije jako vlastní certifikát domény ve službě API Management.

Následující šablona obsahuje následující kroky.

Aktualizujte zásady přístupu instance služby Azure 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ů 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 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"
					}
				}]
		}
		}
	}
]
}

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

Spravovanou identitu přiřazenou systémem můžete použít pro přístup ke službě Azure 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í v back-endové službě prostřednictvím zásad 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. To umožňuje službě se připojit k následujícím prostředkům za bránou firewall. Jakmile explicitně přiřadíte příslušnou roli Azure spravované identitě přiřazené systémem pro danou instanci prostředku, rozsah přístupu pro instanci odpovídá roli Azure přiřazené spravované identitě.

Služba Azure	Odkaz
Azure Key Vault	Důvěryhodný přístup k trezoru klíčů Azure
Azure Storage	Důvěryhodný přístup k úložišti Azure
Azure Service Bus	Důvěryhodný přístup k azure-service-bus
Azure Event Hubs	Důvěryhodný přístup k azure-event-hub

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

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 Azure Event Hubs ve službě Azure API Management.

Vytvoření spravované identity přiřazené 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.

portál Azure

Pokud chcete nastavit spravovanou identitu na portálu, nejprve vytvoříte instanci služby API Management a vytvoříte identitu přiřazenou uživatelem. Potom tuto funkci povolte.

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ý uživatel 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.

V případě potřeby nainstalujte Azure PowerShell podle pokynů v průvodci Azure PowerShellem. Pak spusťte a Connect-AzAccount vytvořte připojení k Azure.

K vytvoření instance použijte následující kód. Další příklady použití Azure PowerShellu s instancí služby 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 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 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

Šablona Azure Resource Manageru

Instanci služby API Management s identitou můžete vytvořit tak, že do definice prostředku zahrnete následující vlastnost:

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

Přidání typu přiřazeného uživatelem říká Azure, aby použila identitu přiřazenou uživatelem zadanou pro vaši instanci.

Kompletní šablona Azure Resource Manageru 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 API Management může mít současně identity přiřazené systémem i uživatelem. V tomto případě type by vlastnost byla SystemAssigned,UserAssigned.

Podporované scénáře s využitím spravované identity přiřazené uživatelem

Získání vlastního certifikátu TLS/SSL pro instanci API Management z Azure 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 Azure 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ě Azure 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 bráně firewall služby Key Vault musí být také povolená možnost Povolit důvěryhodným službám Microsoftu obejít tuto možnost brány firewall .

Mějte na paměti tyto aspekty:

Typ obsahu tajného kódu musí být application/x-pkcs12.
Použijte 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á novější verzi certifikátu do čtyř hodin od aktualizace ve službě Key Vault.

Kompletní šablonu najdete v tématu API Management se službou Key Vault založeným na SSL pomocí identity přiřazené uživatelem.

V této šabloně nasadíte:

Instance služby Azure API Management
Spravovaná identita přiřazená uživatelem Azure
Azure Key Vault pro ukládání certifikátu SSL/TLS

Pokud chcete nasazení spustit automaticky, vyberte následující tlačítko:

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

Spravovanou identitu přiřazenou uživatelem můžete použít pro přístup ke službě Azure 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.

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í v back-endové službě prostřednictvím zásad identity spravované ověřováním.

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

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.

Odebrání identity

Identitu přiřazenou systémem můžete odebrat zakázáním funkce prostřednictvím portálu nebo šablony Azure Resource Manageru 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"hodnotu .

Odebráním identity přiřazené systémem tímto způsobem se odstraní také z ID Microsoft Entra. 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 Azure Resource Manageru, 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.

Můžete se odblokovat tak, že přepnete z certifikátu služby Azure Key Vault na vložený kódovaný certifikát a potom zakážete spravovanou identitu. Další informace najdete v tématu Konfigurace vlastního názvu domény.

Další kroky

Další informace o spravovaných identitách pro prostředky Azure:

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

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

portál Azure

Azure PowerShell

Šablona Azure Resource Manageru

Konfigurace přístupu 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 s využitím identity přiřazené systémem

Získání vlastního certifikátu TLS/SSL pro instanci API Management z Azure Key Vault

Požadavky

Ukládání a správa pojmenovaných hodnot ze služby Azure 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 centra událostí

Vytvoření spravované identity přiřazené uživatelem

portál Azure

Azure PowerShell

Šablona Azure Resource Manageru

Podporované scénáře s využitím spravované identity přiřazené uživatelem

Získání vlastního certifikátu TLS/SSL pro instanci API Management z Azure Key Vault

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

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

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

Odebrání identity

Další kroky

Další materiály