Usare le chiavi di accesso in Funzioni di Azure

Funzioni di Azure consente di usare chiavi segreto per rendere più difficile l'accesso agli endpoint della funzione. Questo articolo descrive i vari tipi di chiavi di accesso supportate da Funzioni e il modo in cui usare le chiavi di accesso.

Sebbene le chiavi di accesso forniscano una misura di mitigazione contro l'accesso indesiderato, è consigliabile prendere in considerazione altre opzioni per proteggere gli endpoint HTTP nell'ambiente di produzione. Ad esempio, è sconsigliabile distribuire i segreti condivisi in un’app pubblica. Se la funzione viene chiamata da un client pubblico, è consigliabile implementare questi o altri meccanismi di sicurezza:

• Abilitare l'autenticazione/autorizzazione di Servizio app di Azure
• Usare Gestione API di Azure (APIM) per autenticare le richieste
• Distribuire l'app per le funzioni in una rete virtuale
• Distribuire l'app per le funzioni in isolamento

Le chiavi di accesso forniscono la base per l'autorizzazione HTTP nelle funzioni attivate da HTTP. Per altre informazioni, vedere Livello di autorizzazione.

Informazioni sulle chiavi

L'ambito di una chiave di accesso e le azioni supportate dipendono dal tipo di chiave di accesso.

Tipo di chiave	Nome chiave	Livello di autenticazione HTTP	Descrizione
Funzione	default o definito dall'utente	function	Consente l'accesso a un solo endpoint di funzione specifico.
Host	default o definito dall'utente	function	Consente l'accesso a tutti gli endpoint di funzione in un'app per le funzioni.
Generale	_master	admin	Chiave host speciale che fornisce anche l'accesso amministrativo alle API REST di runtime in un'app per le funzioni. Questa chiave non può essere revocata. Poiché la chiave master concede autorizzazioni elevate nell'app per le funzioni, è consigliabile non condividere questa chiave con terzi o distribuirla in applicazioni client native.
Di sistema	Dipende dall'estensione	n/d	Le estensioni specifiche potrebbero richiedere una chiave gestita dal sistema per accedere agli endpoint del webhook. Le chiavi di sistema sono progettate per endpoint di funzioni specifici per l'estensione chiamati da componenti interni. Ad esempio, per il trigger della Griglia di eventi è necessario che la sottoscrizione usi una chiave di sistema durante la chiamata all'endpoint del trigger. Durable Functions usa anche chiavi di sistema per chiamare le API dell'estensione Durable Task. Le chiavi di sistema possono essere create solo da estensioni specifiche e non è possibile impostarne i relativi valori in modo esplicito. Analogamente ad altre chiavi, è possibile generare un nuovo valore per la chiave nel portale o usando le API della chiave.

Ogni chiave viene denominata per riferimento ed esiste una chiave predefinita (denominata default) a livello di funzione e di host. Le chiavi di funzione hanno la precedenza sulle chiavi host. Se sono definite due chiavi con lo stesso nome, viene usata sempre la chiave di funzione.

La tabella seguente confronta gli utilizzi per diversi tipi di chiavi di accesso:

Azione	Ambito	Tipo di chiave
Eseguire una funzione	Funzione specifica	Funzione
Eseguire una funzione	Qualsiasi funzione	Funzione o host
Chiamare un endpoint admin	App per le funzioni	Solo master
Chiamare le API dell'estensione Durable Task	App per le funzioni*	System
Chiamare un webhook specifico per l'estensione (interno)	App per le funzioni*	operativo

^*Ambito determinato dall'estensione.

Requisiti chiave

In Funzioni, le chiavi di accesso sono matrici a 32 byte generate in modo casuale e codificate come stringhe base-64 sicure per gli URL. Anche se è possibile generare chiavi di accesso personalizzate e usarle con Funzioni, è consigliabile consentire a Funzioni di generare automaticamente tutte le chiavi di accesso.

Le chiavi di accesso generate da Funzioni includono valori di firma e checksum speciali, che indicano il tipo di chiave di accesso e che è stata generata da Funzioni di Azure. La presenza di questi componenti aggiuntivi nella chiave stessa rende molto più semplice determinare l'origine di questi tipi di segreti durante l'analisi della sicurezza e altri processi automatizzati.

Per consentire a Funzioni di generare automaticamente le chiavi, non fornire la chiave value a nessuna delle API utilizzabili per generare chiavi.

Gestire l'archiviazione delle chiavi

Le chiavi vengono archiviate come parte dell'app per le funzioni in Azure e crittografate inattive. Per impostazione predefinita, le chiavi sono archiviate in un contenitore di archiviazione BLOB nell'account fornito dall'impostazione AzureWebJobsStorage. È possibile usare l'impostazione AzureWebJobsSecretStorageType per sostituire questo comportamento predefinito e archiviare le chiavi in una delle posizioni alternative:

Ufficio	Valore	Descrizione
Un secondo account di archiviazione	blob	Archivia le chiavi nell'archiviazione BLOB in un account di archiviazione diverso da quello usato dal runtime di Funzioni. L'account e il contenitore specifici usati sono definiti da un URL di firma di accesso condiviso (SAS) indicato nell'impostazione AzureWebJobsSecretStorageSas. Quando l'URL SAS cambia, è necessario mantenere l'impostazione AzureWebJobsSecretStorageSas.
Azure Key Vault	keyvault	L'insieme di credenziali delle chiavi in AzureWebJobsSecretStorageKeyVaultUri viene usato per archiviare le chiavi.
File system	files	Le chiavi vengono salvate in modo permanente nel file system locale, ovvero l'impostazione predefinita in Funzioni v1.x. L'archiviazione del file system non è consigliata.
Segreti di Kubernetes	kubernetes	Il set di risorse in AzureWebJobsKubernetesSecretName viene usato per archiviare le chiavi. Supportato solo quando l'app per le funzioni viene distribuita in Kubernetes. Azure Functions Core Tools genera automaticamente i valori quando lo si usa per implementare l'app in un cluster Kubernetes.

Quando si usa Key Vault per l'archiviazione delle chiavi, le impostazioni dell'app necessarie dipendono dal tipo di identità gestita, assegnata dal sistema o assegnata dall'utente.

Nome impostazione	Assegnata dal sistema	Assegnata dall'utente	Registrazione app
AzureWebJobsSecretStorageKeyVaultUri	✓	✓	✓
AzureWebJobsSecretStorageKeyVaultClientId	X	✓	✓
AzureWebJobsSecretStorageKeyVaultClientSecret	X	X	✓
AzureWebJobsSecretStorageKeyVaultTenantId	X	X	✓

Usare le chiavi di accesso

Le funzioni attivate da HTTP possono in genere essere chiamate usando un URL nel formato: https://<APP_NAME>.azurewebsites.net/api/<FUNCTION_NAME>. Quando il livello di autorizzazione di una determinata funzione è impostato su un valore diverso da anonymous, nella richiesta è necessario specificare anche una chiave di accesso. La chiave di accesso può essere specificata nell'URL usando la stringa di query ?code=, o nell'intestazione della richiesta (x-functions-key). Per altre informazioni, vedere Autorizzazione della chiave di accesso.

Per accedere alle API REST di runtime (in /admin/), è necessario specificare la chiave master (_master) nell'intestazione della richiesta x-functions-key. È possibile rimuovere gli endpoint di amministrazione usando la proprietà del sito functionsRuntimeAdminIsolationEnabled.

Ottenere le chiavi di accesso alle funzioni

È possibile ottenere chiavi di funzione e host a livello di codice usando queste API di Azure Resource Manager:

• Elencare le chiavi di funzione
• Elencare le chiavi host
• Elencare lo slot delle chiavi di funzione
• Elencare lo slot delle chiavi host.

Per informazioni su come chiamare le API di Azure Resource Manager, vedere informazioni di riferimento sull'API REST di Azure.

Per ottenere le chiavi di accesso senza dover usare le API REST è possibile usare questi metodi.

Azure portal

1. Accedere al portale di Azure e quindi cercare e selezionare App per le funzioni.

2. Selezionare l'app per le funzioni che si desidera usare.

3. Nel riquadro sinistro espandere Funzioni, quindi selezionare Chiavi dell'app.

   Viene visualizzata la pagina Chiavi dell'app. In questa pagina vengono visualizzate le chiavi host, che possono essere usate per accedere a qualsiasi funzione nell'app. Viene visualizzata anche la chiave di sistema, che consente a chiunque l'accesso a livello di amministratore a tutte le API dell'app per le funzioni.

È inoltre possibile avvalersi di privilegi minimi usando la chiave per una funzione specifica. È possibile ottenere chiavi specifiche della funzione dalla scheda Chiavi funzione di una specifica funzione attivata da HTTP.

Interfaccia della riga di comando di Azure

Eseguire lo script seguente in Azure Cloud Shell, il cui output è la chiave host default, che può essere usata per accedere a qualsiasi funzione attivata tramite HTTP nell'app per le funzioni.

az functionapp keys list --resource-group <RESOURCE_GROUP> --name <APP_NAME> --query functionKeys.default --output tsv

In questo script, sostituire <RESOURCE_GROUP> e <APP_NAME> rispettivamente con il gruppo di risorse e il nome dell'app per le funzioni.

Poiché l'output contiene informazioni sensibili, non rendere persistente l'output né proteggere gli output dei file persistenti.

Azure PowerShell

Eseguire lo script seguente, il cui output è la chiave host default, che può essere usata per accedere a qualsiasi funzione attivata tramite HTTP nell'app per le funzioni.

