Trabalhar com chaves de acesso no Azure Functions

O Azure Functions permite que você use chaves secretas para dificultar o acesso aos pontos de extremidade de função. Este artigo descreve os vários tipos de chaves de acesso suportadas pelo Functions e como trabalhar com chaves de acesso.

Embora as chaves de acesso forneçam alguma atenuação contra acesso indesejado, você deve considerar outras opções para proteger pontos de extremidade HTTP na produção. Por exemplo, não é uma boa prática distribuir segredos compartilhados em um aplicativo público. Se a sua função estiver a ser chamada por um cliente público, deve considerar a implementação destes ou de outros mecanismos de segurança:

• Habilitar autenticação/autorização do Serviço de Aplicativo
• Usar o Gerenciamento de API do Azure (APIM) para autenticar solicitações
• Implantar seu aplicativo de função em uma rede virtual
• Implante seu aplicativo de função de forma isolada

As chaves de acesso fornecem a base para a autorização HTTP em funções acionadas por HTTP. Para obter mais informações, consulte Nível de autorização.

Compreender as chaves

O âmbito de uma chave de acesso e as ações que suporta dependem do tipo de chave de acesso.

Tipo de chave	Nome da chave	Nível de autenticação HTTP	Description
Função	default ou definido pelo usuário	function	Permite o acesso apenas a um ponto de extremidade de função específico.
Anfitrião	default ou definido pelo usuário	function	Permite o acesso a todos os pontos de extremidade de função em um aplicativo de função.
Mestrado	_master	admin	Chave de host especial que também fornece acesso administrativo às APIs REST de tempo de execução em um aplicativo de função. Esta chave não pode ser revogada. Como a chave mestra concede permissões elevadas em seu aplicativo de função, você não deve compartilhar essa chave com terceiros ou distribuí-la em aplicativos cliente nativos.
Sistema	Depende da extensão	n/d	Extensões específicas podem exigir uma chave gerenciada pelo sistema para acessar pontos de extremidade webhook. As chaves do sistema são projetadas para pontos de extremidade de função específicos de extensão que são chamados por componentes internos. Por exemplo, o gatilho de Grade de Eventos requer que a assinatura use uma chave do sistema ao chamar o ponto de extremidade do gatilho. Durable Functions também usa chaves do sistema para chamar APIs de extensão de tarefa durável. As chaves do sistema só podem ser criadas por extensões específicas e você não pode definir explicitamente seus valores. Como outras chaves, você pode gerar um novo valor para a chave a partir do portal ou usando as APIs de chave.

Cada chave é nomeada para referência, e há uma chave padrão (chamada default) no nível da função e do host. As teclas de função têm precedência sobre as teclas de host. Quando duas teclas são definidas com o mesmo nome, a tecla de função é sempre usada.

A tabela a seguir compara os usos para vários tipos de chaves de acesso:

Ação	Âmbito	Tipo de chave
Executar uma função	Função específica	Function
Executar uma função	Qualquer função	Função ou host
Chamar um ponto de admin extremidade	Aplicação de funções	Apenas mestre
Chamar APIs de extensão de tarefa durável	Aplicação Função*	Sistema
Chamar um Webhook específico da extensão (interno)	Aplicação Função*	sistema

^*Âmbito determinado pela extensão.

Requisitos chave

Em Funções, as chaves de acesso são matrizes de 32 bytes geradas aleatoriamente que são codificadas como cadeias de caracteres base-64 seguras para URL. Embora você possa gerar suas próprias chaves de acesso e usá-las com o Functions, recomendamos que você permita que o Functions gere todas as suas chaves de acesso para você.

As chaves de acesso geradas por funções incluem valores especiais de assinatura e soma de verificação que indicam o tipo de chave de acesso e que ela foi gerada pelo Azure Functions. Ter esses componentes extras na própria chave torna muito mais fácil determinar a origem desses tipos de segredos localizados durante a verificação de segurança e outros processos automatizados.

Para permitir que o Functions gere suas chaves para você, não forneça a chave value para nenhuma das APIs que você pode usar para gerar chaves.

Gerenciar armazenamento de chaves

