Usare le identità gestite in Azure Gestione API

Questo articolo illustra come creare un'identità gestita per un'istanza di Azure Gestione API 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 Che cosa sono le 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 aggiornati se una sottoscrizione viene spostata in una directory diversa. Se viene spostata una sottoscrizione, sarà necessario ricreare e configurare le identità.

Creare un'identità gestita assegnata dal sistema

Azure portal

Per configurare un'identità gestita nella 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 Sicurezza, selezionare Identità gestite.

  3. Nella scheda Assegnata dal sistema impostare Stato su . Seleziona Salva.

    Selections for enabling a system-assigned managed identity

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 nella guida di Azure PowerShell. Connect-AzAccount Eseguire quindi 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 Gestione API esempi di 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
    

È 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 tenantId proprietà identifica il tenant microsoft Entra a cui appartiene l'identità. La principalId proprietà è 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 type proprietà sarà SystemAssigned,UserAssigned.

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

Le configurazioni seguenti sono necessarie per Gestione API di 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 l'accesso controllo degli accessi in base al ruolo di Azure per un'identità gestita Gestione API.

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

    1. Nel menu a sinistra selezionare Criteri di accesso.
    2. Nella pagina Criteri di accesso selezionare + Crea.
    3. Nella scheda Autorizzazioni, in Autorizzazioni segrete, selezionare Recupera ed Elenco e quindi selezionare Avanti.
    4. Nella scheda Entità selezionare l'entità, 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 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 segreti dell'insieme di credenziali delle chiavi.
    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 dell'insieme di credenziali delle chiavi 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 ad Azure Gestione API. 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 dell'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:

Per informazioni dettagliate, vedere Configurazione di rete durante la configurazione di Azure Gestione API 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 tipo di contenuto del segreto deve essere 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.
  2. Aggiornare l'istanza di Gestione API impostando un nome di dominio personalizzato tramite il certificato 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 Azure Gestione API.

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

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

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 Collegamento
Insieme di credenziali chiave di Azure 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 per Hub eventi di Azure in Azure Gestione API.

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 Sicurezza, selezionare Identità gestite.

  3. Nella scheda Assegnata dall'utente selezionare Aggiungi.

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

    Selections for enabling a user-assigned managed identity

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 nella guida di Azure PowerShell. Connect-AzAccount Eseguire quindi per creare una connessione con Azure.

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

È 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 principalId proprietà è un identificatore univoco per l'identità usata per l'amministrazione di Microsoft Entra. La clientId proprietà è 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 type proprietà sarà 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 tipo di contenuto del segreto deve essere 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.

Per il modello completo, vedere Gestione API con SSL basato su Key Vault usando l'identità assegnata dall'utente.

In questo modello si distribuiranno:

  • Istanza di Azure Gestione API
  • Identità gestita assegnata dall'utente di Azure
  • Azure Key Vault per l'archiviazione del certificato SSL/TLS

Per eseguire automaticamente la distribuzione, fare clic sul pulsante seguente:

Deploy to Azure

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 Azure Gestione API.

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 autenticazione gestita-identità .

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 per Hub eventi di Azure in Azure Gestione API.

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 lo eliminerà anche dall'ID Microsoft Entra. Le identità assegnate dal sistema vengono rimosse automaticamente anche 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: