Trabalhar com chaves de acesso no Azure Functions

O Azure Functions permite usar chaves secretas para dificultar o acesso aos pontos de extremidade da 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.

Como 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	Descrição
Função	default ou definido pelo usuário	function	Permite o acesso apenas a um endpoint de função específico.
Anfitrião	default ou definido pelo usuário	function	Permite o acesso a todos os endpoints de função numa aplicação de funções.
Mestrado	_master	admin	Chave de host especial que também fornece acesso administrativo às APIs REST durante a execução numa aplicação de funções. 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 gerida pelo sistema para aceder aos endpoints de webhook. As chaves do sistema são projetadas para pontos de extremidade de funções específicos para extensões que são chamados por componentes internos. Por exemplo, o gatilho Evento Grid requer que a assinatura use uma chave de sistema ao chamar o ponto de extremidade do gatilho. Durable Functions também usa chaves do sistema para chamar APIs da extensão Durable Task. 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	Função
Executar uma função	Qualquer função	Função ou host
Chamar um endpoint admin	App de Funções	Apenas para mestre
Invocar APIs da extensão de tarefas duráveis	Aplicação de Funções*	Sistema
Chamar um Webhook específico da extensão (interno)	Aplicação de Funções*	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 chaves são armazenadas num contêiner de armazenamento 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	Descrição
Uma segunda conta de armazenamento	blob	Armazena chaves no armazenamento de Blob numa conta de armazenamento diferente da usada pelo runtime das 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 configurado em 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 em sistema de ficheiros 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. Segredos imutáveis não são suportados

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 de configuração	Atribuído pelo sistema	Atribuída pelo utilizador	Registo de aplicações
AzureWebJobsSecretStorageKeyVaultUri	✓	✓	✓
AzureWebJobsSecretStorageKeyVaultClientId	X	✓	✓
AzureWebJobsSecretStorageKeyVaultClientSecret	X	X	✓
AzureWebJobsSecretStorageKeyVaultTenantId	X	X	✓

Importante

Os segredos não estão confinados a aplicações de funções individuais através da AzureWebJobsSecretStorageKeyVaultUri configuração. Se várias aplicações de função estiverem configuradas para usar o mesmo Cofre de Chaves, partilham os mesmos segredos, potencialmente levando a conflitos ou substituições de chaves. Para evitar comportamentos não intencionais, é recomendável usar uma instância separada do Cofre de Chaves para cada aplicativo de função.

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 aceder às APIs REST de tempo de execução (em /admin/), deve fornecer a chave mestra (_master) no cabeçalho do pedido x-functions-key. Você pode remover os pontos de extremidade de administrador usando a functionsRuntimeAdminIsolationEnabled propriedade do 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 Slots de Chaves de Host.

Para saber como chamar as 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 o princípio do privilégio mínimo usando a chave para uma função específica. Pode obter teclas específicas de função na guia Teclas de Função de uma função específica acionada por HTTP.

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 aceder a qualquer função HTTP acionada na aplicação de funções.

$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 as 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 específica acionada por HTTP.

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:

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

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

Conteúdos relacionados

• Aumentando a segurança das Azure Functions
• Gatilho HTTP do Azure Functions
• Gerenciar seu aplicativo de função