Notes
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de vous connecter ou de modifier des répertoires.
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de modifier des répertoires.
S’APPLIQUE À : Tous les niveaux de Gestion des API
Cet article explique 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 l’ID Microsoft Entra permet à Gestion des API d’accéder facilement et en toute sécurité à d’autres ressources protégées par Microsoft Entra, comme Azure Key Vault. Azure gère ces identités, de sorte que vous n’avez pas besoin de provisionner ou de faire tourner des 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.
Remarque
Les identités managées sont spécifiques au locataire Microsoft Entra dans lequel votre abonnement Azure est hébergé. Elles ne sont pas mises à jour si un abonnement est déplacé vers un autre annuaire. Si un abonnement est déplacé, vous devez recréer et reconfigurer les identités.
Remarque
Actuellement, cette fonctionnalité n’est pas disponible dans les espaces de travail.
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 créez une instance Gestion des API, puis activez la fonctionnalité.
Créez une instance Gestion des API dans le portail comme vous le faites en temps normal. Accédez-y dans le portail.
Dans le menu de gauche, sous Sécurité, sélectionnez Identités managées.
Sous l’onglet Affecté par le système, changez le Statut sur Activé. Sélectionnez Enregistrer.
Azure PowerShell
Remarque
Nous vous recommandons d’utiliser le module Azure Az PowerShell pour interagir avec Azure. Pour bien démarrer, consultez Installer Azure PowerShell. Pour savoir comment migrer vers le module Az PowerShell, consultez Migrer Azure PowerShell depuis AzureRM vers Az.
Les étapes suivantes vous guident tout au long de la création d’une instance Gestion des API et de l’affectation d’une identité à l’aide d’Azure PowerShell.
Si vous avez besoin, installez Azure PowerShell en suivant les instructions du guide Azure PowerShell. Exécutez ensuite
Connect-AzAccountpour créer une connexion avec Azure.Utilisez le code suivant pour créer une instance avec une identité managée affectée par le système. Pour plus d’exemples d’utilisation d’Azure PowerShell avec Gestion des API, consultez des exemples PowerShell Gestion des API.
# 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 (ARM)
Vous pouvez créer une instance Gestion des API avec une identité affectée par le système en incluant la propriété suivante dans la définition de ressource du modèle ARM :
"identity" : {
"type" : "SystemAssigned"
}
Cette propriété indique à Azure de créer et de gérer l’identité de votre instance Gestion des API.
Par exemple, un modèle ARM complet peut ressembler à celui-ci :
{
"$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.
Remarque
Une instance Gestion des API peut avoir des identités affectées par le système et affectées par l’utilisateur. Dans ce scénario, la type propriété est SystemAssigned,UserAssigned.
Configurer l’accès Key Vault à l’aide d’une identité managée
Les configurations suivantes sont requises si vous souhaitez utiliser Gestion des API pour accéder aux certificats à partir d’un coffre de clés Azure.
Configurer l’accès au coffre de clés
- Dans le portail, allez à votre coffre-fort de clés.
- Dans le menu de gauche, sélectionnez Configuration d’Access. Notez le modèle d’autorisation configuré.
- 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 :
- Dans le menu de gauche, sélectionnez Stratégies d’accès.
- Dans la page Stratégies d’accès, sélectionnez + Créer.
- Sous l’onglet Autorisations , sous Autorisations secrètes, sélectionnez Obtenir et Liste, puis sélectionnez Suivant.
- Sous l’onglet Principal , sélectionnez Principal, recherchez le nom de la 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.
- 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 :
- Dans le menu de gauche, sélectionnez Contrôle d’accès (IAM) .
- Sur la page Contrôle d’accès (IAM), sélectionnez Ajout de l’attribution de rôle.
- Sous l’onglet Rôle, sélectionnez Utilisateur du certificat Key Vault.
- Sous l’onglet Membres, sélectionnez Identité managée>+ Sélectionner des membres.
- Dans la fenêtre Sélectionner des identités managées , 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 cliquez sur Sélectionner.
- 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, vous devez répondre à ces exigences :
Vous devez utiliser l’identité managée affectée par le système de 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 sur 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 réseau lors de la configuration de gestion des API dans un réseau virtuel.
Scénarios pris en charge qui utilisent l’identité assignée par le système
Voici quelques scénarios courants d’utilisation d’une identité managée affectée par le système dans Gestion des API Azure.
Obtenir un certificat TLS/SSL personnalisé pour l’instance Gestion des API à partir de Key Vault
Vous pouvez utiliser l’identité affectée par le système d’une instance Gestion des API pour récupérer des certificats TLS/SSL personnalisés stockés dans Key Vault. Vous pouvez ensuite affecter ces certificats à des domaines personnalisés dans l’instance Gestion des API. Prenez en compte ces considérations :
- Le type de contenu du secret doit être application/x-pkcs12. Pour plus d’informations, consultez les options de certificat de domaine.
- Vous devez utiliser le point de terminaison du secret de certificat Key Vault, qui contient le secret.
Important
Si vous ne fournissez pas la version objet du certificat, Gestion des API obtient automatiquement une version plus récente du certificat dans les quatre heures suivant sa mise à jour dans Key Vault.
L’exemple suivant montre un modèle ARM qui utilise l’identité managée affectée par le système d’une instance Gestion des API pour récupérer un certificat de domaine personnalisé à partir de Key Vault.
Prérequis
- Instance 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.
- Instance Key Vault dans le même groupe de ressources. L’instance doit héberger un certificat qui sera utilisé comme certificat de domaine personnalisé dans Gestion des API.
Le modèle contient les étapes suivantes.
- Mettez à jour les stratégies d’accès de l’instance Key Vault et autorisez l’instance Gestion des API à obtenir des secrets à partir de celui-ci.
- 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 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"
}
}]
}
}
}
]
}
Stocker et gérer des valeurs nommées à partir de Key Vault
Vous pouvez utiliser une identité managée affectée par le système pour accéder à Key Vault pour stocker et gérer les secrets à utiliser dans les stratégies gestion des API. 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 via la stratégie d’identité managée par l’authentification .
Se connecter aux ressources Azure derrière un pare-feu IP à l’aide d’une identité managée affectée par le système
API Management est un service Microsoft approuvé pour les ressources suivantes. Cet état approuvé permet au service de se connecter aux ressources suivantes derrière un pare-feu. Après avoir attribué explicitement le rôle Azure approprié à l’identité managée affectée par le système pour une instance de ressource, l’étendue d’accès de l’instance correspond au rôle Azure affecté à l’identité managée.
- Accès approuvé pour Key Vault
- Accès approuvé pour stockage Azure
- Accès approuvé pour Azure Services Bus
- Accès approuvé pour Azure Event Hubs
Journaliser des événements dans un Event Hub
Vous pouvez configurer et utiliser une identité managée affectée par le système pour accéder à un event Hub pour journaliser les événements à partir d’une instance gestion des API. Pour plus d’informations, consultez Comment consigner des événements dans Event Hubs dans Gestion des API Azure.
Créer une identité managée attribuée par l’utilisateur
Remarque
Vous pouvez associer une instance Gestion des API à 10 identités managées affectées par l’utilisateur.
Portail Azure
Pour configurer une identité managée dans le portail, vous devez d’abord créer une instance Gestion des API et créer une identité affectée par l’utilisateur. Effectuez ensuite les étapes suivantes.
Accédez à votre instance Gestion des API dans le portail.
Dans le menu de gauche, sous Sécurité, sélectionnez Identités managées.
Dans l’onglet Attribuée par l’utilisateur, sélectionnez Ajouter.
Recherchez l’identité que vous avez créée précédemment et sélectionnez-la. Sélectionnez Ajouter.
Azure PowerShell
Remarque
Nous vous recommandons d’utiliser le module Azure Az PowerShell pour interagir avec Azure. Pour bien démarrer, consultez Installer Azure PowerShell. Pour savoir comment migrer vers le module Az PowerShell, consultez Migrer Azure PowerShell depuis AzureRM vers Az.
Les étapes suivantes vous guident tout au long de la création d’une instance Gestion des API et de l’affectation d’une identité à l’aide d’Azure PowerShell.
Si vous avez besoin, installez Azure PowerShell en suivant les instructions du guide Azure PowerShell. Exécutez ensuite
Connect-AzAccountpour créer une connexion avec Azure.Utilisez le code suivant pour créer l’instance. Pour plus d’exemples d’utilisation d’Azure PowerShell avec Gestion des API, consultez des exemples PowerShell Gestion des API.
# 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
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 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
Modèle ARM
Vous pouvez créer une instance Gestion des API qui a une identité en incluant la propriété suivante dans la définition de ressource :
"identity": {
"type": "UserAssigned",
"userAssignedIdentities": {
"<RESOURCEID>": {}
}
}
L'ajout du type d'utilisateur attribué informe Azure d'utiliser l'identité utilisateur attribuée spécifiée pour votre instance.
Par exemple, un modèle ARM complet peut ressembler à celui-ci :
{
"$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.
Remarque
Une instance Gestion des API peut avoir des identités affectées par le système et affectées par l’utilisateur. Dans ce scénario, la type propriété serait SystemAssigned,UserAssigned.
Scénarios pris en charge utilisant des identités gérées assignées par l'utilisateur
Voici quelques scénarios courants d’utilisation d’une identité managée affectée par l’utilisateur dans Gestion des API Azure.
Obtenir un certificat TLS/SSL personnalisé pour l’instance Gestion des API à partir de Key Vault
Vous pouvez utiliser une identité affectée par l’utilisateur pour établir l’approbation entre une instance gestion des API et Key Vault. Cette approbation peut ensuite être utilisée pour récupérer des certificats TLS/SSL personnalisés stockés dans Key Vault. Vous pouvez ensuite affecter ces certificats à des domaines personnalisés dans l’instance Gestion des API.
Important
Si Pare-feu Key Vault est activé sur votre coffre de clés, vous ne pouvez pas utiliser une identité affectée par l’utilisateur pour l’accès à partir de Gestion des API. Vous pouvez utiliser l’identité affectée par le système à la place. Dans le pare-feu Key Vault, l’option Autoriser les services Microsoft approuvés à contourner cette option de pare-feu doit être activée.
Prenez en compte ces considérations :
- Le type de contenu du secret doit être application/x-pkcs12.
- Vous devez utiliser le point de terminaison du secret de certificat Key Vault, qui contient le secret.
Important
Si vous ne fournissez pas la version objet du certificat, Gestion des API obtient automatiquement une version plus récente du certificat dans les quatre heures suivant sa mise à jour dans Key Vault.
Stocker et gérer des valeurs nommées à partir de Key Vault
Vous pouvez utiliser une identité managée affectée par l’utilisateur pour accéder à Key Vault pour stocker et gérer les secrets à utiliser dans les stratégies gestion des API. Pour plus d’informations, consultez Utiliser des valeurs nommées dans les stratégies Gestion des API Azure.
Remarque
Si Pare-feu Key Vault est activé sur votre coffre de clés, vous ne pouvez pas utiliser une identité affectée par l’utilisateur pour l’accès à partir de Gestion des API. Vous pouvez utiliser l’identité affectée par le système à la place. Dans le pare-feu Key Vault, l’option Autoriser les services Microsoft approuvés à contourner cette option de pare-feu doit être activée.
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 via la stratégie d’identité managée par l’authentification .
Journaliser des événements dans un Event Hub
Vous pouvez configurer et utiliser une identité managée affectée par l’utilisateur pour accéder à un event Hub pour journaliser les événements à partir d’une instance 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 un modèle ARM de la même façon 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".
La suppression d’une identité affectée par le système de cette façon le supprime également de l’ID Microsoft Entra. 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 d’un modèle ARM, mettez à jour cette section :
"identity": {
"type": "None"
}
Important
Si une instance Gestion des API est configurée avec un certificat SSL personnalisé à partir de Key Vault et que vous essayez de désactiver une identité managée, la requête échoue.
Vous pouvez résoudre ce problème en passant d’un certificat Key Vault à un certificat encodé en ligne, puis en désactivant l’identité managée. Pour plus d’informations, consultez Configurer un nom de domaine personnalisé.