Work with access keys in Azure Functions

Article
08/21/2024

Azure Functions lets you use secret keys to make it more difficult to access your function endpoints. This article describes the various kinds of access keys supported by Functions, and how to work with access keys.

While access keys provide some mitigation against unwanted access, you should consider other options to secure HTTP endpoints in production. For example, it's not a good practice to distribute shared secrets in a public app. If your function is being called from a public client, you should consider implementing these or other security mechanisms:

Access keys provide the basis for HTTP authorization in HTTP triggered functions. For more information, see Authorization level.

Understand keys

The scope of an access key and the actions it supports depend on the type of access key.

Key type	Key name	HTTP auth level	Description
Function	`default` or user defined	`function`	Allows access only to a specific function endpoint.
Host	`default` or user defined	`function`	Allows access to all function endpoints in a function app.
Master	`_master`	`admin`	Special host key that also provides administrative access to the runtime REST APIs in a function app. This key can't be revoked. Because the master key grants elevated permissions in your function app, you shouldn't share this key with third parties or distribute it in native client applications.
System	Depends on the extension	n/a	Specific extensions might require a system-managed key to access webhook endpoints. System keys are designed for extension-specific function endpoints that get called by internal components. For example, the Event Grid trigger requires that the subscription use a system key when calling the trigger endpoint. Durable Functions also uses system keys to call Durable Task extension APIs. System keys can only be created by specific extensions, and you can't explicitly set their values. Like other keys, you can generate a new value for the key from the portal or by using the key APIs.

Each key is named for reference, and there's a default key (named default) at the function and host level. Function keys take precedence over host keys. When two keys are defined with the same name, the function key is always used.

The following table compares the uses for various kinds of access keys:

Action	Scope	Key type
Execute a function	Specific function	Function
Execute a function	Any function	Function or host
Call an `admin` endpoint	Function app	Master-only
Call Durable Task extension APIs	Function app^*	System
Call an extension-specific Webhook (internal)	Function app^*	system

^*Scope determined by the extension.

Key requirements

In Functions, access keys are randomly generated 32-byte arrays that are encoded as URL-safe base-64 strings. While you can generate your own access keys and use them with Functions, we strongly recommend that you instead allow Functions to generate all of your access keys for you.

Functions-generated access keys include special signature and checksum values that indicate the type of access key and that it was generated by Azure Functions. Having these extra components in the key itself makes it much easier to determine the source of these kinds of secrets located during security scanning and other automated processes.

To allow Functions to generate your keys for you, don't supply the key value to any of the APIs that you can use to generate keys.

Manage key storage

Keys are stored as part of your function app in Azure and are encrypted at rest. By default, keys are stored in a Blob storage container in the account provided by the AzureWebJobsStorage setting. You can use the AzureWebJobsSecretStorageType setting to override this default behavior and instead store keys in one of these alternate locations:

Location	Value	Description
A second storage account	`blob`	Stores keys in Blob storage in a storage account that's different that the one used by the Functions runtime. The specific account and container used is defined by a shared access signature (SAS) URL set in the `AzureWebJobsSecretStorageSas` setting. You must maintain the `AzureWebJobsSecretStorageSas` setting when the SAS URL changes.
Azure Key Vault	`keyvault`	The key vault set in `AzureWebJobsSecretStorageKeyVaultUri` is used to store keys.
File system	`files`	Keys are persisted on the local file system, which is the default in Functions v1.x. File system storage isn't recommended.
Kubernetes Secrets	`kubernetes`	The resource set in AzureWebJobsKubernetesSecretName is used to store keys. Supported only when your function app is deployed to Kubernetes. The Azure Functions Core Tools generates the values automatically when you use it to deploy your app to a Kubernetes cluster.

When using Key Vault for key storage, the app settings you need depend on the managed identity type, either system-assigned or user-assigned.

Setting name	System-assigned	User-assigned	App registration
AzureWebJobsSecretStorageKeyVaultUri	✓	✓	✓
AzureWebJobsSecretStorageKeyVaultClientId	X	✓	✓
AzureWebJobsSecretStorageKeyVaultClientSecret	X	X	✓
AzureWebJobsSecretStorageKeyVaultTenantId	X	X	✓

Use access keys

HTTP triggered functions can generally be called by using a URL in the format: https://<APP_NAME>.chinacloudsites.cn/api/<FUNCTION_NAME>. When the authorization level of a given function is set a value other than anonymous, you must also provide an access key in your request. The access key can either be provided in the URL using the ?code= query string or in the request header (x-functions-key). For more information, see Access key authorization.

To access the runtime REST APIs (under /admin/), you must provide the master key (_master) in the x-functions-key request header. You can remove the admin endpoints using the functionsRuntimeAdminIsolationEnabled site property.

Get your function access keys

You can get function and host keys programmatically by using these Azure Resource Manager APIs:

To learn how to call Azure Resource Manager APIs, see the Azure REST API reference.

You can use these methods to get access keys without having to use the REST APIs.

Sign in to the Azure portal, then search for and select Function App.
Select the function app you want to work with.
In the left pane, expand Functions, and then select App keys.

The App keys page appears. On this page the host keys are displayed, which can be used to access any function in the app. The system key is also displayed, which gives anyone administrator-level access to all function app APIs.

You can also practice least privilege by using the key for a specific function. You can get function-specific keys from the Function keys tab of a specific HTTP-triggered function.

Run the following script in Azure Cli, the output of which is the default host key, which can be used to access any HTTP triggered function in the function app.

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

In this script, replace <RESOURCE_GROUP> and <APP_NAME> with the resource group and your function app name, respective.

Because the output contains sensitive information, either don't persist the output or secure any persisted file outputs.

Run the following script, the output of which is the default host key, which can be used to access any HTTP triggered function in the function 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

In this script, replace <RESOURCE_GROUP> and <APP_NAME> with the resource group and your function app name, respective.

Renew or create access keys

When you renew or create your access key values, you must manually redistribute the updated key values to all clients that call your function.

You can renew function and host keys programmatically or create new ones by using these Azure Resource Manager APIs:

To learn how to call Azure Resource Manager APIs, see the Azure REST API reference.

You can use these methods to get access keys without having to manually create calls to the REST APIs.

Sign in to the Azure portal, then search for and select Function App.
Select the function app you want to work with.
In the left pane, expand Functions, and then select App keys.

The App keys page appears. On this page the host keys are displayed, which can be used to access any function in the app. The system key is also displayed, which gives anyone administrator-level access to all function app APIs.
Select Renew key value next to the key you want to renew, then select Renew and save.

You can also renew a function key in the Function keys tab of a specific HTTP-triggered function.

Run the following script in Azure Cli, which renews the default host key with a new key value generated by Functions.

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

In this script, replace <RESOURCE_GROUP> and <APP_NAME> with the resource group and your function app name, respective. This script has been created to run in Azure Cli (Bash). You must modify it to run in a Windows terminal.

The new key value generated by Functions is displayed for your reference. This new key value must be securely distributed to any apps that rely on the host key. Because the output contains sensitive information, either don't persist the output or secure any persisted file outputs.

Run the following script, which uses the REST APIs to renew the default host key with a new key value generated by Functions.

# Variables - replace these with your actual values
$resourceGroupName = "<RESOURCE_GROUP>"
$functionAppName = "<APP_NAME>" 

# Construct the URI for the REST API call
$uri = "https://management.chinacloudapi.cn/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

In this script, replace <RESOURCE_GROUP> and <APP_NAME> with the resource group and your function app name, respective.

The new key value generated by Functions is returned for your reference. It must be securely distributed to any apps that rely on the host key. Because the output contains sensitive information, either don't persist the output or secure any persisted file outputs.

Delete access keys

You can delete function and host keys programmatically by using these Azure Resource Manager APIs:

To learn how to call Azure Resource Manager APIs, see the Azure REST API reference.

Work with access keys in Azure Functions

Understand keys

Key requirements

Manage key storage

Use access keys

Get your function access keys

Renew or create access keys

Delete access keys

Related content

Additional resources