Configurare l'archiviazione delle chiavi host di Funzioni su App contenitore di Azure

Le chiavi di accesso alle funzioni sono token di autenticazione usati dal runtime di Funzioni per proteggere gli endpoint attivati tramite HTTP. Quando un chiamante richiama una funzione HTTP, include una chiave come parametro di query ?code= o come intestazione x-functions-key. Il runtime convalida la chiave e autorizza o rifiuta la richiesta.

Le chiavi di accesso non corrispondono ai segreti a livello di app. Le chiavi di accesso proteggono chi può chiamare le funzioni, mentre i segreti a livello di app proteggono le funzioni a cui si connettono.

Quando usare le chiavi di accesso

Scenario	Perché i tasti di accesso si adattano perfettamente
Webhook di terze parti	Provider come GitHub, Stripe o Twilio chiamano la funzione tramite un URL e un segreto. Le chiavi di accesso si inseriscono direttamente nel modello `?code=` previsto.
Chiamate da servizio a servizio	Il servizio back-end A chiama la funzione B su HTTP. Una chiave condivisa è più semplice rispetto alla configurazione delle registrazioni delle app di Microsoft Entra per le chiamate esclusivamente interne.
Sottoscrizioni di Griglia di eventi	Griglia di eventi convalida e chiama l'endpoint della funzione usando una chiave di sistema gestita automaticamente dalla piattaforma.
Autenticazione di sviluppo/test	Durante lo sviluppo è necessaria l'autenticazione di base senza configurare OAuth/OIDC completo. Le chiavi di accesso forniscono un gate di autenticazione a basso attrito senza alcuna configurazione di identità.
Compatibilità della migrazione	Le app di Funzioni di Azure esistenti usano già le chiavi di accesso. Quando si esegue la migrazione ad App contenitore, è necessaria la stessa autenticazione basata su chiave per evitare interruzioni dei chiamanti.

Note

Per le API rivolte agli utenti, carichi di lavoro senza attendibilità o scenari di autorizzazione per utente, usare Microsoft Entra ID/ OAuth 2.0 anziché le chiavi di accesso. Le chiavi di accesso sono segreti condivisi senza tracciabilità a livello di identità.

Prerequisiti

Un account Azure con una sottoscrizione attiva. Creare un account gratuito.
interfaccia della riga di comando di Azure versione 2.40.0 o successiva.
Un'app Funzioni di Azure esistente in Container Apps o autorizzazioni per crearne una.

Tipi di chiave di accesso

Il runtime di Funzioni gestisce quattro tipi di chiavi:

Tipo di chiave	Ambito	Purpose
Chiave principale (`_master`)	Intera app di funzioni	Accesso a livello di amministratore a tutte le funzioni e `/admin/*` agli endpoint di gestione. Non può essere revocato, solo ruotato.
Chiavi host (`default` + personalizzato)	Intera app di funzioni	Autorizzare le chiamate a qualsiasi funzione attivata da HTTP nell'app.
Tasti funzione (`default` + personalizzato)	Singola funzione	Autorizzare le chiamate a una funzione specifica. Fornisce un controllo più granulare rispetto alle chiavi host.
Chiavi di sistema	Punti di estensione	Usato dalle estensioni della piattaforma, ad esempio sottoscrizioni di webhook di Griglia di eventi e Durable Functions. Gestito automaticamente.

Scegliere un back-end di archiviazione

Impostare la AzureWebJobsSecretStorageType variabile di ambiente per controllare la posizione in cui il runtime rende persistenti le chiavi di accesso. App contenitore di Azure supporta tre back-end di livello di produzione.

Back-end	Valore dell'impostazione	Genera automaticamente chiavi	Dipendenza esterna	Ideale per
Archivio segreto delle applicazioni container	`containerapps`	No: si effettua il provisioning delle chiavi come segreti di App contenitore	None	La maggior parte dei carichi di lavoro (Consigliato)
Azure Key Vault	`keyvault`	No - Creazione manuale del trigger	Istanza del Key Vault	Governance centralizzata, controllo della conformità
Archiviazione BLOB di Azure	`blob`	Sì	Account di archiviazione	Applicazioni legacy o account `AzureWebJobsStorage` esistente

Tieni a mente queste considerazioni del backend:

