Utilisation d’identités managées dans le service Gestion des API Azure

S’APPLIQUE À : Tous les niveaux de Gestion des API

Cet article vous montre comment créer une identité managée pour une instance Gestion des API Azure et comment l’utiliser pour accéder à d’autres ressources. Une identité managée générée par Microsoft Entra ID permet à votre instance API Management d’accéder facilement et en toute sécurité à d’autres ressources protégées par Microsoft Entra, telles qu’Azure Key Vault. Azure gère cette identité et vous n’avez pas besoin d’approvisionner ou de faire tourner les secrets. Pour en savoir plus sur les identités managées, consultez la section Que sont les identités managées pour les ressources Azure ?

Vous pouvez accorder deux types d’identités à une instance Gestion des API :

• Une identité affectée par le système est liée à votre service et est supprimée si votre service est supprimé. Le service ne peut avoir qu’une seule identité affectée par le système.
• Une identité affectée par l’utilisateur est une ressource Azure autonome qui peut être affectée à votre service. Le service peut avoir plusieurs identités affectées par l’utilisateur.

Créer une identité managée affectée par le système

Portail Azure

Pour configurer une identité managée dans le portail Azure, vous devez d’abord créer une instance du service Gestion des API, puis activer la fonctionnalité.

1. Créez une instance Gestion des API dans le portail comme vous le faites en temps normal. Accédez-y dans le portail.

2. Dans le menu de gauche, sous Sécurité, sélectionnez Identités managées.

3. Dans l’onglet Attribuée par le système, définissez État sur Activé. Sélectionnez Enregistrer.

   

Azure PowerShell

Les étapes suivantes vous guideront dans la création d’une instance Gestion des API application à laquelle vous attribuez une identité avec Azure PowerShell.

1. Si nécessaire, installez Azure PowerShell à l’aide des instructions figurant dans le Guide Azure PowerShell. Exécutez ensuite Connect-AzAccount pour créer une connexion avec Azure.

2. Utilisez le code suivant pour créer l’instance avec une identité managée affectée par le système. Pour plus d’exemples sur l’utilisation d’Azure PowerShell avec Gestion des API, consultez Exemples Gestion des API PowerShell.

   # 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
   

Vous pouvez également mettre à jour une instance existante pour créer l’identité :

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

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

Modèle Azure Resource Manager

Vous pouvez créer une instance Gestion des API avec une identité attribuée par le système en incluant la propriété suivante dans la définition de la ressource :

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

Cette propriété indique à Azure de créer et de manager l’identité de votre instance Gestion des API.

Par exemple, un modèle complet Azure Resource Manager peut se présenter comme suit :

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

Quand l’instance est créée, elle a les propriétés supplémentaires suivantes :

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

La propriété tenantId identifie le tenant Microsoft Entra auquel appartient l’identité. La propriété principalId est un identificateur unique pour la nouvelle identité de l’instance. Dans Microsoft Entra ID, le principal de service a le même nom que celui que vous avez donné à votre instance API Management.

Configurer l’accès à Key Vault en utilisant une identité managée

Les configurations suivantes sont nécessaires pour Gestion des API afin d’accéder aux secrètes et aux certificats d’un coffre de clés Azure.

Configurer l’accès au coffre de clés

1. Dans le portail, accédez à votre coffre de clés.

2. Dans le menu de gauche, sélectionnez Configuration de l’accès et notez le modèle d’autorisation configuré.

3. Selon le modèle d’autorisation, configurez une stratégie d’accès au coffre de clés ou un accès RBAC Azure pour une identité managée Gestion des API.

   Pour ajouter une stratégie d’accès au coffre de clés :
   

   1. Dans le menu de gauche, sélectionnez Stratégies d’accès.
   2. Sur la page Stratégies d’accès, sélectionnez + Créer.
   3. Sous l’onglet Autorisations, sous Autorisations du secret, sélectionnez Get et List, puis sélectionnez Suivant.
   4. Sous l’onglet Principal, sélectionnez Sélectionner le principal, recherchez le nom de ressource de votre identité managée, puis sélectionnez Suivant. Si vous utilisez une identité attribuée par le système, le principal est le nom de votre instance Gestion des API.
   5. Sélectionnez Suivant de nouveau. Sous l’onglet Review + create (Vérifier + créer) , sélectionnez Créer.

   Pour configurer l’accès RBAC Azure :
   

   1. Dans le menu de gauche, sélectionnez Contrôle d’accès (IAM) .
   2. Sur la page Contrôle d’accès (IAM), sélectionnez Ajout de l’attribution de rôle.
   3. Sous l’onglet Rôle, sélectionnez Utilisateur du certificat Key Vault.
   4. Sous l’onglet Membres, sélectionnez Identité managée>+ Sélectionner des membres.
   5. Dans la page Sélectionner l’identité managée, sélectionnez l’identité managée affectée par le système ou une identité managée affectée par l’utilisateur associée à votre instance Gestion des API, puis sélectionnez Sélectionner.
   6. Sélectionnez Vérifier + attribuer.

