Usare le identità gestite in Gestione API di Azure

SI APPLICA A: Tutti i livelli di Gestione API

Questo articolo illustra come creare un'identità gestita per un'istanza di Gestione API di Azure e come usarla per accedere ad altre risorse. Un'identità gestita generata da Microsoft Entra ID consente all'istanza di Gestione API di accedere in modo semplice e sicuro ad altre risorse protette di Microsoft Entra, ad esempio Azure Key Vault. Azure gestisce questa identità, quindi non è necessario effettuare il provisioning o ruotare i segreti. Per altre informazioni sulle identità gestite, vedere Informazioni sulle identità gestite per le risorse di Azure.

È possibile concedere due tipi di identità a un'istanza di Gestione API:

• Un'identità assegnata dal sistema viene associata al servizio e viene eliminata in caso di eliminazione. Il servizio può avere una sola identità assegnata dal sistema.
• Un'identità assegnata dall'utente è una risorsa di Azure autonoma che può essere assegnata al servizio. Il servizio può avere più identità assegnate dall'utente.

Nota

Le identità gestite sono specifiche del tenant di Microsoft Entra in cui è ospitata la sottoscrizione di Azure. Non vengono aggiornate se una sottoscrizione viene spostata in una directory diversa. Se viene spostata una sottoscrizione, sarà necessario ricreare e configurare le identità.

Nota

Attualmente, questa funzionalità non è disponibile nelle aree di lavoro.

Creare un'identità gestita assegnata dal sistema

Azure portal

Per configurare un'identità gestita nel portale di Azure, creare prima un'istanza di Gestione API e quindi abilitare la funzionalità.

1. Creare un'istanza di Gestione API nel portale come di consueto. Passare al portale.

2. Nel menu a sinistra, in Sicurezzaselezionare Identità gestite.

3. All'interno della scheda Assegnata dal sistema impostare Stato su Attivato. Seleziona Salva.

   

Azure PowerShell

Nota

È consigliabile usare il modulo Azure Az PowerShell per interagire con Azure. Per iniziare, vedere Installare Azure PowerShell. Per informazioni su come eseguire la migrazione al modulo AZ PowerShell, vedere Eseguire la migrazione di Azure PowerShell da AzureRM ad Az.

La procedura seguente illustra come creare un'istanza di Gestione API e assegnarla un'identità usando Azure PowerShell.

1. Se necessario, installare Azure PowerShell usando le istruzioni riportate nella guida di Azure PowerShell. Eseguire quindi Connect-AzAccount per creare una connessione con Azure.

2. Usare il codice seguente per creare l'istanza con un'identità gestita assegnata dal sistema. Per altri esempi di come usare Azure PowerShell con un'istanza di Gestione API, vedere Esempi di PowerShell per Gestione 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
   

È anche possibile aggiornare un'istanza esistente per creare l'identità:

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

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

Modello di Azure Resource Manager

È possibile creare un'istanza di Gestione API con un'identità assegnata dal sistema includendo la proprietà seguente nella definizione della risorsa:

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

Questa proprietà indica ad Azure di creare e gestire l'identità per l'istanza di Gestione API.

Ad esempio, un modello completo di Azure Resource Manager può essere simile al seguente:

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

Quando l'istanza viene creata, ha le proprietà aggiuntive seguenti:

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

La proprietà tenantId identifica il tenant Microsoft Entra a cui appartiene l'identità. La proprietà principalId è un identificatore univoco per la nuova identità dell'istanza. All'interno di Microsoft Entra ID, l'entità servizio ha lo stesso nome assegnato all'istanza di Gestione API.

Nota

Un’istanza di Gestione API può avere contemporaneamente sia identità assegnate dal sistema che assegnate dall'utente. In questo caso, la proprietà type sarebbe SystemAssigned,UserAssigned.

Configurare Key Vault l'accesso usando un'identità gestita

Le configurazioni seguenti sono necessarie per Gestione API per accedere ai segreti e ai certificati da un insieme di credenziali delle chiavi di Azure.

Configurare l'accesso all'insieme di credenziali delle chiavi

1. Nel portale passare all'insieme di credenziali delle chiavi.

2. Nel menu a sinistra, selezionare Configurazione di accesso e prendere nota del modello di autorizzazione configurato.