L'esecuzione non seleziona automaticamente lo spazio di archiviazione segreta delle Container App. Se non imposti AzureWebJobsSecretStorageType o imposti un valore non riconosciuto, l'host delle Funzioni usa gestione rete virtuale di Azure quando AzureWebJobsStorage è disponibile.
Tieni AzureWebJobsStorage configurato per controlli di stato dello storage e funzionalità dipendenti dallo storage.
Non impostare AzureWebJobsSecretStorageType su files. Il file system delle Container Apps è effimero, quindi le chiavi memorizzate con questo backend si perdono quando l'app scala a zero, si riavvia o distribuisce una nuova versione.

Modelli di nomi dei segreti

La convenzione di denominazione per le chiavi archiviate dipende dal back-end di archiviazione.

L'archivio segreti di App contenitore usa una convenzione diversa. L'host di Funzioni legge le chiavi dai file montati sul volume in /run/secrets/functions-keys/. Ogni file usa un nome punteggiato ,ad esempio host.master, ma i nomi dei segreti di App contenitore consentono solo caratteri alfanumerici minuscoli e trattini. Quando si monta un volume segreto, è necessario impostare esplicitamente il campo path sul nome del file punteggiato previsto dall'host delle Funzioni, ad esempio secretRef: host-master → path: host.master. La piattaforma non esegue alcuna traduzione automatica dei nomi.

Tipo di chiave	Nome del segreto di App contenitore (trattini)	Montaggio del volume `path` (punti)
Chiave master	`host-master`	`host.master`
Chiave host predefinita	`host-function-default`	`host.function.default`
Chiave host personalizzata	`host-function-<name>`	`host.function.<name>`
Chiave di funzione predefinita per una funzione specifica	`functions-<functionname>-default`	`functions.<functionName>.default`
Chiave di funzione personalizzata per una funzione specifica	`functions-<functionname>-<keyname>`	`functions.<functionName>.<keyName>`
Chiave di sistema	`host-systemkey-<extension>`	`host.systemKey.<extension>`

Il back-end Key Vault archivia ogni chiave come singolo segreto Key Vault usando una convenzione double-dash (--):

Tipo di chiave	Modello di nome segreto	Example
Chiave master	`host--masterKey--master`	`host--masterKey--master`
Tasto funzione (impostazione predefinita)	`host--functionKey--default`	`host--functionKey--default`
Tasto funzione (personalizzato)	`host--functionKey--<name>`	`host--functionKey--MyApiClient`
Chiave di sistema	`host--systemKey--<extension>`	`host--systemKey--eventgrid_extension`
Chiave per funzione	`function--<functionName>--<keyName>`	`function--myhttpfunc--default`

Il back-end gestione rete virtuale di Azure archivia le chiavi come file JSON nel contenitore BLOB azure-webjobs-secrets. Tutte le chiavi a livello di host (master, chiavi di funzione e chiavi di sistema) vengono archiviate insieme in un singolo host.json BLOB. Le chiavi per funzione vengono archiviate in BLOB separati denominati dopo ogni funzione.

Percorso BLOB	Contenuto
`<SITE_SLOT_NAME>/host.json`	File JSON contenente `masterKey`, `functionKeys`e `systemKeys`
`<SITE_SLOT_NAME>/<FUNCTION_NAME>.json`	File JSON contenente chiavi per una funzione specifica

Tip

Durante la risoluzione dei problemi, cercare questi modelli nell'archivio back-end per verificare che le chiavi siano configurate correttamente.

Configurare l'archivio dei segreti di App contenitore

L'archivio dei segreti di App contenitore è il back-end consigliato. Le chiavi rimangono all'interno della piattaforma App contenitore e non richiedono spazio di archiviazione esterno o Key Vault. Azure Resource Manager i log delle attività tengono traccia delle modifiche apportate ai segreti e alle variabili di ambiente.

Con questo back-end, l'host di Funzioni legge le chiavi dai file montati sul volume in /run/secrets/functions-keys/. L'host non genera automaticamente le chiavi. È necessario creare ogni chiave come segreto di Container Apps e la piattaforma li monta come file per essere letti dall'host.

Importante

L'archivio dei segreti di App contenitore è di sola lettura dal punto di vista dell'host. L'host legge i file di chiave montati, ma non li scrive mai. Se manca una chiave obbligatoria, l'host non lo genera automaticamente.

Passaggio 1: Impostare il tipo di archiviazione

Portale
interfaccia della riga di comando di Azure

