Trabalhar com chaves de acesso no Azure Functions

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

Embora as chaves de acesso forneçam algum nível de mitigação contra o acesso indesejado, você deve pensar em 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 sua função estiver sendo chamada a partir de um cliente público, você deve pensar em implementar esses ou outros mecanismos de segurança:

• Habilitar a 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ções em uma rede virtual
• Implantar o aplicativo de funções isoladamente

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

Entenda as chaves

O escopo de uma chave de acesso e as ações que ela respalda 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 somente a um ponto de extremidade de função específico.
Host	default ou definido pelo usuário	function	Permite o acesso a todos os pontos de extremidade de função em um aplicativo de funções.
Mestre	_master	admin	Chave de host especial, que também fornece acesso administrativo às APIs REST do runtime em um aplicativo de funções. Não é possível revogar essa chave. Devido às permissões de nível elevado concedidas pela chave mestra no seu aplicativo de funções, você não deve compartilhar essa chave com terceiros nem distribuí-la em aplicativos de clientes nativos.
Sistema	Depende do tipo de extensão	N/D	Extensões específicas podem requerer uma chave gerenciada pelo sistema para acessar pontos de extremidade de webhook. As chaves do sistema foram criadas para pontos de extremidade de função específicos da 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. O Durable Functions também usa as 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 seus valores explicitamente. Assim como outras chaves, você pode gerar um novo valor para a chave do portal ou usar as APIs de chave.

Cada chave recebe um nome para referência e existe uma chave padrão (chamada default) no nível da função e do host. As chaves de função têm precedência sobre as chaves de host. Quando duas chaves forem definidas com o mesmo nome, a chave de função sempre será usada.

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

Ação	Escopo	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 ponto de extremidade admin	Aplicativo de funções	Somente mestre
Chamar APIs de extensão de tarefa durável	Aplicativo de funções*	Sistema
Chamar um webhook específico da extensão (interno)	Aplicativo de funções*	sistema

^*Escopo determinado pela extensão.

Requisitos de chave

No Functions, as chaves de acesso são geradas aleatoriamente por matrizes de 32 bytes 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 fortemente que você permita que o Functions gere todas as suas chaves de acesso.

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 informam que ela foi gerada pelo Azure Functions. O fato de 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 as chaves para você, não forneça a chave value para nenhuma das APIs que você pode usar para gerar chaves.

Gerenciar o armazenamento de chaves

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

Localidade	Valor	Descrição
Uma segunda conta de armazenamento	blob	Armazena chaves no Armazenamento de Blobs em uma conta de armazenamento diferente da usada pelo runtime do Functions. A conta e o contêiner específicos que são usados são definidos por uma URL de assinatura de acesso compartilhado (SAS) definida na configuração AzureWebJobsSecretStorageSas. Você precisa fazer a manutenção da configuração AzureWebJobsSecretStorageSas quando a URL da SAS sofrer alterações.
Azure Key Vault	keyvault	O cofre de chaves configurado em AzureWebJobsSecretStorageKeyVaultUri é usado para armazenar chaves.
Sistema de arquivos	files	As chaves são persistidas no sistema de arquivos local, que é o padrão no Functions v1.x. O armazenamento no sistema de arquivos não é recomendado.
Segredos do Kubernetes	kubernetes	O conjunto de recursos em AzureWebJobsKubernetesSecretName é usado para armazenar chaves. Têm suporte somente quando seu aplicativo de funções é implantado no Kubernetes. As Ferramentas Básicas do Azure Functions geram os valores automaticamente quando você as usa para implantar seu aplicativo em um cluster do Kubernetes.

Ao usar o Key Vault para o armazenamento de chaves, as configurações de aplicativo de que você vai precisar irão depender do tipo de identidade gerenciada — se atribuída pelo sistema ou atribuída pelo usuário.

Nome da configuração	Atribuída pelo sistema	Atribuída pelo usuário	Registro do aplicativo
AzureWebJobsSecretStorageKeyVaultUri	✓	✓	✓
AzureWebJobsSecretStorageKeyVaultClientId	X	✓	✓
AzureWebJobsSecretStorageKeyVaultClientSecret	X	X	✓
AzureWebJobsSecretStorageKeyVaultTenantId	X	X	✓

Usar chaves de acesso

As funções disparadas 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 com um valor diferente de anonymous, você precisa também fornecer uma chave de acesso na sua solicitação. A chave de acesso pode ser fornecida na URL usando a cadeia de caracteres de consulta ?code= ou no cabeçalho da solicitação (x-functions-key). Para obter mais informações, confira Autorização da chave de acesso.

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

Obter chaves de acesso de função

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