3. A seconda del modello di autorizzazione, configurare un criterio di accesso dell'insieme di credenziali delle chiavi o un accesso al controllo degli accessi in base al ruolo di Azure per un'identità gestita di Gestione API.

   Per aggiungere un criterio di accesso dell'insieme di credenziali delle chiavi:
   

   1. Selezionare Criteri di accesso nel menu a sinistra.
   2. Nella pagina Criteri di accesso, selezionare + Crea.
   3. Nella scheda Autorizzazioni, in Autorizzazioni segrete, selezionare Ottieni ed Elenco, quindi selezionare Avanti.
   4. Nella scheda Entità di sicurezza, Seleziona entità di sicurezza , cercare il nome della risorsa dell'identità gestita e quindi selezionare Avanti. Se si usa un'identità assegnata dal sistema, l'entità è il nome dell'istanza di Gestione API.
   5. Selezionare di nuovo Avanti. Nella scheda Rivedi e crea selezionare Crea.

   Per configurare l'accesso al controllo degli accessi in base al ruolo di Azure:
   

   1. Nel menu a sinistra selezionare Controllo di accesso (IAM).
   2. Nella pagina Controllo di accesso (IAM), selezionare Aggiungi assegnazione di ruolo.
   3. Nella scheda Ruolo, selezionare Utente dei certificati Key Vault.
   4. Nella scheda Membri, selezionare Identità gestita>+ Seleziona membri.
   5. Nella pagina Seleziona identità gestita, selezionare l'identità gestita assegnata dal sistema o un'identità gestita assegnata dall'utente associata all'istanza di Gestione API e quindi selezionare Seleziona.
   6. Seleziona Rivedi + assegna.

Requisiti per il firewall di Key Vault

Se il firewall di Key Vault è abilitato nell'insieme di credenziali delle chiavi, sono necessari requisiti aggiuntivi:

• Per accedere all'insieme di credenziali delle chiavi, è necessario usare l'identità gestita assegnata dal sistema dell'istanza di Gestione API.

• Nel firewall di Key Vault, abilitare l'opzione Consenti ai servizi Microsoft attendibili di ignorare questo firewall.

• Assicurarsi che l'indirizzo IP del client locale sia autorizzato ad accedere temporaneamente all'insieme di credenziali delle chiavi mentre si seleziona un certificato o un segreto da aggiungere a Gestione API di Azure. Per altre informazioni, vedere Configurare le impostazioni di rete di Azure Key Vault.

  Dopo aver completato la configurazione, è possibile bloccare l'indirizzo client nel firewall di insieme di credenziali delle chiavi.

Requisiti della rete virtuale

Se l'istanza di Gestione API viene distribuita in una rete virtuale, configurare anche le impostazioni di rete seguenti:

• Abilitare un endpoint di servizio in Azure Key Vault nella subnet di Gestione API.
• Configurare una regola del gruppo di sicurezza di rete (NSG) per consentire il traffico in uscita ai tag del servizio AzureKeyVault e AzureActiveDirectory.

Per informazioni dettagliate, vedere Configurazione di rete durante la configurazione di Gestione API di Azure in una rete virtuale.

Scenari supportati con l'identità assegnata dal sistema

Ottenere un certificato TLS/SSL personalizzato per l'istanza di Gestione API da Azure Key Vault

È possibile usare l'identità assegnata dal sistema di un'istanza di Gestione API per recuperare i certificati TLS/SSL personalizzati archiviati in Azure Key Vault. È quindi possibile assegnare questi certificati ai domini personalizzati nell'istanza di Gestione API. Tenere presenti queste considerazioni:

• Il contenuto del segreto deve essere di tipo application/x-pkcs12. Altre informazioni sui requisiti dei certificati di dominio personalizzati.
• Usare l'endpoint segreto del certificato di Key Vault, che contiene il segreto.

Importante

Se non si specifica la versione dell'oggetto del certificato, Gestione API otterrà automaticamente la versione più recente del certificato entro quattro ore dall'aggiornamento in Key Vault.

L'esempio seguente illustra un modello di Azure Resource Manager che usa l'identità gestita assegnata dal sistema di un'istanza del servizio Gestione API per recuperare un certificato di dominio personalizzato da Key Vault.

Prerequisiti

• Istanza del servizio Gestione API configurata con un'identità gestita assegnata dal sistema. Per creare l'istanza, è possibile usare un modello di avvio rapido di Azure.
• Un'istanza di Azure Key Vault nello stesso gruppo di risorse, che ospita un certificato che verrà usato come certificato di dominio personalizzato in Gestione API.

