Configurar o armazenamento de chaves do host do Functions no Aplicativos de Contêiner do Azure

As chaves de acesso do Functions são tokens de autenticação que o runtime Functions usa para proteger endpoints acionados por HTTP. Quando um chamador invoca uma função HTTP, ela inclui uma chave como um ?code= parâmetro de consulta ou um x-functions-key cabeçalho. O runtime valida a chave e autoriza ou rejeita a solicitação.

As chaves de acesso não são iguais aos segredos no nível do aplicativo. As chaves de acesso protegem quem pode chamar suas funções, enquanto os segredos no nível do aplicativo protegem ao que suas funções se conectam.

Quando usar chaves de acesso

Pré-requisitos

• Uma conta do Azure com uma assinatura ativa. Crie uma conta gratuitamente.
• CLI do Azure versão 2.40.0 ou superior.
• Um aplicativo Azure Functions existente em Aplicativos de Contêiner ou permissões para criar um.

Tipos de chave de acesso

O runtime do Functions gerencia quatro tipos de chaves:

Padrões de nome secreto

A convenção de nomenclatura para chaves armazenadas depende do back-end de armazenamento.

Cofre de Chaves

O back-end Key Vault armazena cada chave como um segredo de Key Vault individual usando uma convenção de traço duplo (--):

Armazenamento de Blobs

O back-end Armazenamento de Blobs armazena chaves como arquivos JSON no contêiner de blob azure-webjobs-secrets. Todas as chaves no nível do host (mestre, chaves de função e chaves do sistema) são armazenadas juntas em um único host.json blob. As chaves por função são armazenadas em blobs separados com o nome de cada função.

Repositório secreto de Aplicativos de Contêiner

O repositório secreto de Aplicativos de Contêiner usa uma convenção diferente. O host do Functions lê chaves de arquivos montados em volume em /run/secrets/functions-keys/. Cada arquivo usa um nome pontilhado (por exemplo), host.mastermas os nomes secretos dos Aplicativos de Contêiner permitem apenas caracteres alfanuméricos minúsculos e traços. Ao montar um volume secreto, você deve definir explicitamente o path campo como o nome do arquivo pontilhado que o host do Functions espera (por exemplo, secretRef: host-master → path: host.master). A plataforma não executa nenhuma tradução automática de nome.

Escolher um back-end de armazenamento

Defina a variável de ambiente AzureWebJobsSecretStorageType para controlar onde o runtime persiste as chaves de acesso. Aplicativos de Contêiner do Azure dá suporte a três back-ends de nível de produção.

Configurar o repositório secreto de Aplicativos de Contêiner

O repositório secreto de Aplicativos de Contêiner é o back-end recomendado. As chaves permanecem dentro da plataforma de Aplicativos de Contêiner e não exigem armazenamento externo ou Key Vault. Azure Resource Manager logs de atividades acompanham alterações em segredos e variáveis de ambiente.

Com esse back-end, o host do Functions lê chaves de arquivos montados em volume em /run/secrets/functions-keys/. O host não gera chaves automaticamente. Você deve criar cada chave como um segredo dos Aplicativos de Contêiner e a plataforma as monta como arquivos para o host ler.

Etapa 1: Definir o tipo de armazenamento

az containerapp update \
  --resource-group "<RESOURCE_GROUP>" \
  --name "<FUNCTIONS_APP_NAME>" \
  --set-env-vars "AzureWebJobsSecretStorageType=containerapp"

Etapa 2: Gerar e armazenar segredos de chave de acesso

Gere valores de chave e armazene-os como segredos dos Aplicativos de Contêiner. No mínimo, você precisa da chave mestra e de uma chave de host padrão.

# Generate random key values
MASTER_KEY=$(openssl rand -hex 32)
HOST_DEFAULT_KEY=$(openssl rand -hex 32)

# Store as Container Apps secrets
az containerapp secret set \
  --resource-group "<RESOURCE_GROUP>" \
  --name "<FUNCTIONS_APP_NAME>" \
  --secrets "host-master=$MASTER_KEY" "host-function-default=$HOST_DEFAULT_KEY"

FUNC_KEY=$(openssl rand -hex 32)

az containerapp secret set \
  --resource-group "<RESOURCE_GROUP>" \
  --name "<FUNCTIONS_APP_NAME>" \
  --secrets "functions-myhttpfunc-default=$FUNC_KEY"

