Werken met toegangssleutels in Azure Functions

Met Azure Functions kunt u geheime sleutels gebruiken om het moeilijker te maken om toegang te krijgen tot uw functie-eindpunten. In dit artikel worden de verschillende soorten toegangssleutels beschreven die worden ondersteund door Functions en hoe u kunt werken met toegangssleutels.

Hoewel toegangssleutels enige beperking bieden tegen ongewenste toegang, moet u andere opties overwegen om HTTP-eindpunten in productie te beveiligen. Het is bijvoorbeeld geen goede gewoonte om gedeelde geheimen in een openbare app te distribueren. Als uw functie wordt aangeroepen vanuit een openbare client, kunt u overwegen deze of andere beveiligingsmechanismen te implementeren:

• App Service-verificatie/-autorisatie inschakelen
• Azure API Management (APIM) gebruiken om aanvragen te verifiëren
• Uw functie-app implementeren in een virtueel netwerk
• Uw functie-app in isolatie implementeren

Toegangssleutels bieden de basis voor HTTP-autorisatie in door HTTP geactiveerde functies. Zie Autorisatieniveau voor meer informatie.

Sleutels begrijpen

Het bereik van een toegangssleutel en de acties die worden ondersteund, zijn afhankelijk van het type toegangssleutel.

Type sleutel	Sleutelnaam	HTTP-verificatieniveau	Beschrijving
Functie	default of door de gebruiker gedefinieerd	function	Hiermee wordt alleen toegang tot een specifiek functie-eindpunt toegestaan.
Host	default of door de gebruiker gedefinieerd	function	Hiermee heeft u toegang tot alle functie-eindpunten in een functie-app.
Hoofdvrachtbrief	_master	admin	Speciale hostsleutel die ook beheerderstoegang biedt tot de RUNTIME REST API's in een functie-app. Deze sleutel kan niet worden ingetrokken. Omdat de hoofdsleutel verhoogde machtigingen in uw functie-app verleent, moet u deze sleutel niet delen met derden of distribueren in systeemeigen clienttoepassingen.
Systeem	Afhankelijk van de extensie	N.v.t.	Voor specifieke extensies is mogelijk een door het systeem beheerde sleutel vereist voor toegang tot webhook-eindpunten. Systeemsleutels zijn ontworpen voor extensiespecifieke functie-eindpunten die worden aangeroepen door interne onderdelen. De Event Grid-trigger vereist bijvoorbeeld dat het abonnement een systeemsleutel gebruikt bij het aanroepen van het triggereindpunt. Durable Functions maakt ook gebruik van systeemsleutels om API's voor durable task-extensie aan te roepen. Systeemsleutels kunnen alleen worden gemaakt door specifieke extensies en u kunt hun waarden niet expliciet instellen. Net als andere sleutels kunt u een nieuwe waarde genereren voor de sleutel vanuit de portal of met behulp van de sleutel-API's.

Elke sleutel wordt genoemd als referentie en er is een standaardsleutel (benoemd default) op functie- en hostniveau. Functietoetsen hebben voorrang op hostsleutels. Wanneer twee sleutels met dezelfde naam worden gedefinieerd, wordt de functiesleutel altijd gebruikt.

In de volgende tabel worden de toepassingen voor verschillende soorten toegangssleutels vergeleken:

Actie	Bereik	Type sleutel
Een functie uitvoeren	Specifieke functie	Functie
Een functie uitvoeren	Elke functie	Functie of host
Een admin eindpunt aanroepen	Functie-app	Alleen model
Duurzame taakextensie-API's aanroepen	Functie-app*	Systeem
Een extensiespecifieke webhook aanroepen (intern)	Functie-app*	systeem

^*Bereik bepaald door de extensie.

Belangrijke vereisten

In Functions worden willekeurig 32 bytematrices gegenereerd die zijn gecodeerd als URL-veilige base-64-tekenreeksen. Hoewel u uw eigen toegangssleutels kunt genereren en deze kunt gebruiken met Functions, raden we u ten zeerste aan om in plaats daarvan toe te staan dat Functions al uw toegangssleutels voor u genereert.

Door functies gegenereerde toegangssleutels bevatten speciale handtekening- en controlesomwaarden die het type toegangssleutel aangeven en dat deze is gegenereerd door Azure Functions. Het gebruik van deze extra onderdelen in de sleutel zelf maakt het veel gemakkelijker om de bron van dit soort geheimen te bepalen die zich tijdens het scannen van de beveiliging en andere geautomatiseerde processen bevinden.

Als u wilt toestaan dat Functions uw sleutels voor u genereert, geeft u de sleutel value niet op aan een van de API's die u kunt gebruiken om sleutels te genereren.