Il modello seguente contiene i passaggi seguenti.

1. Aggiornare i criteri di accesso dell'istanza di Azure Key Vault e consentire all'istanza di Gestione API di ottenere i segreti da essa.
2. Aggiornare l'istanza di Gestione API impostando un nome di dominio personalizzato tramite il certificato ottenuto dall'istanza di Key Vault.

Quando si esegue il modello, specificare i valori dei parametri appropriati per l'ambiente.

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

Archiviare e gestire i valori denominati da Azure Key Vault

È possibile usare un'identità gestita assegnata dal sistema per accedere ad Azure Key Vault per archiviare e gestire i segreti da usare nei criteri di Gestione API. Per altre informazioni, vedere Usare valori denominati nei criteri di Gestione API di Azure.

Eseguire l'autenticazione in un back-end usando un'identità di Gestione API

È possibile usare l'identità assegnata dal sistema per eseguire l'autenticazione a un servizio back-end tramite i criteri di authentication-managed-identity.

Connettersi alle risorse di Azure dietro il firewall IP usando l'identità gestita assegnata dal sistema

Gestione API è un servizio Microsoft attendibile per le risorse seguenti. In questo modo il servizio può connettersi alle risorse seguenti dietro un firewall. Dopo aver assegnato in modo esplicito il ruolo di Azure appropriato all'identità gestita assegnata dal sistema per tale istanza di risorsa, l'ambito di accesso per l'istanza corrisponde al ruolo di Azure assegnato all'identità gestita.

Servizio di Azure	Collega
Azure Key Vault	Trusted-access-to-azure-key-vault
Archiviazione di Azure	Trusted-access-to-azure-storage
Bus di servizio di Azure	Trusted-access-to-azure-service-bus
Hub eventi di Azure	Trusted-access-to-azure-event-hub

Registrare eventi in un hub eventi

È possibile configurare e usare un'identità gestita assegnata dal sistema per accedere a un hub eventi per registrare gli eventi da un'istanza di Gestione API. Per altre informazioni, vedere Come registrare gli eventi in Hub eventi di Azure in Gestione API di Azure.

Creare un'identità gestita assegnata dall'utente

Nota

È possibile associare un'istanza di Gestione API a un massimo di 10 identità gestite assegnate dall'utente.

Azure portal

Per configurare un'identità gestita nel portale, creare prima un'istanza di Gestione API e creare un'identità assegnata dall'utente. Abilitare quindi la funzionalità.

1. Creare un'istanza di Gestione API nel portale come di consueto. Passare al portale.

2. Nel menu a sinistra, in Sicurezzaselezionare Identità gestite.

3. Nella scheda Assegnata dall'utente selezionare Aggiungi.

4. Cercare l'identità creata in precedenza e selezionarla. Selezionare Aggiungi.

   

Azure PowerShell

Nota

È consigliabile usare il modulo Azure Az PowerShell per interagire con Azure. Per iniziare, vedere Installare Azure PowerShell. Per informazioni su come eseguire la migrazione al modulo AZ PowerShell, vedere Eseguire la migrazione di Azure PowerShell da AzureRM ad Az.

La procedura seguente illustra come creare un'istanza di Gestione API e assegnarla un'identità usando Azure PowerShell.

1. Se necessario, installare Azure PowerShell seguendo le istruzioni presenti nella guida di Azure PowerShell. Eseguire quindi Connect-AzAccount per creare una connessione con Azure.

2. Usare il codice seguente per creare l'istanza. Per altri esempi di come usare Azure PowerShell con un'istanza di Gestione API, vedere Esempi di PowerShell per Gestione API.

   # 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
   

È anche possibile aggiornare un servizio esistente per assegnare un'identità al servizio:

# 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

Modello di Azure Resource Manager

È possibile creare un'istanza di Gestione API con un'identità includendo la proprietà seguente nella definizione della risorsa:

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

L'aggiunta del tipo assegnato dall'utente indica ad Azure di usare l'identità assegnata dall'utente specificata per l'istanza.

Ad esempio, un modello completo di Azure Resource Manager può essere simile al seguente:

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

Quando il servizio viene creato, ha le proprietà aggiuntive seguenti:

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