As chaves são armazenadas como parte do seu aplicativo de função no Azure e são criptografadas em repouso. Por padrão, as AzureWebJobsStorage chaves são armazenadas em um contêiner de armazenamento de Blob na conta fornecida pela configuração. Você pode usar a AzureWebJobsSecretStorageType configuração para substituir esse comportamento padrão e, em vez disso, armazenar chaves em um destes locais alternativos:

Localização	Valor	Description
Uma segunda conta de armazenamento	blob	Armazena chaves no armazenamento de Blob em uma conta de armazenamento diferente da usada pelo tempo de execução do Functions. A conta específica e o contêiner usados são definidos por uma URL de assinatura de acesso compartilhado (SAS) definida na AzureWebJobsSecretStorageSas configuração. Você deve manter a AzureWebJobsSecretStorageSas configuração quando a URL SAS for alterada.
Azure Key Vault	keyvault	O cofre de chaves definido é AzureWebJobsSecretStorageKeyVaultUri usado para armazenar chaves.
Sistema de ficheiros	files	As chaves são mantidas no sistema de arquivos local, que é o padrão no Functions v1.x. O armazenamento do sistema de arquivos não é recomendado.
Segredos de Kubernetes	kubernetes	O conjunto de recursos no AzureWebJobsKubernetesSecretName é utilizado para armazenar chaves. Suportado apenas quando seu aplicativo de função é implantado no Kubernetes. As Ferramentas Principais do Azure Functions geram os valores automaticamente quando você as usa para implantar seu aplicativo em um cluster do Kubernetes.

Ao usar o Cofre da Chave para armazenamento de chaves, as configurações do aplicativo de que você precisa dependem do tipo de identidade gerenciada, atribuída pelo sistema ou atribuída pelo usuário.

Nome da definição	Atribuída pelo sistema	Atribuída pelo utilizador	Registo de aplicações
AzureWebJobsSecretStorageKeyVaultUri	✓	✓	✓
AzureWebJobsSecretStorageKeyVaultClientId	X	✓	✓
AzureWebJobsSecretStorageKeyVaultClientSecret	X	X	✓
AzureWebJobsSecretStorageKeyVaultTenantId	X	X	✓

Utilizar teclas de acesso

As funções acionadas por HTTP geralmente podem ser chamadas usando uma URL no formato: https://<APP_NAME>.azurewebsites.net/api/<FUNCTION_NAME>. Quando o nível de autorização de uma determinada função é definido como um valor diferente de anonymous, você também deve fornecer uma chave de acesso em sua solicitação. A chave de acesso pode ser fornecida na URL usando a cadeia de caracteres de ?code= consulta ou no cabeçalho da solicitação (x-functions-key). Para obter mais informações, consulte Autorização de chave de acesso.

Para acessar as APIs REST de tempo de execução (em /admin/), você deve fornecer a chave mestra (_master) no cabeçalho da x-functions-key solicitação. Você pode remover os pontos de extremidade admin usando a functionsRuntimeAdminIsolationEnabled propriedade site.

Obtenha as teclas de acesso à sua função

Você pode obter chaves de função e host programaticamente usando estas APIs do Azure Resource Manager:

• Listar teclas de função
• Listar chaves de host
• Listar slot de teclas de função
• Listar Slot de Chaves de Host.

Para saber como chamar APIs do Azure Resource Manager, consulte a referência da API REST do Azure.

Você pode usar esses métodos para obter chaves de acesso sem ter que usar as APIs REST.

Portal do Azure

1. Entre no portal do Azure e, em seguida, procure e selecione Aplicativo de função.

2. Selecione o aplicativo de função com o qual deseja trabalhar.

3. No painel esquerdo, expanda Funções e selecione Teclas do aplicativo.

   A página Chaves do aplicativo é exibida. Nesta página são exibidas as chaves de host, que podem ser usadas para acessar qualquer função no aplicativo. A chave do sistema também é exibida, o que dá a qualquer pessoa acesso em nível de administrador a todas as APIs de aplicativos funcionais.

Você também pode praticar privilégios mínimos usando a tecla para uma função específica. Você pode obter teclas específicas da função na guia Teclas de função de uma função acionada por HTTP específica.

CLI do Azure

Execute o seguinte script no Azure Cloud Shell, cuja saída é a default chave do host, que pode ser usada para acessar qualquer função acionada por HTTP no aplicativo de função.

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

Neste script, substitua <RESOURCE_GROUP> e <APP_NAME> pelo grupo de recursos e pelo nome do aplicativo de função, respetivo.

Como a saída contém informações confidenciais, não persista a saída ou proteja qualquer saída de arquivo persistente.

Azure PowerShell

Execute o script a seguir, cuja saída é a default chave do host, que pode ser usada para acessar qualquer função acionada HTTP no aplicativo de função.

$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

Neste script, substitua <RESOURCE_GROUP> e <APP_NAME> pelo grupo de recursos e pelo nome do aplicativo de função, respetivo.

Renovar ou criar chaves de acesso

Ao renovar ou criar seus valores de chave de acesso, você deve redistribuir manualmente os valores de chave atualizados para todos os clientes que chamam sua função.

Você pode renovar chaves de função e host programaticamente ou criar novas usando estas APIs do Azure Resource Manager:

• Criar ou atualizar segredo de função
• Criar ou atualizar slot secreto de função
• Criar ou atualizar segredo do host
• Criar ou atualizar slot secreto do host

Para saber como chamar APIs do Azure Resource Manager, consulte a referência da API REST do Azure.

Você pode usar esses métodos para obter chaves de acesso sem ter que criar manualmente chamadas para as APIs REST.

Portal do Azure

1. Entre no portal do Azure e, em seguida, procure e selecione Aplicativo de função.

2. Selecione o aplicativo de função com o qual deseja trabalhar.

3. No painel esquerdo, expanda Funções e selecione Teclas do aplicativo.

   A página Chaves do aplicativo é exibida. Nesta página são exibidas as chaves de host, que podem ser usadas para acessar qualquer função no aplicativo. A chave do sistema também é exibida, o que dá a qualquer pessoa acesso em nível de administrador a todas as APIs de aplicativos funcionais.

4. Selecione Renovar valor da chave junto à chave que pretende renovar e, em seguida, selecione Renovar e guardar.

Você também pode renovar uma tecla de função na guia Teclas de função de uma função acionada por HTTP específica.

CLI do Azure

Execute o seguinte script no Azure Cloud Shell, que renova a chave de default host com um novo valor de chave gerado pelo Functions.

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

Neste script, substitua <RESOURCE_GROUP> e <APP_NAME> pelo grupo de recursos e pelo nome do aplicativo de função, respetivo. Este script foi criado para ser executado no Azure Cloud Shell (Bash). Você deve modificá-lo para ser executado em um terminal do Windows.

O novo valor de chave gerado por Functions é exibido para sua referência. Esse novo valor de chave deve ser distribuído com segurança para todos os aplicativos que dependem da chave do host. Como a saída contém informações confidenciais, não persista a saída ou proteja qualquer saída de arquivo persistente.

Azure PowerShell

Execute o script a seguir, que usa as APIs REST para renovar a chave do default host com um novo valor de chave gerado pelo 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.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

Neste script, substitua <RESOURCE_GROUP> e <APP_NAME> pelo grupo de recursos e pelo nome do aplicativo de função, respetivo.

O novo valor de chave gerado por Functions é retornado para sua referência. Ele deve ser distribuído com segurança para todos os aplicativos que dependem da chave do host. Como a saída contém informações confidenciais, não persista a saída ou proteja qualquer saída de arquivo persistente.

Excluir chaves de acesso

Você pode excluir chaves de função e host programaticamente usando estas APIs do Azure Resource Manager:

• Excluir segredo da função
• Excluir slot secreto de função
• Excluir segredo do host
• Excluir slot secreto do host

Para saber como chamar APIs do Azure Resource Manager, consulte a referência da API REST do Azure.

Conteúdos relacionados

• Protegendo o Azure Functions
• Gatilho HTTP do Azure Functions
• Gerenciar seu aplicativo de função