• Listar Chaves de Função
• Listar Chaves de Host
• Listar o Slot de Chaves de Função
• Listar o Slot de Chaves de Host

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

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

Portal do Azure

1. Entre no portal do Azure, em seguida, procure e selecione Aplicativo de Funções.

2. Selecione o aplicativo de funções com o qual você quer trabalhar.

3. No painel do lado esquerdo, expanda Funções e, a seguir, selecione Chaves de aplicativo.

   A página Chaves do aplicativo irá aparecer. Nessa página são exibidas as chaves de host, que podem ser usadas para acessar qualquer função no aplicativo. Também é mostrada a chave do sistema, que concede a qualquer pessoa no nível de administrador acesso a todas as APIs do aplicativo de funções.

Você também pode praticar o privilégio mínimo usando a chave para uma função específica. Você pode obter chaves específicas para cada função na guia Chaves de função de uma função específica disparada por HTTP.

CLI do Azure

Execute o script a seguir no Azure Cloud Shell, cujo resultado é a chave de host default, que pode ser usada para acessar qualquer função disparada por HTTP no aplicativo de funções.

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

Nesse script, substitua <RESOURCE_GROUP> e <APP_NAME> pelo grupo de recursos e o nome do seu aplicativo de funções, respectivamente.

Já que o resultado contém informações confidenciais, você tem a opção de não persisti-lo ou de proteger quaisquer resultados de arquivo persistidos.

PowerShell do Azure

Execute o script a seguir, cujo resultado é a chave de host default, que pode ser usada para acessar qualquer função disparada por HTTP no aplicativo 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

Nesse script, substitua <RESOURCE_GROUP> e <APP_NAME> pelo grupo de recursos e o nome do seu aplicativo de funções, respectivamente.

Renovar ou criar chaves de acesso

Quando renovar ou criar os valores da sua chave de acesso, você precisará redistribuir manualmente os valores de chave atualizados para todos os clientes que chamam sua função.

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

• Criar ou Atualizar o Segredo da Função
• Criar ou Atualizar o Slot do Segredo da Função
• Criar ou Atualizar o Segredo do Host
• Criar ou Atualizar o Slot do Segredo do Host

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

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

Portal do Azure

1. Entre no portal do Azure, em seguida, procure e selecione Aplicativo de Funções.

2. Selecione o aplicativo de funções com o qual você quer trabalhar.

3. No painel do lado esquerdo, expanda Funções e, a seguir, selecione Chaves de aplicativo.

   A página Chaves do aplicativo irá aparecer. Nessa página são exibidas as chaves de host, que podem ser usadas para acessar qualquer função no aplicativo. Também é mostrada a chave do sistema, que concede a qualquer pessoa no nível de administrador acesso a todas as APIs do aplicativo de funções.

4. Selecione Renovar o valor da chave ao lado da chave que você quiser renovar e, em seguida, selecione Renovar e salvar.

Você também pode renovar uma chave de função na guia Chaves de função de uma função específica disparada por HTTP.

CLI do Azure

No Azure Cloud Shell, execute o script a seguir, que renova a chave de host default 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

Nesse script, substitua <RESOURCE_GROUP> e <APP_NAME> pelo grupo de recursos e o nome do seu aplicativo de funções, respectivamente. Esse script foi criado para ser executado no Azure Cloud Shell (Bash). Você precisa modificá-lo para ser executado em um terminal do Windows.

O novo valor de chave gerado pelo Functions é mostrado para sua referência. Esse novo valor de chave precisa ser distribuído com segurança para todos os aplicativos que dependem da chave de host. Já que o resultado contém informações confidenciais, você tem a opção de não persisti-lo ou de proteger quaisquer resultados de arquivo persistidos.

PowerShell do Azure

Execute o script a seguir, que usa as APIs REST para renovar a chave de host default 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

Nesse script, substitua <RESOURCE_GROUP> e <APP_NAME> pelo grupo de recursos e o nome do seu aplicativo de funções, respectivamente.

O novo valor de chave gerado pelo Functions é retornado para sua referência e precisa ser distribuído com segurança para todos os aplicativos que dependem da chave de host. Já que o resultado contém informações confidenciais, você tem a opção de não persisti-lo ou de proteger quaisquer resultados de arquivo persistidos.

Excluir chaves de acesso

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

• Excluir o Segredo da Função
• Excluir o Slot do Segredo da Função
• Excluir o Segredo do Host
• Excluir o Slot do Segredo do Host

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

Conteúdo relacionado

• Proteger o Azure Functions
• Gatilho de HTTP do Azure Functions
• Gerenciar seu aplicativo de funções