Exigences pour le pare-feu Key Vault

Si le pare-feu Key Vault est activé sur votre coffre de clés, les conditions suivantes sont requises :

• Vous devez utiliser l’identité managée attribuée par le système à l’instance Gestion des API pour accéder au coffre de clés.

• Dans le pare-feu Key Vault, activez l’option Autoriser les services Microsoft approuvés à contourner ce pare-feu.

• Vérifiez que votre adresse IP du client local est autorisée à accéder temporairement au coffre de clés pendant que vous sélectionnez un certificat ou un secret à ajouter à Gestion des API Azure. Pour plus d’informations, consultez Configurer les paramètres de mise en réseau du Coffre de clés Azure.

  Une fois la configuration terminée, vous pouvez bloquer votre adresse client dans le pare-feu du coffre de clés.

Conditions requises pour le réseau virtuel

Si l’instance Gestion des API est déployée dans un réseau virtuel, configurez également les paramètres réseau suivants :

• Activez un point de terminaison de service pour Azure Key Vault sur le sous-réseau Gestion des API.
• Configurez une règle de groupe de sécurité réseau (NSG) pour autoriser le trafic sortant vers les balises de service AzureKeyVault et AzureActiveDirectory.

Pour plus d’informations, consultez Configuration du réseau lors de la configuration de Gestion des API Azure dans un réseau virtuel.

Scénarios pris en charge utilisant l’identité affectée par le système

Obtenir un certificat TLS/SSL personnalisé pour l’instance Gestion des API à partir de Azure Key Vault

Vous pouvez utiliser l’identité affectée par le système d’une instance Gestion des API pour récupérer les certificats TLS/SSL personnalisés stockés dans Azure Key Vault. Vous pouvez ensuite affecter ces certificats à des domaines personnalisés dans l’instance Gestion des API. Gardez à l’esprit les éléments suivants :

• Le type de contenu du secret doit être application/x-pkcs12. Apprenez-en davantage sur les exigences de certificat de domaine personnalisé.
• Utilisez le point de terminaison du secret de certificat Key Vault, qui contient le secret.

L’exemple suivant montre un modèle Azure Resource Manager qui utilise l’identité managée affectée par le système d’une instance de service Gestion des API pour récupérer un certificat de domaine personnalisé à partir de Key Vault.

Prérequis

• Instance de service Gestion des API configurée avec une identité managée affectée par le système. Pour créer l’instance, vous pouvez utiliser un modèle de démarrage rapide Azure.
• Une instance Azure Key Vault dans le même groupe de ressources, hébergeant un certificat qui sera utilisé comme certificat de domaine personnalisé dans Gestion des API.

Le modèle suivant contient les étapes suivantes.

1. Mettez à jour les stratégies d’accès de l’instance Azure Key Vault et autorisez l’instance Gestion des API à obtenir des secrets à partir de celle-ci.
2. Mettez à jour l’instance Gestion des API en définissant un nom de domaine personnalisé via le certificat obtenu à partir de l’instance Key Vault.

Lorsque vous exécutez le modèle, fournissez des valeurs de paramètre appropriées pour votre environnement.

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

Stocker et gérer des valeurs nommées depuis Azure Key Vault

Vous pouvez utiliser une identité managée affectée par le système pour accéder à Azure Key Vault afin de stocker et de gérer les secrets à utiliser dans les stratégies API Management. Pour plus d’informations, consultez Utiliser des valeurs nommées dans les stratégies Gestion des API Azure.

S’authentifier auprès d’un serveur principal à l’aide d’une identité Gestion des API

Vous pouvez utiliser l’identité affectée par le système pour vous authentifier auprès d’un service principal par le biais de la stratégie authentication-managed-identity.

Se connecter aux ressources Azure derrière un pare-feu IP en utilisant l’identité managée attribuée par le système

API Management est un service Microsoft approuvé pour les ressources suivantes. Cela permet au service de se connecter aux ressources suivantes derrière un pare-feu. Après que vous avez explicitement attribué le rôle Azure approprié à l’identité managée attribuée par le système pour cette instance de ressource, l’étendue de l’accès à l’instance correspond au rôle Azure attribué à l’identité managée.

Journaliser des événements dans un Event Hub

Vous pouvez configurer, puis utiliser une identité managée affectée par le système pour accéder à un Event Hub pour la journalisation des événements depuis une instance de Gestion des API. Si vous souhaitez en savoir plus, veuillez consulter la rubrique Comment enregistrer des événements sur Azure Event Hubs dans Gestion des API Azure.

