Verwenden von Zugriffsschlüsseln in Azure Functions

Azure Functions ermöglicht die Verwendung geheimer Schlüssel, um den Zugriff auf Ihre Funktionsendpunkte zu erschweren. In diesem Artikel werden die verschiedenen Arten von Zugriffsschlüsseln beschrieben, die von Azure Functions unterstützt werden, und Sie erfahren, wie Sie sie verwenden.

Zugriffsschlüssel bieten zwar einen gewissen Schutz vor unerwünschtem Zugriff, in der Produktion sollten jedoch andere Optionen zum Schutz von HTTP-Endpunkten in Betracht gezogen werden. So ist es beispielsweise nicht empfehlenswert, gemeinsam genutzte Geheimnisse in einer öffentlichen App zu verteilen. Wenn Ihre Funktion über einen öffentlichen Client aufgerufen wird, empfiehlt es sich gegebenenfalls, die folgenden (oder auch andere) Sicherheitsmechanismen zu implementieren:

• Aktivieren der App Service-Authentifizierung/-Autorisierung
• Verwenden von Azure API Management (APIM) zum Authentifizieren von Anforderungen
• Bereitstellen der Funktions-App in einem virtuellen Netzwerk
• Isoliertes Bereitstellen Ihrer Funktions-App

Zugriffsschlüssel stellen die Grundlage für die HTTP-Autorisierung in Funktionen mit HTTP-Trigger bereit. Weitere Informationen finden Sie unter Autorisierungsebene.

Grundlegendes zu Schlüsseln

Der Geltungsbereich eines Zugriffsschlüssels und die von ihm unterstützten Aktionen hängen von der Art des Zugriffsschlüssels ab.

Typ Key	Schlüsselname	HTTP-Authentifizierungsebene	Beschreibung
Function	default oder benutzerdefiniert	function	Gewährt nur Zugriff auf einen bestimmten Funktionsendpunkt.
Host	default oder benutzerdefiniert	function	Gewährt Zugriff auf alle Funktionsendpunkte in einer Funktions-App.
Haupt	_master	admin	Spezieller Hostschlüssel, der auch Administratorzugriff auf die Runtime-REST-APIs in einer Funktions-App bietet. Dieser Schlüssel kann nicht widerrufen werden. Aufgrund der erhöhten Berechtigungen, die der Hauptschlüssel in Ihrer Funktions-App erteilt, sollten Sie diesen Schlüssel nicht an Dritte weitergeben oder ihn in nativen Clientanwendungen verteilen.
System	Abhängig von der Erweiterung	Nicht zutreffend	Für bestimmte Erweiterungen kann ein systemseitig verwalteter Schlüssel für den Zugriff auf Webhook-Endpunkte erforderlich sein. Systemschlüssel sind für erweiterungsspezifische Funktionsendpunkte vorgesehen, die von internen Komponenten aufgerufen werden. Beispielsweise erfordert der Event Grid-Auslöser, dass das Abonnement beim Aufruf des Endpunkts des Auslösers einen Systemschlüssel nutzt. Das Feature „Durable Functions“ nutzt auch Systemschlüssel zum Aufrufen von Durable Task-Erweiterungs-APIs. Systemschlüssel können nur von bestimmten Erweiterungen erstellt werden. Ihre Werte können nicht explizit festgelegt werden. Wie bei anderen Schlüsseln können Sie einen neuen Wert für den Schlüssel über das Portal oder mithilfe der Schlüssel-APIs generieren.

Jeder Schlüssel ist zu Referenzzwecken benannt. Auf Funktions- und Hostebene gibt es einen Standardschlüssel (mit dem Namen default). Funktionsschlüssel haben Vorrang vor Hostschlüsseln. Wenn zwei Schlüssel mit dem gleichen Namen definiert wurden, wird immer der Funktionsschlüssel verwendet.

In der folgenden Tabelle wird der Zweck der verschiedenen Arten von Zugriffsschlüsseln verglichen:

Aktion	Bereich	Typ Key
Funktion ausführen	Spezifische Funktion	Funktion
Funktion ausführen	Beliebige Funktion	Funktion oder Host
Aufrufen eines admin-Endpunkts	Funktionen-App	Nur Hauptschlüssel
Durable Task-Erweiterungs-APIs aufrufen	Funktions-App*	System
Erweiterungsspezifischen Webhook (intern) aufrufen	Funktions-App*	system

^* Von der Erweiterung bestimmter Geltungsbereich.

Schlüsselanfoderungen

In Azure Functions sind Zugriffsschlüssel nach dem Zufallsprinzip generierte 32-Byte-Arrays, die als URL-sichere Base64-Zeichenfolgen codiert werden. Sie können zwar eigene Zugriffsschlüssel generieren und mit Azure Functions verwenden, wir empfehlen jedoch dringend, Azure Functions alle Zugriffsschlüssel für Sie generieren zu lassen.

Von Azure Functions generierte Zugriffsschlüssel enthalten spezielle Signatur- und Prüfsummenwerte, die angeben, um welche Art von Zugriffsschlüssel es sich handelt und dass sie von Azure Functions generiert wurden. Durch diese zusätzlichen Komponenten im Schlüssel ist es viel einfacher, die Quelle dieser Arten von Geheimnissen zu bestimmen, die bei der Sicherheitsüberprüfung oder bei anderen automatisierten Prozessen gefunden wurden.

Damit Azure Functions Schlüssel für Sie generieren kann, geben Sie für keine der APIs, die Sie zum Generieren von Schlüsseln verwenden können, den Schlüssel value an.

Verwalten der Schlüsselspeicherung

Schlüssel werden als Teil Ihrer Funktionen-App in Azure gespeichert und sind im Ruhezustand verschlüsselt. Standardmäßig werden Schlüssel in einem Blob Storage-Container in dem Konto gespeichert, das von der AzureWebJobsStorage Einstellung bereitgestellt wird. Sie können die Einstellung AzureWebJobsSecretStorageType verwenden, um dieses Standardverhalten außer Kraft zu setzen und Schlüssel stattdessen an einem der folgenden alternativen Speicherorte zu speichern:

Location	Wert	Beschreibung
Zweites Speicherkonto	blob	Speichert Schlüssel im Blobspeicher in einem Speicherkonto, das sich von dem Speicherkonto unterscheidet, das von der Azure Functions-Runtime verwendet wird. Das spezifische verwendete Konto und der spezifische verwendete Container werden durch eine SAS-URL (Shared Access Signature) definiert, die in der Einstellung AzureWebJobsSecretStorageSas festgelegt wird. Die Einstellung AzureWebJobsSecretStorageSas muss beibehalten werden, wenn sich die SAS-URL ändert.
Azure Key Vault	keyvault	Der in AzureWebJobsSecretStorageKeyVaultUri festgelegte Schlüsseltresor wird zum Speichern von Schlüsseln verwendet.
Dateisystem	files	Schlüssel werden im Dateisystem persistent gespeichert. Dies ist die Standardeinstellung in Azure Functions v1.x. Die Speicherung im Dateisystem wird nicht empfohlen.
Kubernetes-Geheimnisse	kubernetes	Der Ressourcensatz in AzureWebJobsKubernetesSecretName wird zum Speichern von Schlüsseln verwendet. Wird nur unterstützt, wenn Ihre Funktions-App für Kubernetes bereitgestellt wird. Azure Functions Core Tools generiert die Werte automatisch, wenn Sie Ihre App damit in einem Kubernetes-Cluster bereitstellen.

Wenn Sie Key Vault als Schlüsselspeicher verwenden, hängen die von Ihnen benötigten App-Einstellungen von der Art der verwalteten Identität ab (systemseitig zugewiesen oder benutzerseitig zugewiesen).

Einstellungsname	Systemseitig zugewiesen	Benutzerseitig zugewiesen	App-Registrierung
AzureWebJobsSecretStorageKeyVaultUri	✓	✓	✓
AzureWebJobsSecretStorageKeyVaultClientId	X	✓	✓
AzureWebJobsSecretStorageKeyVaultClientSecret	X	X	✓
AzureWebJobsSecretStorageKeyVaultTenantId	X	X	✓

