Trabalhar com chaves de acesso no Azure Functions

As chaves de acesso do Azure Functions atuam como segredos compartilhados que autorizam o acesso aos endpoints de funções. Este artigo descreve os tipos de chaves de acesso compatíveis com o Functions e como trabalhar com chaves de acesso.

Embora as chaves de acesso ofereçam alguma proteção contra acessos indesejados, considere outras opções para proteger endpoints HTTP em produção. Por exemplo, não distribua segredos compartilhados em um aplicativo público. Se um cliente público chamar sua função, considere implementar estes ou outros mecanismos de segurança:

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

Tipos de chave de acesso

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.
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çõ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. Como a chave mestra concede permissões elevadas no seu aplicativo de funções, não compartilhe essa chave com terceiros nem a distribua em aplicativos 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 são projetadas para endpoints específicos de funções de extensão que os componentes internos chamam. 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. Somente extensões específicas podem criar chaves do sistema. Você não pode definir explicitamente seus valores. Assim como outras chaves, você pode gerar um novo valor para a chave do portal ou usar as APIs de chave.

Cada chave tem um nome para referência. O aplicativo de funções e os níveis de função têm, cada um, uma chave padrão chamada default. As chaves de função têm precedência sobre as chaves de host. Quando duas teclas têm 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	Scope	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	Senhor
Chamar APIs de extensão de tarefa durável	Aplicativo de funções^*	Sistema
Chame um webhook específico da extensão (interno)	Aplicativo de funções^*	Sistema

^*Escopo determinado pela extensão.

Requisitos da chave de acesso

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 Funções, use o processo padrão de geração de 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 que o Azure Functions a gerou. Esses componentes extras na chave facilitam a determinação da origem desses tipos de segredos durante varreduras de segurança e outros processos automatizados.

Para permitir que as Funções gerem suas chaves, não forneça a chave value para nenhuma das APIs que você pode usar para gerar chaves.

Armazenamento de chaves de acesso

Seu aplicativo de funções no Azure armazena chaves e as criptografa em repouso. Por padrão, a AzureWebJobsStorage configuração armazena chaves em um contêiner de armazenamento Blob na conta fornecida. Use a configuração AzureWebJobsSecretStorageType para substituir esse comportamento padrão e armazenar as chaves em um destes locais alternativos:

Importante

As chaves de acesso fazem parte do armazenamento secreto do seu app e têm seu próprio ciclo de vida, independente das funções que protegem. Deletar uma função não exclui nem gira as chaves mantidas no armazenamento secreto. Como a localização de armazenamento de uma chave é derivada do nome do app, recriar uma função com o mesmo nome reutiliza as chaves previamente armazenadas em vez de gerar novas. Esse comportamento se aplica a todos os provedores de armazenamento secreto, incluindo armazenamento Blob e Key Vault. Deletar e recriar uma função não substitui a rotação de chaves: para revogar uma chave quando uma credencial é exposta ou você está removendo o acesso de alguém, você deve girá-la ou excluí-la explicitamente, como descrito em Renovar ou criar chaves de acesso.