Sleutelopslag beheren

Sleutels worden opgeslagen als onderdeel van uw functie-app in Azure en worden at-rest versleuteld. Sleutels worden standaard opgeslagen in een Blob Storage-container in het account dat door de AzureWebJobsStorage instelling wordt geleverd. U kunt de AzureWebJobsSecretStorageType instelling gebruiken om dit standaardgedrag te overschrijven en in plaats daarvan sleutels op te slaan op een van deze alternatieve locaties:

Locatie	Waarde	Beschrijving
Een tweede opslagaccount	blob	Slaat sleutels op in Blob Storage in een opslagaccount dat anders is dan het account dat wordt gebruikt door de Functions-runtime. Het specifieke account en de gebruikte container worden gedefinieerd door een SAS-URL (Shared Access Signature) die is ingesteld in de AzureWebJobsSecretStorageSas instelling. U moet de AzureWebJobsSecretStorageSas instelling behouden wanneer de SAS-URL wordt gewijzigd.
Azure Key Vault	keyvault	De sleutelkluis die is ingesteld, AzureWebJobsSecretStorageKeyVaultUri wordt gebruikt om sleutels op te slaan.
Bestandssysteem	files	Sleutels blijven behouden op het lokale bestandssysteem. Dit is de standaardwaarde in Functions v1.x. Bestandssysteemopslag wordt niet aanbevolen.
Kubernetes Secrets	kubernetes	De resource-set in AzureWebJobsKubernetesSecretName wordt gebruikt om sleutels op te slaan. Alleen ondersteund wanneer uw functie-app wordt geïmplementeerd in Kubernetes. De Azure Functions Core Tools genereert de waarden automatisch wanneer u deze gebruikt om uw app te implementeren in een Kubernetes-cluster.

Wanneer u Key Vault gebruikt voor sleutelopslag, zijn de app-instellingen die u nodig hebt, afhankelijk van het type beheerde identiteit, ofwel door het systeem toegewezen of door de gebruiker toegewezen.

Naam instelling	Door het systeem toegewezen	Door de gebruiker toegewezen	App-registratie
AzureWebJobsSecretStorageKeyVaultUri	✓	✓	✓
AzureWebJobsSecretStorageKeyVaultClientId	X	✓	✓
AzureWebJobsSecretStorageKeyVaultClientSecret	X	X	✓
AzureWebJobsSecretStorageKeyVaultTenantId	X	X	✓

Toegangssleutels gebruiken

Http-geactiveerde functies kunnen over het algemeen worden aangeroepen met behulp van een URL in de indeling: https://<APP_NAME>.azurewebsites.net/api/<FUNCTION_NAME>. Wanneer het autorisatieniveau van een bepaalde functie een andere waarde dan anonymousis ingesteld, moet u ook een toegangssleutel opgeven in uw aanvraag. De toegangssleutel kan worden opgegeven in de URL met behulp van de ?code= querytekenreeks of in de aanvraagheader (x-functions-key). Zie Toegangssleutelautorisatie voor meer informatie.

Als u toegang wilt krijgen tot de RUNTIME REST API's (onder /admin/), moet u de hoofdsleutel (_master) opgeven in de x-functions-key aanvraagheader.

Toegangssleutels voor uw functie ophalen

U kunt functie- en hostsleutels programmatisch ophalen met behulp van deze Azure Resource Manager-API's:

• Functietoetsen weergeven
• Hostsleutels vermelden
• Sleuf lijstfunctietoetsen
• Lijst hostsleutelsite.

Zie de Naslaginformatie over de Azure REST API voor meer informatie over het aanroepen van Azure Resource Manager-API's.

U kunt deze methoden gebruiken om toegangssleutels op te halen zonder dat u de REST API's hoeft te gebruiken.

Azure-portal

1. Meld u aan bij de Azure-portal, en zoek en selecteer Functie-app.

2. Selecteer de functie-app waarmee u wilt werken.

3. Vouw in het linkerdeelvenster Functies uit en selecteer vervolgens App-sleutels.

   De pagina App-sleutels wordt weergegeven. Op deze pagina worden de hostsleutels weergegeven, die kunnen worden gebruikt voor toegang tot elke functie in de app. De systeemsleutel wordt ook weergegeven, waardoor iedereen op beheerdersniveau toegang heeft tot alle API's van de functie-app.

U kunt ook minimale bevoegdheden oefenen met behulp van de sleutel voor een specifieke functie. U kunt functiespecifieke sleutels ophalen op het tabblad Functietoetsen van een specifieke door HTTP geactiveerde functie.

Azure-CLI

