Konfigurieren des Hostschlüsselspeichers von Funktionen auf Azure Container Apps

Funktionszugriffsschlüssel sind Authentifizierungstoken, die von der Funktionslaufzeit verwendet werden, um http-ausgelöste Endpunkte zu sichern. Wenn ein Aufrufer eine HTTP-Funktion aufruft, enthält er einen Schlüssel als ?code= Abfrageparameter oder einen x-functions-key Header. Die Laufzeit überprüft den Schlüssel und autorisiert oder lehnt die Anforderung ab.

Zugriffstasten sind nicht identisch mit geheimen Schlüsseln auf App-Ebene. Zugriffstasten schützen , wer Ihre Funktionen aufrufen kann, während geheime Schlüssel auf App-Ebene schützen , mit welcher Verbindung Ihre Funktionen verbunden sind.

Wann Zugriffstasten verwendet werden sollen

Szenario Warum Zugriffstasten passen
Webhooks von Drittanbietern Anbieter wie GitHub, Stripe oder Twilio rufen Ihre Funktion über eine URL und einen geheimen Schlüssel auf. Zugriffstasten passen direkt in das erwartete Muster ?code=.
Service-to-Service-Aufrufe Back-End-Dienst A ruft Function B über HTTP auf. Ein gemeinsam genutzter Schlüssel ist einfacher als das Einrichten Microsoft Entra App-Registrierungen für nur interne Anrufe.
Event Grid-Abonnements Das Ereignisraster überprüft und ruft Ihren Funktionsendpunkt mithilfe eines Systemschlüssels auf, der von der Plattform automatisch verwaltet wird.
Entwicklungs-/Testauthentifizierung Während der Entwicklung benötigen Sie eine Standardauthentifizierung, ohne OAuth/OIDC zu konfigurieren. Zugriffsschlüssel bieten ein reibungsarmes Authentifizierungs-Gateway ohne Identitätskonfiguration.
Migrationskompatibilität Vorhandene Azure Functions Apps verwenden bereits Zugriffstasten. Bei der Migration zu Container-Apps benötigen Sie dieselbe schlüsselbasierte Authentifizierung, um zu vermeiden, dass Aufrufer dadurch beeinträchtigt werden.

Note

Verwenden Sie für benutzerorientierte APIs, Zero-Trust-Workloads oder Szenarien zur Benutzerautorisierung Microsoft Entra ID / OAuth 2.0 anstelle von Zugriffsschlüsseln. Zugriffsschlüssel sind geheime Schlüssel ohne Prüfpfad auf Identitätsebene.

Voraussetzungen

Zugriffstastentypen

Die Funktionslaufzeit verwaltet vier Schlüsseltypen:

Schlüsseltyp Geltungsbereich Purpose
Haupttaste (_master) Gesamte Funktionsanwendung Administratorzugriff auf alle Funktionen und /admin/* Management-Endpunkte. Kann nicht widerrufen werden; wird nur rotiert.
Hostschlüssel (default + benutzerdefiniert) Gesamte Funktionsanwendung Autorisieren sie Aufrufe an jede http-ausgelöste Funktion in der App.
Funktionstasten (default + benutzerdefiniert) Einzelne Funktion Autorisieren von Aufrufen einer bestimmten Funktion. Bietet eine präzisere Kontrolle als Hostschlüssel.
Systemschlüssel Erweiterungsendpunkte Wird von Plattformerweiterungen wie Event Grid-Webhook-Abonnements und Durable Functions verwendet. Automatisch verwaltet.

Auswählen eines Speicher-Back-Ends

Legen Sie die AzureWebJobsSecretStorageType Umgebungsvariable fest, um zu steuern, wo die Laufzeit Zugriffstasten speichert. Azure Container Apps unterstützt drei Backends der Produktionsklasse.

Back-End Einstellungswert Automatisches Generieren von Schlüsseln Externe Abhängigkeit Am besten geeignet für:
Container Apps Secret Store containerapps Nein – Sie stellen Schlüssel als Geheimnisse von Container-Apps bereit Nichts Die meisten Workloads (empfohlen)
Azure Key Vault keyvault Nein – Manuelles Auslösen der Erstellung Key Vault-Instanz Zentralisierte Governance, Complianceüberwachung
Azure Blob Storage blob Ja Speicherkonto Legacy-Apps oder vorhandenes AzureWebJobsStorage Konto

Behalte diese Backend-Überlegungen im Hinterkopf:

  • Die Laufzeit wählt nicht automatisch den geheimen Speicher von Container Apps aus. Wenn du ihn nicht auf einen nicht erkannten Wert setzt AzureWebJobsSecretStorageType oder setzt, nutzt der Functions-Host Blob Storage, wenn AzureWebJobsStorage es verfügbar ist.
  • Bleiben Sie AzureWebJobsStorage für Speicher-Gesundheitsprüfungen und speicherabhängige Funktionen konfiguriert.
  • Setzen Sie AzureWebJobsSecretStorageType nicht auf files. Das Dateisystem von Container Apps ist flüchtig, sodass Schlüssel, die in diesem Backend gespeichert sind, verloren gehen, wenn die App auf null skaliert, neu startet oder eine neue Version bereitstellt.

Geheime Namensmuster

Die Benennungskonvention für gespeicherte Schlüssel hängt vom Speicher-Back-End ab.

Der Container Apps-Speicher für geheime Schlüssel verwendet eine andere Konvention. Der Functions-Host liest Schlüssel aus auf dem Datenträger eingebundenen Dateien unter /run/secrets/functions-keys/. Jede Datei verwendet einen gepunkteten Namen (z. B. host.master), aber Container-Apps-Geheimniskonventionen erlauben nur alphanumerische Zeichen in Kleinbuchstaben und Bindestriche. Wenn Sie ein geheimes Volume bereitstellen, müssen Sie das path Feld explizit auf den gepunkteten Dateinamen festlegen, den der Funktionenhost erwartet (z. B. secretRef: host-master → path: host.master). Die Plattform führt keine automatische Namensübersetzung durch.

Schlüsseltyp Container-Apps-Secret-Name (Bindestriche) Volume-Mount path (Punkte)
Generalschlüssel host-master host.master
Standardhostschlüssel host-function-default host.function.default
Benutzerdefinierter Hostschlüssel host-function-<name> host.function.<name>
Standardfunktionsschlüssel für eine bestimmte Funktion functions-<functionname>-default functions.<functionName>.default
Benutzerdefinierte Funktionstaste für eine bestimmte Funktion functions-<functionname>-<keyname> functions.<functionName>.<keyName>
Systemschlüssel host-systemkey-<extension> host.systemKey.<extension>

Tip

Suchen Sie bei der Problembehandlung nach diesen Mustern in Ihrem Back-End-Speicher, um zu überprüfen, ob Schlüssel ordnungsgemäß konfiguriert sind.

Konfigurieren des geheimen Container-Apps-Speichers

Der Geheimspeicher von Container Apps ist das empfohlene Backend. Schlüssel bleiben innerhalb der Container-Apps-Plattform und erfordern keinen externen Speicher oder Key Vault. Azure Resource Manager Aktivitätsprotokolle verfolgen Änderungen an Geheimnissen und Umgebungsvariablen nach.

Mit diesem Back-End liest der Functions-Host Schlüssel aus Dateien, die auf dem Volume unter /run/secrets/functions-keys/ eingebunden sind. Der Host generiert keine Schlüssel automatisch. Sie müssen jeden Schlüssel als geheimer Container-Apps-Schlüssel erstellen, und die Plattform stellt sie als Dateien bereit, damit der Host lesen kann.

Important

Der Container Apps-Speicher für geheime Schlüssel ist aus Sicht des Hosts schreibgeschützt. Der Host liest die bereitgestellten Schlüsseldateien, schreibt aber nie in sie. Wenn ein erforderlicher Schlüssel fehlt, generiert der Host ihn nicht automatisch.

Schritt 1: Festlegen des Speichertyps

  1. Wechseln Sie im Azure-Portal zur Container-App "Funktionen".

  2. Wählen Sie unter "Einstellungen" die Option "Umgebungsvariablen" aus.

  3. Wählen Sie "Hinzufügen" aus, und geben Sie die folgenden Werte ein:

    Property Wert
    Namen AzureWebJobsSecretStorageType
    Wert containerapps

  4. Wählen Sie "Speichern" und dann "Übernehmen" aus, um die Änderungen zu bestätigen.

Schritt 2: Generieren und Speichern von Zugriffsschlüsselgeheimnissen

Generieren Sie Schlüsselwerte und speichern Sie sie als Container Apps-Geheimnisse. Sie benötigen mindestens den Hauptschlüssel und einen Standardhostschlüssel.

  1. Wählen Sie in Ihrer Container-App "Funktionen" unter "Einstellungen" "Geheime Schlüssel" aus.

  2. Wählen Sie "Hinzufügen" aus, und geben Sie die folgenden Werte ein:

    Property Wert
    Namen host-master
    Typ Geheimnis der Container-Apps
    Wert Ein zufällig generierter Schlüsselwert.

  3. Wählen Sie Hinzufügen aus.

  4. host-function-default Wiederholen Sie diesen Vorgang mit einem anderen zufällig generierten Wert.

  5. Um einen Schlüssel pro Funktion hinzuzufügen, fügen Sie ein Geheimnis mit dem Namen functions-<functionname>-default (alles in Kleinbuchstaben) hinzu.

Note

Geheime Container-Apps-Namen lassen nur alphanumerische Zeichen und Gedankenstriche in Kleinbuchstaben zu. Sie müssen das path-Feld in der Volumenkonfiguration explizit auf den gepunkteten Dateinamen festlegen, den der Functions-Host erwartet (zum Beispiel secretRef: host-master → path: host.master). Ohne eine explizite Angabe von path behält die Datei auf dem Datenträger ihren mit Bindestrichen versehenen Namen bei, und der Funktionendienst findet den Schlüssel nicht.

Schritt 3: Konfigurieren der Volume-Mount

Montieren Sie die Geheimnisse als Dateien bei /run/secrets/functions-keys/.

  1. Wählen Sie in der Container-App "Funktionen" unter Anwendung die Optionen Überarbeitungen und Replikate aus.

  2. Wählen Sie " Neue Überarbeitung erstellen" aus.

  3. Wählen Sie auf der Registerkarte " Skalieren" und "Volumes " unter "Volumes" die Option "Hinzufügen" aus.

  4. Geben Sie die folgenden Werte ein:

    Property Wert
    Volume-Typ Geheimnis
    Namen functions-keys

  5. Legen Sie für jedes Geheimnis das Feld Pfad auf den punktierten Dateinamen fest, den der Functions-Host erwartet (z. B. host-master auf den Pfad host.master und host-function-default auf den Pfad host.function.default).

  6. Wählen Sie Hinzufügen aus.

  7. Wählen Sie auf der Registerkarte " Container " Ihren Container und dann "Bearbeiten" aus.

  8. Wählen Sie die Registerkarte " Volume mounts" aus, und wählen Sie "Hinzufügen" aus.

  9. Geben Sie die folgenden Werte ein:

    Property Wert
    Volumename functions-keys
    Einbindungspfad /run/secrets/functions-keys

  10. Wählen Sie "Speichern" und dann " Erstellen" aus, um die neue Revision bereitzustellen.

Schritt 4: Überprüfen

Vergewissern Sie sich nach dem Neustart der App, dass die Tasten funktionieren:

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

Sie können auch die App-Protokolle für die Nachricht Resolved secret storage provider ContainerAppsSecretsRepositoryüberprüfen, wodurch bestätigt wird, dass der Host den geheimen Container-Apps-Speicher verwendet.

Schlüssel drehen

Um einen Schlüssel zu drehen, aktualisieren Sie den geheimen Container-Apps-Schlüssel, und starten Sie die App neu:

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

Alle Replikate nutzen dieselben bereitgestellten geheimen Schlüssel. Nach einem Neustart nimmt jedes Replikat die aktualisierten Schlüsselwerte auf.

Konfigurieren Sie Key Vault oder Blob Storage als Speicher

Das Key Vault Backend speichert Zugriffsschlüssel als Key Vault-Geheimnisse und bietet Überwachung und Zugriffssteuerung auf Unternehmensniveau.

  1. Erstellen Sie eine Key Vault (wenn Sie keinen haben):

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

  2. Aktivieren der verwalteten Identität in Ihrer Container-App (sofern noch nicht aktiviert):

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

  3. Gewähren Sie die Rolle Key Vault-Geheimnisbeauftragter für die verwaltete Identität. Die Laufzeit benötigt Lese- und Schreibzugriff, um Schlüssel zu erstellen und zu verwalten:

    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. Legen Sie den Speichertyp und Key Vault URI fest:

    Für vom System zugewiesene Identität:

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

    Legen Sie für die vom Benutzer zugewiesene Identität auch die Client-ID fest:

    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. Auslösen der Schlüsselerstellung durch Auflisten von Schlüsseln:

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

Verwalten von Zugriffsschlüsseln

Verwenden Sie unabhängig vom Back-End die folgenden Befehle zum Auflisten, Erstellen und Löschen von Zugriffstasten:

Note

Lassen Sie mindestens eine Replik laufen, um diese Schlüsselverwaltungsoperationen durchzuführen.

  • Liste alle Host-Schlüssel auf:

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

  • Listen Sie den Hauptschlüssel auf:

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

  • Erstellen oder überschreiben Sie einen benutzerdefinierten Host-Schlüssel:

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

  • Zeigen Sie einen bestimmten Schlüssel:

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

  • Einen Host-Schlüssel löschen:

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

Aufrufen einer Funktion mit einer Zugriffstaste

Übergeben Sie den Schlüssel als Abfrageparameter oder Anforderungsheader.

# 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>"

Verwandte Inhalte

  • Last updated on