Passare all'app contenitore di Funzioni nel Portale di Azure.
In Impostazioni selezionare Variabili di ambiente.
Selezionare Aggiungi e immettere i valori seguenti:

Proprietà Valore

Nome AzureWebJobsSecretStorageType

Valore containerapps
Selezionare Salva e quindi Applica per confermare le modifiche.

Proprietà	Valore
Nome	`AzureWebJobsSecretStorageType`
Valore	`containerapps`

az containerapp update \
  --resource-group "<RESOURCE_GROUP>" \
  --name "<FUNCTIONS_APP_NAME>" \
  --set-env-vars "AzureWebJobsSecretStorageType=containerapps"

Passaggio 2: Generare e archiviare i segreti delle chiavi di accesso

Generare i valori delle chiavi e archiviarli come segreti delle Container Apps. È necessaria almeno la chiave master e una chiave host predefinita.

Portale
interfaccia della riga di comando di Azure

Nell'app contenitore funzioni, in Impostazioni selezionare Segreti.
Selezionare Aggiungi e immettere i valori seguenti:

Proprietà Valore

Nome host-master

Type Segreto app contenitore

Valore Valore della chiave generato in modo casuale.
Seleziona Aggiungi.
Ripetere per host-function-default con un altro valore generato in modo casuale.
Per aggiungere una chiave per funzione, aggiungere un segreto denominato functions-<functionname>-default (tutte minuscole).

Proprietà	Valore
Nome	`host-master`
Type	Segreto app contenitore
Valore	Valore della chiave generato in modo casuale.

# Generate random key values
MASTER_KEY=$(openssl rand -hex 32)
HOST_DEFAULT_KEY=$(openssl rand -hex 32)

# Store as Container Apps secrets
az containerapp secret set \
  --resource-group "<RESOURCE_GROUP>" \
  --name "<FUNCTIONS_APP_NAME>" \
  --secrets "host-master=$MASTER_KEY" "host-function-default=$HOST_DEFAULT_KEY"

Per aggiungere una chiave per funzione ( ad esempio, per una funzione denominata MyHttpFunc):

FUNC_KEY=$(openssl rand -hex 32)

az containerapp secret set \
  --resource-group "<RESOURCE_GROUP>" \
  --name "<FUNCTIONS_APP_NAME>" \
  --secrets "functions-myhttpfunc-default=$FUNC_KEY"

Note

I nomi dei segreti delle app di container consentono solo caratteri alfanumerici minuscoli e trattini. È necessario impostare esplicitamente il campo path nella configurazione del volume sul nome file punteggiato che l'host delle Funzioni si aspetta, per esempio, secretRef: host-master → path: host.master. Senza un path esplicito, il file su disco mantiene il nome tratteggiato e l'host di Funzioni non potrà trovare la chiave.

Passaggio 3: Configurare il montaggio del volume

Montare i segreti come file in /run/secrets/functions-keys/.

Portale
interfaccia della riga di comando di Azure

Nell'app contenitore funzioni, in Applicazione selezionare Revisioni e repliche.
Selezionare Crea nuova revisione.
Nella scheda Scalabilità e volumi , in Volumi, selezionare Aggiungi.
Immettere i valori seguenti:

Proprietà Valore

Tipo di volume Segreto

Nome functions-keys
Per ogni segreto, impostare il campo Percorso sul nome file punteggiato previsto dall'host di Funzioni, ad esempio impostato sul host-master percorso host.mastere host-function-default sul percorso host.function.default.
Seleziona Aggiungi.
Nella scheda Contenitore selezionare il contenitore e quindi selezionare Modifica.
Selezionare la scheda Montaggi del volume e selezionare Aggiungi.
Immettere i valori seguenti:

Proprietà Valore

Nome del volume functions-keys

Percorso di montaggio /run/secrets/functions-keys
Selezionare Salva e quindi Crea per distribuire la nuova revisione.

Proprietà	Valore
Tipo di volume	Segreto
Nome	`functions-keys`

Proprietà	Valore
Nome del volume	`functions-keys`
Percorso di montaggio	`/run/secrets/functions-keys`

Esportare la YAML dell'app, aggiungere il volume e il montaggio del volume, quindi applicare:

# Export current config
az containerapp show \
  --resource-group "<RESOURCE_GROUP>" \
  --name "<FUNCTIONS_APP_NAME>" \
  --output yaml > app.yaml

Modificare app.yaml per aggiungere il volume e il montaggio del volume nelle sezioni appropriate:

properties:
  template:
    volumes:
      - name: functions-keys
        storageType: Secret
        secrets:
          - secretRef: host-master
            path: host.master
          - secretRef: host-function-default
            path: host.function.default
    containers:
      - name: <CONTAINER_NAME>
        volumeMounts:
          - volumeName: functions-keys
            mountPath: /run/secrets/functions-keys

Applicare la configurazione aggiornata:

az containerapp update \
  --resource-group "<RESOURCE_GROUP>" \
  --name "<FUNCTIONS_APP_NAME>" \
  --yaml app.yaml

Passaggio 4: Verificare

Dopo il riavvio dell'app, verificare che le chiavi funzionino:

az containerapp function keys list \
  --resource-group "<RESOURCE_GROUP>" \
  --name "<FUNCTIONS_APP_NAME>" \
  --key-type hostKey

È anche possibile controllare i log dell'app per il messaggio Resolved secret storage provider ContainerAppsSecretsRepository, che conferma che l'host usa l'archivio dei segreti di App contenitore.

Ruotare le chiavi

Per ruotare una chiave, aggiornare il segreto di App contenitore e riavviare l'app:

NEW_KEY=$(openssl rand -hex 32)

az containerapp secret set \
  --resource-group "<RESOURCE_GROUP>" \
  --name "<FUNCTIONS_APP_NAME>" \
  --secrets "host-function-default=$NEW_KEY"

az containerapp revision restart \
  --resource-group "<RESOURCE_GROUP>" \
  --name "<FUNCTIONS_APP_NAME>" \
  --revision "<REVISION_NAME>"

Note

Tutte le repliche condividono gli stessi segreti segretati. Dopo un riavvio, ogni replica preleva i valori di chiave aggiornati.

Configura Key Vault o gestione rete virtuale di Azure come store

Configura Key Vault
Configura gestione rete virtuale di Azure

Il back-end di Key Vault archivia le chiavi di accesso come segreti Key Vault, fornendo audit e controllo di accesso di livello aziendale.

Creare un Key Vault (se non ne è disponibile uno):

az keyvault create \
  --name "<KEYVAULT_NAME>" \
  --resource-group "<RESOURCE_GROUP>" \
  --location "<LOCATION>"

Abilitare l'identità gestita nell'app contenitore (se non è già abilitata):

az containerapp identity assign \
  --resource-group "<RESOURCE_GROUP>" \
  --name "<FUNCTIONS_APP_NAME>" \
  --system-assigned

Concedere il ruolo Key Vault Secrets Officer all'identità gestita. Il runtime richiede l'accesso in lettura e scrittura per creare e gestire chiavi:

PRINCIPAL_ID=$(az containerapp show \
  --resource-group "<RESOURCE_GROUP>" \
  --name "<FUNCTIONS_APP_NAME>" \
  --query identity.principalId \
  --output tsv)

KEYVAULT_ID=$(az keyvault show \
  --name "<KEYVAULT_NAME>" \
  --query id \
  --output tsv)

az role assignment create \
  --role "Key Vault Secrets Officer" \
  --assignee "$PRINCIPAL_ID" \
  --scope "$KEYVAULT_ID"

Impostare il tipo di archiviazione e Key Vault URI:

Per l'identità assegnata dal sistema:

az containerapp update \
  --resource-group "<RESOURCE_GROUP>" \
  --name "<FUNCTIONS_APP_NAME>" \
  --set-env-vars \
    "AzureWebJobsSecretStorageType=keyvault" \
    "AzureWebJobsSecretStorageKeyVaultUri=https://<KEYVAULT_NAME>.vault.azure.net"

Per l'identità assegnata dall'utente, impostare anche l'ID client:

az containerapp update \
  --resource-group "<RESOURCE_GROUP>" \
  --name "<FUNCTIONS_APP_NAME>" \
  --set-env-vars \
    "AzureWebJobsSecretStorageType=keyvault" \
    "AzureWebJobsSecretStorageKeyVaultUri=https://<KEYVAULT_NAME>.vault.azure.net" \
    "AzureWebJobsSecretStorageKeyVaultClientId=<USER_ASSIGNED_IDENTITY_CLIENT_ID>"

Attivare la creazione della chiave elencando le chiavi:

az containerapp function keys list \
  --resource-group "<RESOURCE_GROUP>" \
  --name "<FUNCTIONS_APP_NAME>" \
  --key-type hostKey