Etapa 3: Configurar o ponto de montagem do volume

Monte os segredos como arquivos em /run/secrets/functions-keys/.

# Export current config
az containerapp show \
  --resource-group "<RESOURCE_GROUP>" \
  --name "<FUNCTIONS_APP_NAME>" \
  --output yaml > app.yaml

properties:
  template:
    volumes:
      - name: functions-keys
        storageType: Secret
        secrets:
          - secretRef: host-master
            path: host.master
          - secretRef: host-function-default
            path: host.function.default
    containers:
      - name: <CONTAINER_NAME>
        volumeMounts:
          - volumeName: functions-keys
            mountPath: /run/secrets/functions-keys

az containerapp update \
  --resource-group "<RESOURCE_GROUP>" \
  --name "<FUNCTIONS_APP_NAME>" \
  --yaml app.yaml

Etapa 4: Verificar

Depois que o aplicativo for reiniciado, confirme se as chaves estão funcionando:

az containerapp function keys list \
  --resource-group "<RESOURCE_GROUP>" \
  --name "<FUNCTIONS_APP_NAME>" \
  --key-type hostKey

Você também pode verificar os logs do aplicativo para a mensagem Resolved secret storage provider ContainerAppsSecretsRepository, o que confirma que o host está usando o repositório secreto de Aplicativos de Contêiner.

Girar chaves

Para girar uma chave, atualize o segredo dos Aplicativos de Contêiner e reinicie o aplicativo:

NEW_KEY=$(openssl rand -hex 32)

az containerapp secret set \
  --resource-group "<RESOURCE_GROUP>" \
  --name "<FUNCTIONS_APP_NAME>" \
  --secrets "host-function-default=$NEW_KEY"

az containerapp revision restart \
  --resource-group "<RESOURCE_GROUP>" \
  --name "<FUNCTIONS_APP_NAME>" \
  --revision "<REVISION_NAME>"

Configurar o Armazenamento de Blobs

O Armazenamento de Blobs back-end permite que o runtime gere e gerencie automaticamente as chaves de acesso. Use essa opção quando você já tiver uma conta AzureWebJobsStorage de armazenamento e não precisar de governança centralizada.

1. Habilitar a identidade gerenciada em seu aplicativo de contêiner (se ainda não estiver habilitado):

   az containerapp identity assign \
     --resource-group "<RESOURCE_GROUP>" \
     --name "<FUNCTIONS_APP_NAME>" \
     --system-assigned
   

2. Conceda a função Colaborador de Dados de Blob de Armazenamento na conta de armazenamento à identidade gerenciada:

   PRINCIPAL_ID=$(az containerapp show \
     --resource-group "<RESOURCE_GROUP>" \
     --name "<FUNCTIONS_APP_NAME>" \
     --query identity.principalId \
     --output tsv)
   
   STORAGE_ID=$(az storage account show \
     --name "<STORAGE_ACCOUNT_NAME>" \
     --resource-group "<RESOURCE_GROUP>" \
     --query id \
     --output tsv)
   
   az role assignment create \
     --role "Storage Blob Data Contributor" \
     --assignee "$PRINCIPAL_ID" \
     --scope "$STORAGE_ID"
   

3. Defina o tipo de armazenamento:

   az containerapp update \
     --resource-group "<RESOURCE_GROUP>" \
     --name "<FUNCTIONS_APP_NAME>" \
     --set-env-vars "AzureWebJobsSecretStorageType=blob"
   

4. O runtime gera automaticamente as chaves na próxima inicialização a frio. Verificar:

   az containerapp function keys list \
     --resource-group "<RESOURCE_GROUP>" \
     --name "<FUNCTIONS_APP_NAME>" \
     --key-type hostKey
   

Configurar Key Vault

O back-end do Key Vault armazena chaves de acesso como segredos do Key Vault, fornecendo auditoria padrão corporativo e controle de acesso.

1. Crie um Key Vault (se você não tiver um):

   az keyvault create \
     --name "<KEYVAULT_NAME>" \
     --resource-group "<RESOURCE_GROUP>" \
     --location "<LOCATION>"
   