Verwenden von Zugriffsschlüsseln

Durch HTTP ausgelöste Funktionen können im Allgemeinen mithilfe einer URL im folgenden Format aufgerufen werden: https://<APP_NAME>.azurewebsites.net/api/<FUNCTION_NAME>. Wenn die Autorisierungsstufe einer Funktion auf einen anderen Wert als anonymous festgelegt ist, müssen Sie in Ihrer Anforderung auch einen Zugriffsschlüssel bereitstellen. Der Zugriffsschlüssel kann entweder in der URL (unter Verwendung der ?code=-Abfragezeichenfolge) oder im Anforderungsheader (x-functions-key) bereitgestellt werden. Weitere Informationen zur Zugriffsschlüsselautorisierung finden Sie hier.

Um auf die Runtime-REST-APIs (unter /admin/) zuzugreifen, müssen Sie den Hauptschlüssel (_master) im Anforderungsheader x-functions-key bereitstellen. Sie können die Administratorendpunkte mithilfe der functionsRuntimeAdminIsolationEnabled Websiteeigenschaft entfernen.

Abrufen Ihrer Funktionszugriffsschlüssel

Funktions- und Hostschlüssel können programmgesteuert über die folgenden Azure Resource Manager-APIs abgerufen werden:

• Funktionsschlüssel auflisten
• Hostschlüssel auflisten
• Funktionsschlüssel für Slots auflisten
• Hostschlüssel für Slots auflisten

Informationen zum Aufrufen von Azure Resource Manager-APIs finden Sie in der Azure REST-API-Referenz.

Sie können diese Methoden verwenden, um Zugriffsschlüssel abzurufen, ohne die REST-APIs verwenden zu müssen.

Azure portal

1. Melden Sie sich beim Azure-Portal an, suchen Sie nach Funktions-App, und wählen Sie diese Option aus.

2. Wählen Sie die gewünschte Funktions-App aus.

3. Erweitern Sie im linken Bereich die Option Funktionen, und wählen Sie dann App-Schlüssel aus.

   Die Seite App-Schlüssel wird angezeigt. Auf dieser Seite werden die Hostschlüssel angezeigt. Diese können für den Zugriff auf eine beliebige Funktion in der App verwendet werden. Außerdem wird der Systemschlüssel angezeigt. Dieser gibt einem beliebigen Benutzer Zugriff auf Administratorebene auf alle Funktions-App-APIs.

Sie können auch das Prinzip der geringsten Rechte anwenden, indem Sie den Schlüssel für eine spezifische Funktion verwenden. Funktionsspezifische Schlüssel können über die Registerkarte Funktionsschlüssel einer bestimmten Funktion mit HTTP-Trigger abgerufen werden.

Azure-Befehlszeilenschnittstelle

Führen Sie das folgende Skript in Azure Cloud Shell aus. Die Ausgabe des Skripts ist der default-Hostschlüssel, der für den Zugriff auf jede durch HTTP ausgelöste Funktion in der Funktions-App verwendet werden kann.

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

Ersetzen Sie in diesem Skript <RESOURCE_GROUP> und <APP_NAME> durch die Ressourcengruppe bzw. durch den Namen Ihrer Funktions-App.

Die Ausgabe enthält vertrauliche Informationen. Speichern Sie sie daher nicht dauerhaft, oder schützen Sie dauerhaft gespeicherte Dateiausgaben.

Azure PowerShell

Führen Sie das folgende Skript aus. Die Ausgabe des Skripts ist der default-Hostschlüssel, der für den Zugriff auf jede durch HTTP ausgelöste Funktion in der Funktions-App verwendet werden kann.

$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

Ersetzen Sie in diesem Skript <RESOURCE_GROUP> und <APP_NAME> durch die Ressourcengruppe bzw. durch den Namen Ihrer Funktions-App.

Erneuern oder Erstellen von Zugriffsschlüsseln

Wenn Sie Ihre Funktionsschlüsselwerte erneuern oder erstellen, müssen die aktualisierten Schlüsselwerte manuell an alle Clients verteilt werden, von denen Ihre Funktion aufgerufen wird.