Location	Valor	Descrição
Uma segunda conta de armazenamento	`blob`	Armazena chaves no armazenamento Blob em uma conta de armazenamento diferente daquela usada pelo runtime das funções. A conta específica e o contêiner usados são definidos por uma URL de SAS (assinatura de acesso compartilhado) definida na `AzureWebJobsSecretStorageSas` configuração. Você precisa fazer a manutenção da configuração `AzureWebJobsSecretStorageSas` quando a URL da SAS sofrer alterações.
Azure Key Vault	`keyvault`	Armazena chaves no cofre de chaves definido em `AzureWebJobsSecretStorageKeyVaultUri`.
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`	Armazena chaves no conjunto de recursos em `AzureWebJobsKubernetesSecretName`. 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. Não há suporte para segredos imutáveis.
Segredos dos Aplicativos de Contêiner do Azure	`containerapps`	As chaves são armazenadas no repositório de segredos Aplicativos de Contêiner do Azure, que é o sistema de gerenciamento de segredos internos para Aplicativos de Contêiner. Com suporte somente quando seu aplicativo de funções é implantado nos Aplicativos de Contêiner do Azure. Para informações, veja Configurar a loja secreta de Apps de Contêineres.

Quando você usa o Key Vault para armazenamento de chaves, as configurações do aplicativo que você precisa dependem de como o app se autentica no Key Vault: uma identidade gerenciada atribuída pelo sistema, uma identidade gerenciada atribuída pelo usuário ou um registro de aplicativo.

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

Importante

Os segredos não têm escopo para aplicativos de funções individuais por meio da configuração AzureWebJobsSecretStorageKeyVaultUri. Se vários aplicativos de funções estiverem configurados para usar o mesmo Key Vault, eles compartilharão os mesmos segredos, potencialmente levando a colisões de chave ou substituições. Para evitar comportamentos não intencionais, recomendamos que você use uma instância separada do Key Vault para cada aplicativo de funções.

Chamar endpoints com chaves de acesso

Você pode chamar funções ativadas por HTTP usando uma URL que inclua o nome da função. Quando você define o nível de autorização de uma função para qualquer valor diferente de anonymous, você também deve fornecer uma chave de acesso em sua solicitação. Você pode incluir a chave de acesso na URL usando a ?code= string de consulta ou no cabeçalho de requisiçã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 desativar endpoints administrativos ao definir a propriedade functionsRuntimeAdminIsolationEnabled do site.

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:

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

Note

Quando você implanta seu aplicativo de funções no Aplicativos de Contêiner do Azure e usa AzureWebJobsSecretStorageType=ContainerApps, deve usar métodos específicos do Aplicativos de Contêiner do Azure para recuperar as chaves de função. Para mais informações, consulte Gerenciar chaves de acesso na documentação do Container Apps.

Use esses métodos para obter chaves de acesso sem usar as APIs REST.

Faça login no portal do Azure e então pesquise e selecione Function App.
Selecione o aplicativo de funções com o qual você quer trabalhar.
No menu à esquerda, expanda Funções e, em seguida, selecione Chaves de aplicativo.

A página Chaves do aplicativo irá aparecer. Nesta página, as chaves host são exibidas, que você pode usar para acessar qualquer função do app. 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.

Execute o comando a seguir no Azure Cloud Shell. A saída do comando é a chave de host default, que você pode usar para acessar qualquer função com gatilho HTTP no aplicativo de funções.

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

Substitua <RESOURCE_GROUP> e <APP_NAME> com o grupo de recursos e o nome do aplicativo de funções.

Como a saída contém informações sensíveis, não persista a saída nem proteja nenhuma saída de arquivo persistente.

Execute o seguinte script. A saída é a chave de host default, que você pode usar para acessar qualquer função acionada por HTTP no aplicativo de funções.

$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> pelos grupo de recursos e nome do aplicativo de funções.

Dica

Você também pode obter chaves de acesso para suas funções usando o comando func azure functionapp list-functions Azure Functions Core Tools com a opção --show-keys. Para obter mais informações, consulte a referência do Azure Functions Core Tools.

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.

Importante

Trate a chave mestra (_master) como uma credencial administrativa. Ele concede acesso administrativo e de plano de dados ao seu app — incluindo, em aplicativos com sistema de arquivos gravável, a capacidade de implantar e executar código pelas APIs REST em tempo de execução — então compartilhe apenas com administradores confiáveis, não com chamadores comuns. As chaves de host não são administrativas, mas cada uma autoriza chamadas para qualquer função do app, então distribua-as com cuidado também.

Quando uma credencial for exposta, ou quando você precisar revogar o acesso de uma parte, gire explicitamente as chaves afetadas. Girar uma chave individual é suficiente para revogar essa chave específica. Como mencionado no armazenamento de chaves de acesso, excluir ou recriar uma função não gira as chaves armazenadas.

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

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.

Faça login no portal do Azure e então pesquise e selecione Function App.
Selecione o aplicativo de funções com o qual você quer trabalhar.
No menu à esquerda, expanda Funções e, em seguida, selecione Chaves de aplicativo.

A página Chaves do aplicativo irá aparecer. Nesta página, as chaves host são exibidas, que você pode usar para acessar qualquer função do app. 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.
Selecione Renovar valor da chave ao lado da chave que você quer renovar, e depois 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.

Execute o comando a seguir no Azure Cloud Shell. O comando renova a default chave host com um novo valor de chave gerado por Functions.

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

Neste comando, substitua <RESOURCE_GROUP> e <APP_NAME> pelo grupo de recursos e o nome do seu app de funções. Esse comando é executado no Bash (Azure Cloud Shell). 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. Distribua de forma segura esse novo valor da chave para quaisquer aplicativos que dependam da chave 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.

Execute o seguinte script. O script usa as APIs REST para renovar a default chave host com um novo valor de chave gerado por 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> pelos grupo de recursos e nome do aplicativo de funções.

O novo valor de chave gerado pelo Functions é retornado para sua referência Distribua essa chave de forma segura para quaisquer aplicativos que dependam da chave 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:

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

Comentários

Esta página foi útil?

Last updated on 2026-08-27

Trabalhar com chaves de acesso no Azure Functions

Tipos de chave de acesso

Requisitos da chave de acesso

Armazenamento de chaves de acesso

Chamar endpoints com chaves de acesso

Obter chaves de acesso de função

Renovar ou criar chaves de acesso

Excluir chaves de acesso

Conteúdo relacionado

Comentários

Recursos adicionais