2. Habilitar a identidade gerenciada em seu aplicativo de contêiner (se ainda não estiver habilitado):

   az containerapp identity assign \
     --resource-group "<RESOURCE_GROUP>" \
     --name "<FUNCTIONS_APP_NAME>" \
     --system-assigned
   

3. Conceda a função Key Vault Secrets Officer à identidade gerenciada. O runtime precisa de acesso de leitura e gravação para criar e gerenciar chaves:

   PRINCIPAL_ID=$(az containerapp show \
     --resource-group "<RESOURCE_GROUP>" \
     --name "<FUNCTIONS_APP_NAME>" \
     --query identity.principalId \
     --output tsv)
   
   KEYVAULT_ID=$(az keyvault show \
     --name "<KEYVAULT_NAME>" \
     --query id \
     --output tsv)
   
   az role assignment create \
     --role "Key Vault Secrets Officer" \
     --assignee "$PRINCIPAL_ID" \
     --scope "$KEYVAULT_ID"
   

4. Defina o tipo de armazenamento e Key Vault URI:

   Para identidade atribuída pelo sistema:

   az containerapp update \
     --resource-group "<RESOURCE_GROUP>" \
     --name "<FUNCTIONS_APP_NAME>" \
     --set-env-vars \
       "AzureWebJobsSecretStorageType=keyvault" \
       "AzureWebJobsSecretStorageKeyVaultUri=https://<KEYVAULT_NAME>.vault.azure.net"
   

   Para a identidade atribuída pelo usuário, defina também a ID do cliente:

   az containerapp update \
     --resource-group "<RESOURCE_GROUP>" \
     --name "<FUNCTIONS_APP_NAME>" \
     --set-env-vars \
       "AzureWebJobsSecretStorageType=keyvault" \
       "AzureWebJobsSecretStorageKeyVaultUri=https://<KEYVAULT_NAME>.vault.azure.net" \
       "AzureWebJobsSecretStorageKeyVaultClientId=<USER_ASSIGNED_IDENTITY_CLIENT_ID>"
   

5. Iniciar a criação de chaves listando-as:

   az containerapp function keys list \
     --resource-group "<RESOURCE_GROUP>" \
     --name "<FUNCTIONS_APP_NAME>" \
     --key-type hostKey
   

Gerenciar chaves de acesso

Independentemente do back-end, use os seguintes comandos para listar, criar e excluir chaves de acesso:

# List all host keys
az containerapp function keys list \
  --resource-group "<RESOURCE_GROUP>" \
  --name "<FUNCTIONS_APP_NAME>" \
  --key-type hostKey

# List the master key
az containerapp function keys list \
  --resource-group "<RESOURCE_GROUP>" \
  --name "<FUNCTIONS_APP_NAME>" \
  --key-type masterKey

# Create or overwrite a custom host key
az containerapp function keys set \
  --resource-group "<RESOURCE_GROUP>" \
  --name "<FUNCTIONS_APP_NAME>" \
  --key-name "MyCustomKey" \
  --key-value "<YOUR_KEY_VALUE>" \
  --key-type hostKey

# Show a specific key
az containerapp function keys show \
  --resource-group "<RESOURCE_GROUP>" \
  --name "<FUNCTIONS_APP_NAME>" \
  --key-name "<KEY_NAME>" \
  --key-type hostKey

# Delete a host key
az containerapp function keys delete \
  --resource-group "<RESOURCE_GROUP>" \
  --name "<FUNCTIONS_APP_NAME>" \
  --key-name "MyCustomKey" \
  --key-type hostKey

Chamar uma função com uma chave de acesso

Passe a chave como um parâmetro de consulta ou cabeçalho de solicitação.

# Query parameter
curl "https://<FUNCTIONS_APP_URL>/api/<FUNCTION_NAME>?code=<HOST_KEY>"

# Header
curl "https://<FUNCTIONS_APP_URL>/api/<FUNCTION_NAME>" \
  -H "x-functions-key: <HOST_KEY>"

Conteúdo relacionado

• Visão geral dos segredos do Functions
• Armazenar segredos no nível do aplicativo
• Gerencie segredos em Aplicativos de Contêiner do Azure
• Gerenciar chaves do Functions
• Identidades gerenciadas em Contêiner Apps
• Visão geral do Azure Functions em Aplicativos de Contêiner do Azure