Voer het volgende script uit in Azure Cloud Shell, waarvan de uitvoer de default hostsleutel is, die kan worden gebruikt voor toegang tot elke door HTTP geactiveerde functie in de functie-app.

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

Vervang in dit script <RESOURCE_GROUP> de resourcegroep en <APP_NAME> de naam van uw functie-app, respectievelijk.

Omdat de uitvoer gevoelige informatie bevat, houdt u de uitvoer niet vast of beveiligt u de uitvoer van persistente bestanden.

Azure PowerShell

Voer het volgende script uit, waarvan de uitvoer de default hostsleutel is, die kan worden gebruikt voor toegang tot elke door HTTP geactiveerde functie in de functie-app.

$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

Vervang in dit script <RESOURCE_GROUP> de resourcegroep en <APP_NAME> de naam van uw functie-app, respectievelijk.

Toegangssleutels vernieuwen of maken

Wanneer u uw toegangssleutelwaarden verlengt of maakt, moet u de bijgewerkte sleutelwaarden handmatig distribueren naar alle clients die uw functie aanroepen.

U kunt functie- en hostsleutels programmatisch vernieuwen of nieuwe sleutels maken met behulp van deze Azure Resource Manager-API's:

• Functiegeheim maken of bijwerken
• Functiegeheimsite maken of bijwerken
• Hostgeheim maken of bijwerken
• Hostgeheimsite maken of bijwerken

Zie de Naslaginformatie over de Azure REST API voor meer informatie over het aanroepen van Azure Resource Manager-API's.

U kunt deze methoden gebruiken om toegangssleutels op te halen zonder handmatig aanroepen naar de REST API's te hoeven maken.

Azure-portal

1. Meld u aan bij de Azure-portal, en zoek en selecteer Functie-app.

2. Selecteer de functie-app waarmee u wilt werken.

3. Vouw in het linkerdeelvenster Functies uit en selecteer vervolgens App-sleutels.

   De pagina App-sleutels wordt weergegeven. Op deze pagina worden de hostsleutels weergegeven, die kunnen worden gebruikt voor toegang tot elke functie in de app. De systeemsleutel wordt ook weergegeven, waardoor iedereen op beheerdersniveau toegang heeft tot alle API's van de functie-app.

4. Selecteer De sleutelwaarde Vernieuwen naast de sleutel die u wilt vernieuwen en selecteer Vervolgens Vernieuwen en opslaan.

U kunt ook een functiesleutel vernieuwen op het tabblad Functietoetsen van een specifieke door HTTP geactiveerde functie.

Azure-CLI

Voer het volgende script uit in Azure Cloud Shell, waarmee de default hostsleutel wordt vernieuwd met een nieuwe sleutelwaarde die door Functions wordt gegenereerd.

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

Vervang in dit script <RESOURCE_GROUP> de resourcegroep en <APP_NAME> de naam van uw functie-app, respectievelijk. Dit script is gemaakt om te worden uitgevoerd in Azure Cloud Shell (Bash). U moet deze wijzigen om te worden uitgevoerd in een Windows-terminal.

De nieuwe sleutelwaarde die door Functions wordt gegenereerd, wordt weergegeven voor uw referentie. Deze nieuwe sleutelwaarde moet veilig worden gedistribueerd naar alle apps die afhankelijk zijn van de hostsleutel. Omdat de uitvoer gevoelige informatie bevat, houdt u de uitvoer niet vast of beveiligt u de uitvoer van persistente bestanden.

Azure PowerShell

Voer het volgende script uit, dat gebruikmaakt van de REST API's om de default hostsleutel te vernieuwen met een nieuwe sleutelwaarde die door Functions wordt gegenereerd.

# 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

Vervang in dit script <RESOURCE_GROUP> de resourcegroep en <APP_NAME> de naam van uw functie-app, respectievelijk.

De nieuwe sleutelwaarde die door Functions wordt gegenereerd, wordt geretourneerd voor uw referentie. Het moet veilig worden gedistribueerd naar alle apps die afhankelijk zijn van de hostsleutel. Omdat de uitvoer gevoelige informatie bevat, houdt u de uitvoer niet vast of beveiligt u de uitvoer van persistente bestanden.

Toegangssleutels verwijderen

U kunt functie- en hostsleutels programmatisch verwijderen met behulp van deze Azure Resource Manager-API's:

• Functiegeheim verwijderen
• Functiegeheimsite verwijderen
• Hostgeheim verwijderen
• Hostgeheimsite verwijderen

Zie de Naslaginformatie over de Azure REST API voor meer informatie over het aanroepen van Azure Resource Manager-API's.

Gerelateerde inhoud

• Azure Functions beveiligen
• HTTP-trigger voor Azure Functions
• Uw functie-app beheren