Il back-end gestione rete virtuale di Azure consente al runtime di generare e gestire automaticamente le chiavi di accesso. Usare questa opzione quando si ha già un account di archiviazione per AzureWebJobsStorage e non è necessaria la governance centralizzata.

Abilitare l'identità gestita nell'app contenitore (se non è già abilitata):

az containerapp identity assign \
  --resource-group "<RESOURCE_GROUP>" \
  --name "<FUNCTIONS_APP_NAME>" \
  --system-assigned

Concedere il ruolo Collaboratore dati BLOB di archiviazione sull'account di archiviazione all'identità gestita:

PRINCIPAL_ID=$(az containerapp show \
  --resource-group "<RESOURCE_GROUP>" \
  --name "<FUNCTIONS_APP_NAME>" \
  --query identity.principalId \
  --output tsv)

STORAGE_ID=$(az storage account show \
  --name "<STORAGE_ACCOUNT_NAME>" \
  --resource-group "<RESOURCE_GROUP>" \
  --query id \
  --output tsv)

az role assignment create \
  --role "Storage Blob Data Contributor" \
  --assignee "$PRINCIPAL_ID" \
  --scope "$STORAGE_ID"

Impostare il tipo di archiviazione:

az containerapp update \
  --resource-group "<RESOURCE_GROUP>" \
  --name "<FUNCTIONS_APP_NAME>" \
  --set-env-vars "AzureWebJobsSecretStorageType=blob"

Il runtime genera automaticamente le chiavi all'avvio a freddo successivo. Verificare:

az containerapp function keys list \
  --resource-group "<RESOURCE_GROUP>" \
  --name "<FUNCTIONS_APP_NAME>" \
  --key-type hostKey

Gestire le chiavi di accesso

Indipendentemente dal back-end, usare i comandi seguenti per elencare, creare ed eliminare chiavi di accesso:

Note

Tieni in funzione almeno una replica per eseguire queste operazioni di gestione delle chiavi.

Elenca tutte le chiavi dell'host:

az containerapp function keys list \
  --resource-group "<RESOURCE_GROUP>" \
  --name "<FUNCTIONS_APP_NAME>" \
  --key-type hostKey

Elenca la chiave maestra:

az containerapp function keys list \
  --resource-group "<RESOURCE_GROUP>" \
  --name "<FUNCTIONS_APP_NAME>" \
  --key-type masterKey

Crea o sovrascrivi una chiave host personalizzata:

az containerapp function keys set \
  --resource-group "<RESOURCE_GROUP>" \
  --name "<FUNCTIONS_APP_NAME>" \
  --key-name "MyCustomKey" \
  --key-value "<YOUR_KEY_VALUE>" \
  --key-type hostKey

Mostra una chiave specifica:

az containerapp function keys show \
  --resource-group "<RESOURCE_GROUP>" \
  --name "<FUNCTIONS_APP_NAME>" \
  --key-name "<KEY_NAME>" \
  --key-type hostKey

Elimina una chiave host:

az containerapp function keys delete \
  --resource-group "<RESOURCE_GROUP>" \
  --name "<FUNCTIONS_APP_NAME>" \
  --key-name "MyCustomKey" \
  --key-type hostKey

Chiamare una funzione con una chiave di accesso

Passare la chiave come parametro di query o intestazione della richiesta.

# Query parameter
curl "https://<FUNCTIONS_APP_URL>/api/<FUNCTION_NAME>?code=<HOST_KEY>"

# Header
curl "https://<FUNCTIONS_APP_URL>/api/<FUNCTION_NAME>" \
  -H "x-functions-key: <HOST_KEY>"

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2026-08-14

Configurare l'archiviazione delle chiavi host di Funzioni su App contenitore di Azure

Quando usare le chiavi di accesso

Prerequisiti

Tipi di chiave di accesso

Scegliere un back-end di archiviazione

Modelli di nomi dei segreti

Configurare l'archivio dei segreti di App contenitore

Passaggio 1: Impostare il tipo di archiviazione

Passaggio 2: Generare e archiviare i segreti delle chiavi di accesso

Passaggio 3: Configurare il montaggio del volume

Passaggio 4: Verificare

Ruotare le chiavi

Configura Key Vault o gestione rete virtuale di Azure come store

Gestire le chiavi di accesso

Chiamare una funzione con una chiave di accesso

Contenuti correlati

Commenti e suggerimenti

Risorse aggiuntive