$subName = '<SUBSCRIPTION_ID>'
$rGroup = '<RESOURCE_GROUP>'
$appName = '<APP_NAME>'
$path = "/subscriptions/$((Get-AzContext).Subscription.Id)/resourceGroups/$rGroup/providers/Microsoft.Web/sites/$appName/host/default/listKeys?api-version=2018-11-01"
((Invoke-AzRestMethod -Path $path -Method POST).Content | ConvertFrom-JSON).functionKeys.default

In questo script, sostituire <RESOURCE_GROUP> e <APP_NAME> rispettivamente con il gruppo di risorse e il nome dell'app per le funzioni.

Rinnovare o creare chiavi di accesso

Quando si rinnovano o si creano i valori della chiave di accesso, è necessario ridistribuire manualmente i valori della chiave aggiornati a tutti i client che chiamano la funzione.

È possibile rinnovare le chiavi di funzione e host a livello di codice, o crearne di nuove usando queste API di Azure Resource Manager:

• Creare o aggiornare un segreto per le funzioni
• Creare o aggiornare lo slot segreti per le funzioni
• Creare o aggiornare un segreto host
• Creare o aggiornare lo slot segreto host

Per informazioni su come chiamare le API di Azure Resource Manager, vedere informazioni di riferimento sull'API REST di Azure.

È possibile usare questi metodi per ottenere le chiavi di accesso senza dover creare manualmente le chiamate alle API REST.

Azure portal

1. Accedere al portale di Azure e quindi cercare e selezionare App per le funzioni.

2. Selezionare l'app per le funzioni che si desidera usare.

3. Nel riquadro sinistro espandere Funzioni, quindi selezionare Chiavi dell'app.

   Viene visualizzata la pagina Chiavi dell'app. In questa pagina vengono visualizzate le chiavi host, che possono essere usate per accedere a qualsiasi funzione nell'app. Viene visualizzata anche la chiave di sistema, che consente a chiunque l'accesso a livello di amministratore a tutte le API dell'app per le funzioni.

4. Selezionare Rinnova il valore della chiave accanto alla chiave da rinnovare, quindi selezionare Rinnova e salva.

È inoltre possibile rinnovare una chiave di funzione nella scheda Chiavi funzione di una specifica funzione attivata da HTTP.

Interfaccia della riga di comando di Azure

Eseguire lo script seguente in Azure Cloud Shell, che rinnova la chiave host default con un nuovo valore chiave generato da Funzioni.

az functionapp keys set --resource-group <RESOURCE_GROUP> --name <APP_NAME> --key-type functionKeys --key-name default

In questo script, sostituire <RESOURCE_GROUP> e <APP_NAME> rispettivamente con il gruppo di risorse e il nome dell'app per le funzioni. Questo script è stato creato per l'esecuzione in Azure Cloud Shell (Bash). È necessario modificarlo per l'esecuzione in un terminale Windows.

Il nuovo valore della chiave generato da Funzioni viene mostrato come riferimento. Questo nuovo valore della chiave deve essere distribuito in modo sicuro in tutte le app che si basano sulla chiave host. Poiché l'output contiene informazioni sensibili, non rendere persistente l'output né proteggere gli output dei file persistenti.

Azure PowerShell

Eseguire lo script seguente, che usa le API REST per rinnovare la chiave host default con un nuovo valore chiave generato da Funzioni.

# Variables - replace these with your actual values
$resourceGroupName = "<RESOURCE_GROUP>"
$functionAppName = "<APP_NAME>" 

# Construct the URI for the REST API call
$uri = "https://management.azure.com/subscriptions/$((Get-AzContext).Subscription.Id)/resourceGroups/$resourceGroupName/providers/Microsoft.Web/sites/$functionAppName/host/default/listkeys?api-version=2021-02-01"

# Construct the body of the request
$body = @{
    properties = @{
        name = "default"
    }
} | ConvertTo-Json

# Invoke the REST API to create or update the host-level secret
$response = Invoke-AzRestMethod -Method Post -Uri $uri -Payload $body

# Output the updated key for reference
($response.Content | ConvertFrom-Json).functionKeys.default

In questo script, sostituire <RESOURCE_GROUP> e <APP_NAME> rispettivamente con il gruppo di risorse e il nome dell'app per le funzioni.

Il nuovo valore della chiave generato da Funzioni viene restituito come riferimento. Deve essere distribuito in modo sicuro in tutte le app che si basano sulla chiave host. Poiché l'output contiene informazioni sensibili, non rendere persistente l'output né proteggere gli output dei file persistenti.

Eliminare le chiavi di accesso

È possibile eliminare le chiavi funzione e host a livello di codice usando queste API di Azure Resource Manager:

• Elimina segreto funzione
• Elimina slot segreto funzione
• Elimina segreto host
• Elimina slot segreto host

Per informazioni su come chiamare le API di Azure Resource Manager, vedere informazioni di riferimento sull'API REST di Azure.

Contenuto correlato

• Protezione di Funzioni di Azure
• Trigger HTTP di Funzioni di Azure
• Gestire l'app per le funzioni