Condividi tramite

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 a Gestione API di accedere facilmente e in modo sicuro ad altre risorse protette da Microsoft Entra, ad esempio Azure Key Vault. Azure gestisce queste identità, quindi non è necessario approvvigionare o modificare periodicamente 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, è necessario ricreare e riconfigurare le identità.

Nota

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

Creare un'identità gestita assegnata dal sistema

Portale di Azure

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

  1. Creare un'istanza di Gestione API nel portale come di consueto. Vai a esso nel portale.

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

  3. Nella scheda Assegnata dal sistema impostare Statosu Sì. Seleziona Salva.

    Screenshot che mostra come abilitare un'identità gestita assegnata dal sistema.

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.

I passaggi seguenti portano alla creazione di un'istanza di Gestione API e all'assegnazione di un'identità tramite Azure PowerShell.

  1. Se necessario, installare Azure PowerShell seguendo 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 un'istanza con un'identità gestita assegnata dal sistema. Per altri esempi di come usare Azure PowerShell con 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 (modello di ARM)

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

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

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

Ad esempio, un modello ARM completo potrebbe 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 identità assegnate dal sistema e assegnate dall'utente. In questo scenario, la type proprietà è SystemAssigned,UserAssigned.

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

Se si vuole usare Gestione API per accedere ai certificati da un insieme di credenziali delle chiavi di Azure, sono necessarie le configurazioni seguenti.

Configurare l'accesso all'insieme di credenziali delle chiavi

  1. Nel portale, vai al tuo gestione delle chiavi.
  2. Nel menu a sinistra selezionare Configurazione di accesso. Si noti il 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 una policy di accesso del Key Vault:

  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 Recupera ed Elenco e quindi selezionare Avanti.
  4. Nella scheda Entità selezionare 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 RBAC 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 finestra Seleziona identità gestite selezionare l'identità gestita assegnata dal sistema o un'identità gestita assegnata dall'utente associata all'istanza di Gestione API e quindi fare clic su Seleziona.
  6. Seleziona Rivedi + assegna.

Requisiti per il firewall di Key Vault

Se il firewall di Key Vault è abilitato nella tua Key Vault, devi soddisfare questi requisiti:

  • Per accedere al Key Vault, è necessario usare l'identità gestita assegnata dal sistema dell'istanza di API Management.

  • 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 del cliente nel firewall del Key Vault.

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 per 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 in una rete virtuale.

Scenari supportati che usano l'identità assegnata dal sistema

Di seguito sono riportati alcuni scenari comuni per l'uso di un'identità gestita assegnata dal sistema in Gestione API di Azure.

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

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

  • Il contenuto del segreto deve essere di tipo application/x-pkcs12. Per altre informazioni, vedere Opzioni del certificato di dominio.
  • È necessario 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 ottiene automaticamente qualsiasi versione più recente del certificato entro quattro ore dall'aggiornamento in Key Vault.

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

Prerequisiti

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

Il modello contiene i passaggi seguenti.

  1. Aggiornare i criteri di accesso dell'istanza di 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 ottenuto dall'istanza di Key Vault.

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

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

Archiviare e gestire i valori denominati da Key Vault

È possibile usare un'identità gestita assegnata dal sistema per accedere a 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 autenticarsi a un servizio back-end tramite la politica di autenticazione gestita dall'identità.

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

Gestione API è un servizio Microsoft attendibile per le risorse seguenti. Questo stato attendibile consente al servizio di 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 un'istanza di risorsa, l'ambito di accesso per l'istanza corrisponde al ruolo di Azure assegnato all'identità gestita.

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

Creare un'identità gestita assegnata dall'utente

Nota

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

Portale di Azure

Per configurare un'identità gestita nel portale, è prima necessario creare un'istanza di Gestione API e creare un'identità assegnata dall'utente. Completare quindi i passaggi seguenti.

  1. Vai alla tua istanza di Gestione API nel 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.

    Screenshot che mostra come abilitare un'identità gestita assegnata dall'utente.

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.

I passaggi seguenti portano alla creazione di un'istanza di Gestione API e all'assegnazione di un'identità tramite Azure PowerShell.

  1. Se necessario, installare Azure PowerShell seguendo 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. Per altri esempi di come usare Azure PowerShell con 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 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

È 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 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

Modello ARM

È 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 informa Azure di usare l'identità assegnata dall'utente specificata per l'istanza.

Ad esempio, un modello ARM completo potrebbe 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 identità assegnate dal sistema e assegnate dall'utente. In questo scenario, la type proprietà sarà SystemAssigned,UserAssigned.

Scenari supportati che usano identità gestite assegnate dall'utente

Di seguito sono riportati alcuni scenari comuni per l'uso di un'identità gestita assegnata dall'utente in Gestione API di Azure.

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

È possibile usare un'identità assegnata dall'utente per stabilire un trust tra un'istanza di Gestione API e Key Vault. Questo trust può quindi essere usato per recuperare certificati TLS/SSL personalizzati archiviati in 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 di Key Vault è necessario abilitare l'opzione Consenti ai servizi Microsoft attendibili di ignorare questo firewall .

Prendere in considerazione queste considerazioni:

  • Il contenuto del segreto deve essere di tipo application/x-pkcs12.
  • È necessario 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 ottiene automaticamente qualsiasi versione più recente del certificato entro quattro ore dall'aggiornamento in Key Vault.

Archiviare e gestire i valori denominati da Key Vault

È possibile usare un'identità gestita assegnata dall'utente per accedere a 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 di Key Vault è necessario abilitare 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 autenticarsi a un servizio back-end tramite la politica di autenticazione identità gestita.

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 un modello di 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 elimina anche dall'ID Microsoft Entra. 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 un modello di ARM, 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 ha esito negativo.

Per risolvere questo problema, passare da un certificato di Key Vault a un certificato con codifica inline e quindi disabilitare l'identità gestita. Per altre informazioni, vedere Configurare un nome di dominio personalizzato.

Contenuti correlati