Créer une identité managée attribuée par l’utilisateur

Portail Azure

Pour configurer une identité managée dans le portail, vous devez d’abord créer une instance du service Gestion des API, puis créer une identité attribuée par l’utilisateur. Activez ensuite la fonctionnalité.

1. Créez une instance Gestion des API dans le portail comme vous le faites en temps normal. Accédez-y dans le portail.

2. Dans le menu de gauche, sous Sécurité, sélectionnez Identités managées.

3. Dans l’onglet Attribuée par l’utilisateur, sélectionnez Ajouter.

4. Recherchez l’identité que vous avez créée précédemment et sélectionnez-la. Sélectionnez Ajouter.

   

Azure PowerShell

Les étapes suivantes vous guideront dans la création d’une instance Gestion des API application à laquelle vous attribuez une identité avec Azure PowerShell.

1. Si nécessaire, installez Azure PowerShell à l’aide des instructions figurant dans le Guide Azure PowerShell. Exécutez ensuite Connect-AzAccount pour créer une connexion avec Azure.

2. Utilisez le code suivant pour créer l’instance. Pour plus d’exemples sur l’utilisation d’Azure PowerShell avec Gestion des API, consultez Exemples Gestion des API PowerShell.

   # 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
   

Vous pouvez également mettre à jour un service existant pour affecter une identité au service :

# 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

Modèle Azure Resource Manager

Vous pouvez créer une instance Gestion des API avec une identité en incluant la propriété suivante dans la définition de la ressource :

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

L’ajout du type attribué par l’utilisateur indique à Azure d’utiliser l’identité affectée par l’utilisateur qui est spécifiée pour votre instance.

Par exemple, un modèle complet Azure Resource Manager peut se présenter comme suit :

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

Quand le service est créé, il a les propriétés supplémentaires suivantes :

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

La propriété principalId est un identificateur unique pour l’identité qui est utilisée pour l’administration de Microsoft Entra. La propriété clientId est un identificateur unique pour la nouvelle identité de l’application qui est utilisée pour spécifier l’identité à utiliser lors des appels de runtime.

Scénarios pris en charge utilisant l’identité managée affectée par l’utilisateur

Obtenir un certificat TLS/SSL personnalisé pour l’instance Gestion des API à partir de Azure Key Vault

Vous pouvez utiliser n’importe quelle identité affectée par l’utilisateur pour établir une relation de confiance entre une instance Gestion des API et Azure Key Vault. Cette confiance peut ensuite être utilisée pour récupérer des certificats TLS/SSL personnalisés stockés dans Azure Key Vault. Vous pouvez ensuite affecter ces certificats à des domaines personnalisés dans l’instance Gestion des API.

Gardez à l’esprit les éléments suivants :

• Le type de contenu du secret doit être application/x-pkcs12.
• Utilisez le point de terminaison du secret de certificat Key Vault, qui contient le secret.

Stocker et gérer des valeurs nommées depuis Azure Key Vault

Vous pouvez utiliser une identité managée affectée par l’utilisateur pour accéder à Azure Key Vault afin de stocker et de gérer les secrets à utiliser dans les stratégies API Management. Pour plus d’informations, consultez Utiliser des valeurs nommées dans les stratégies Gestion des API Azure.

S’authentifier auprès d’un serveur principal à l’aide d’une identité affectée par l’utilisateur

Vous pouvez utiliser l’identité affectée par l’utilisateur pour vous authentifier auprès d’un service principal par le biais de la stratégie authentication-managed-identity.

Journaliser des événements dans un Event Hub

Vous pouvez configurer, puis utiliser une identité managée affectée par l’utilisateur pour accéder à un Event Hub pour la journalisation des événements depuis une instance de Gestion des API. Si vous souhaitez en savoir plus, veuillez consulter la rubrique Comment enregistrer des événements sur Azure Event Hubs dans Gestion des API Azure.

Supprimer une identité

Vous pouvez supprimer une identité affectée par le système en désactivant la fonctionnalité via le portail ou le modèle Azure Resource Manager de la même manière qu’elle a été créée. Les identités attribuées par l’utilisateur peuvent être supprimées individuellement. Pour supprimer toutes les identités, définissez le type d’identité sur "None".

Si vous supprimez une identité attribuée par le système de cette façon, vous la supprimez également de Microsoft Entra ID. Les identités attribuées par le système sont aussi automatiquement supprimées de Microsoft Entra ID quand l’instance API Management est supprimée.

Pour supprimer toutes les identités à l’aide du modèle Azure Resource Manager, mettez à jour cette section :

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

Étapes suivantes

En savoir plus sur les identités managées pour les ressources Azure :

• Que sont les identités managées pour les ressources Azure ?
• Modèles Microsoft Azure Resource Manager
• Authentifier avec l’identité managée