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

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.

Modelli di nomi dei segreti

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

Key Vault

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

Archiviazione BLOB

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
<siteSlotName>/host.json File JSON contenente masterKey, functionKeyse systemKeys
<siteSlotName>/<functionName>.json File JSON contenente chiavi per una funzione specifica

Archivio sicuro delle applicazioni container

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>

Tip

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

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.

Importante

Per i carichi di lavoro di produzione, preferire i back-end in questo ordine: Archivio di segreti delle app container (containerapp) > Azure Key Vault (keyvault) > Archiviazione BLOB di Azure (blob). Il store delle segreti delle Container Apps non ha dipendenze esterne ed è il più semplice da usare.

Back-end Valore dell'impostazione Genera automaticamente chiavi Dipendenza esterna Ideale per
Archivio segreto delle applicazioni container containerapp 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

Note

Per Functions su App contenitore di Azure, la piattaforma usa per impostazione predefinita containerapp (archivio dei segreti di Container Apps) quando AzureWebJobsSecretStorageType non è impostato in modo esplicito. Non è necessario configurare un back-end a meno che non si voglia usare Key Vault o gestione rete virtuale di Azure.

Avvertimento

Non impostare AzureWebJobsSecretStorageType su files. In App contenitore di Azure, il file system è effimero, quindi le chiavi host archiviate con il back-end files vengono perse ogni volta che l'app viene ridimensionata a zero, viene riavviata o distribuisce una nuova revisione. Usare sempre uno dei tre back-end di produzione elencati in precedenza.

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

  1. Passare all'app contenitore di Funzioni nel Portale di Azure.

  2. In Impostazioni selezionare Variabili di ambiente.

  3. Selezionare Aggiungi e immettere i valori seguenti:

    Proprietà Valore
    Nome AzureWebJobsSecretStorageType
    Valore containerapp

  4. Selezionare Salva e quindi Applica per confermare le modifiche.

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.

  1. Nell'app contenitore funzioni, in Impostazioni selezionare Segreti.

  2. Selezionare Aggiungi e immettere i valori seguenti:

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

  3. Seleziona Aggiungi.

  4. Ripetere per host-function-default con un altro valore generato in modo casuale.

  5. Per aggiungere una chiave per funzione, aggiungere un segreto denominato functions-<functionname>-default (tutte minuscole).

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/.

  1. Nell'app contenitore funzioni, in Applicazione selezionare Revisioni e repliche.

  2. Selezionare Crea nuova revisione.

  3. Nella scheda Scalabilità e volumi , in Volumi, selezionare Aggiungi.

  4. Immettere i valori seguenti:

    Proprietà Valore
    Tipo di volume Segreto
    Nome functions-keys

  5. 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.

  6. Seleziona Aggiungi.

  7. Nella scheda Contenitore selezionare il contenitore e quindi selezionare Modifica.

  8. Selezionare la scheda Montaggi del volume e selezionare Aggiungi.

  9. Immettere i valori seguenti:

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

  10. Selezionare Salva e quindi Crea per distribuire la nuova revisione.

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.

Configurare l'archiviazione BLOB

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.

Note

Crittografia dei dati inattivi: quando si esamina il contenuto del BLOB (ad esempio, azure-webjobs-secrets/<app>/host.json), è possibile che venga visualizzato "encrypted": false nel payload JSON. Questo flag indica che l'host di Functions non ha applicato la crittografia a livello di host ai valori delle chiavi prima di scriverli nell'archivio. Tuttavia, questo non significa che i segreti vengono archiviati non crittografati. Crittografia del servizio di archiviazione di Azure crittografa automaticamente tutti i dati BLOB a riposo con crittografia AES-256. L'intero contenuto del blob, inclusi i valori delle chiavi, viene crittografato in modo trasparente dal livello di archiviazione. La crittografia a livello di host è necessaria principalmente per backend come il file system locale, che non offrono una propria crittografia dei dati a riposo.

  1. 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

  2. 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"

  3. Impostare il tipo di archiviazione:

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

  4. 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

Configurare Key Vault

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

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

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

  2. 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

  3. 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"

  4. 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>"

  5. Attivare la creazione della chiave elencando le chiavi:

    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:

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

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

# Create or overwrite a custom host key
az containerapp function keys set \
  --resource-group "<RESOURCE_GROUP>" \
  --name "<FUNCTIONS_APP_NAME>" \
  --key-name "MyCustomKey" \
  --key-value "<YOUR_KEY_VALUE>" \
  --key-type hostKey

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

# Delete a host key
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>"

Contenuti correlati

  • Last updated on