La proprietà principalId è un identificatore univoco per l'identità usata per l'amministrazione di Microsoft Entra. La proprietà clientId è un identificatore univoco per la nuova identità dell'applicazione usata per specificare l'identità da usare durante le chiamate di runtime.

Nota

Un’istanza di Gestione API può avere contemporaneamente sia identità assegnate dal sistema che assegnate dall'utente. In questo caso, la proprietà type sarebbe SystemAssigned,UserAssigned.

Scenari supportati con l'identità gestita assegnata dall'utente

Ottenere un certificato TLS/SSL personalizzato per l'istanza di Gestione API da Azure Key Vault

È possibile usare un'identità assegnata dall'utente per stabilire un trust tra un'istanza di Gestione API e Azure Key Vault. Questo trust può quindi essere usato per recuperare certificati TLS/SSL personalizzati archiviati in Azure Key Vault. È quindi possibile assegnare questi certificati ai domini personalizzati nell'istanza di Gestione API.

Importante

Se il firewall di Key Vault è abilitato nell'insieme di credenziali delle chiavi, non è possibile usare un'identità assegnata dall'utente per l'accesso da Gestione API. È invece possibile usare l'identità assegnata dal sistema. Nel firewall dell'insieme di credenziali delle chiavi è necessario abilitare anche l'opzione Consenti ai servizi Microsoft attendibili di ignorare questo firewall.

Tenere presenti queste considerazioni:

• Il contenuto del segreto deve essere di tipo application/x-pkcs12.
• Usare l'endpoint segreto del certificato di Key Vault, che contiene il segreto.

Importante

Se non si specifica la versione dell'oggetto del certificato, Gestione API otterrà automaticamente la versione più recente del certificato entro quattro ore dall'aggiornamento in Key Vault.

Archiviare e gestire i valori denominati da Azure Key Vault

È possibile usare un'identità gestita assegnata dall'utente per accedere ad Azure Key Vault per archiviare e gestire i segreti da usare nei criteri di Gestione API. Per altre informazioni, vedere Usare valori denominati nei criteri di Gestione API di Azure.

Nota

Se il firewall di Key Vault è abilitato nell'insieme di credenziali delle chiavi, non è possibile usare un'identità assegnata dall'utente per l'accesso da Gestione API. È invece possibile usare l'identità assegnata dal sistema. Nel firewall dell'insieme di credenziali delle chiavi è necessario abilitare anche l'opzione Consenti ai servizi Microsoft attendibili di ignorare questo firewall.

Eseguire l'autenticazione in un back-end usando un'identità assegnata dall'utente

È possibile usare l'identità assegnata dall'utente per eseguire l'autenticazione a un servizio back-end tramite i criteri di authentication-managed-identity.

Registrare eventi in un hub eventi

È possibile configurare e usare un'identità gestita assegnata dall'utente per accedere a un hub eventi per registrare gli eventi da un'istanza di Gestione API. Per altre informazioni, vedere Come registrare gli eventi in Hub eventi di Azure in Gestione API di Azure.

Rimuovere un'identità

È possibile rimuovere un'identità assegnata dal sistema disabilitando la funzionalità tramite il portale o il modello di Azure Resource Manager nello stesso modo in cui è stata creata. Le identità assegnate dall'utente possono essere rimosse separatamente. Per rimuovere tutte le identità, impostare il tipo di identità su "None".

La rimozione di un'identità assegnata dal sistema in questo modo ne comporta l'eliminazione anche da Microsoft Entra ID. Anche le identità assegnate dal sistema vengono rimosse automaticamente dall'ID Microsoft Entra quando l'istanza di Gestione API viene eliminata.

Per rimuovere tutte le identità usando il modello di Azure Resource Manager, aggiornare questa sezione:

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

Importante

Se un'istanza di Gestione API è configurata con un certificato SSL personalizzato da Key Vault e si tenta di disabilitare un'identità gestita, la richiesta avrà esito negativo.

È possibile sbloccarsi passando da un certificato di Azure Key Vault a un certificato codificato inline e quindi disabilitando l'identità gestita. Per altre informazioni, vedere Configurare un nome di dominio personalizzato.

Passaggi successivi

Altre informazioni sulle identità gestite per le risorse di Azure

• Informazioni sulle identità gestite per le risorse di Azure
• Modelli di Gestione risorse di Azure
• Eseguire l'autenticazione con un'identità gestita in un criterio