Funktions- und Hostschlüssel können programmgesteuert über die folgenden Azure Resource Manager-APIs erneuert oder neu erstellt werden:

• Funktionsgeheimnis erstellen oder aktualisieren
• Funktionsgeheimnis für Slots erstellen oder aktualisieren
• Hostgeheimnis erstellen oder aktualisieren
• Hostgeheimnis für Slot erstellen oder aktualisieren

Informationen zum Aufrufen von Azure Resource Manager-APIs finden Sie in der Azure REST-API-Referenz.

Sie können diese Methoden verwenden, um Zugriffsschlüssel abzurufen, ohne manuell Aufrufe für die REST-APIs erstellen zu müssen.

Azure portal

1. Melden Sie sich beim Azure-Portal an, suchen Sie nach Funktions-App, und wählen Sie diese Option aus.

2. Wählen Sie die gewünschte Funktions-App aus.

3. Erweitern Sie im linken Bereich die Option Funktionen, und wählen Sie dann App-Schlüssel aus.

   Die Seite App-Schlüssel wird angezeigt. Auf dieser Seite werden die Hostschlüssel angezeigt. Diese können für den Zugriff auf eine beliebige Funktion in der App verwendet werden. Außerdem wird der Systemschlüssel angezeigt. Dieser gibt einem beliebigen Benutzer Zugriff auf Administratorebene auf alle Funktions-App-APIs.

4. Wählen Sie neben dem Schlüssel, den Sie erneuern möchten, die Option Schlüsselwert erneuern und anschließend Erneuern und speichern aus.

Funktionsschlüssel können auch auf der Registerkarte Funktionsschlüssel einer bestimmten Funktion mit HTTP-Trigger erneuert werden.

Azure-Befehlszeilenschnittstelle

Führen Sie das folgende Skript in Azure Cloud Shell aus. Dadurch wird der default-Hostschlüssel mit einem neuen, von Azure Functions generierten Schlüsselwert versehen.

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

Ersetzen Sie in diesem Skript <RESOURCE_GROUP> und <APP_NAME> durch die Ressourcengruppe bzw. durch den Namen Ihrer Funktions-App. Dieses Skript wurde für die Ausführung in Azure Cloud Shell (Bash) erstellt. Für die Ausführung in einem Windows-Terminal muss es entsprechend angepasst werden.

Der neue, von Azure Functions generierte Schlüsselwert wird zu Referenzzwecken angezeigt. Dieser neue Schlüsselwert muss sicher an alle Apps verteilt werden, die den Hostschlüssel benötigen. Die Ausgabe enthält vertrauliche Informationen. Speichern Sie sie daher nicht dauerhaft, oder schützen Sie dauerhaft gespeicherte Dateiausgaben.

Azure PowerShell

Führen Sie das folgende Skript. Es verwendet die REST-APIs, um den default-Hostschlüssel mit einem neuen, von Azure Functions generierten Schlüsselwert zu versehen.

# 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

Ersetzen Sie in diesem Skript <RESOURCE_GROUP> und <APP_NAME> durch die Ressourcengruppe bzw. durch den Namen Ihrer Funktions-App.

Der neue, von Azure Functions generierte Schlüsselwert wird zu Referenzzwecken zurückgegeben. Er muss sicher an alle Apps verteilt werden, die den Hostschlüssel benötigen. Die Ausgabe enthält vertrauliche Informationen. Speichern Sie sie daher nicht dauerhaft, oder schützen Sie dauerhaft gespeicherte Dateiausgaben.

Löschen von Zugriffsschlüsseln

Funktions- und Hostschlüssel können programmgesteuert über die folgenden Azure Resource Manager-APIs gelöscht werden:

• Funktionsgeheimnis löschen
• Funktionsgeheimnis für Slots löschen
• Hostgeheimnis löschen
• Hostgeheimnis für Slots löschen

Informationen zum Aufrufen von Azure Resource Manager-APIs finden Sie in der Azure REST-API-Referenz.

Zugehöriger Inhalt

• Absichern von Azure Functions
• HTTP-Trigger in Azure Functions
• Verwalten Ihrer Funktions-App