Configure Functions hospeda armazenamento de chaves no Azure Container Apps

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

As chaves de acesso não são o mesmo que segredos ao nível de uma aplicação. As chaves de acesso protegem quem pode chamar as suas funções, enquanto os segredos ao nível da aplicação protegem aquilo a que as suas funções se ligam.

Quando usar chaves de acesso

Pré-requisitos

• Uma conta do Azure com uma assinatura ativa. Cria uma conta gratuitamente.
• CLI do Azure versão 2.40.0 ou superior.
• Uma aplicação Funções do Azure existente nas Aplicações Container ou permissões para criar uma.

Tipos de chaves de acesso

O runtime das Funções gere quatro tipos de chaves:

Padrões secretos de nomes

A convenção de nomenclatura para chaves armazenadas depende do backend de armazenamento.

Cofre de Chaves

O backend Key Vault armazena cada chave como um segredo individual de Key Vault usando uma convenção de duplo hífen (--):

Armazenamento de Blobs

O backend Armazenamento de Blobs armazena chaves como ficheiros JSON no contentor de blob azure-webjobs-secrets. Todas as chaves ao nível do host (mestre, chaves de função e chaves do sistema) são armazenadas juntas numa única host.json bolha. As chaves por função são armazenadas em blobs separados nomeados em referência a cada função.

Armazenamento secreto de Aplicações de Contentores

A loja secreta Container Apps usa uma convenção diferente. O host das Functions lê as chaves a partir de ficheiros montados em volume em /run/secrets/functions-keys/. Cada ficheiro usa um nome pontilhado (por exemplo, host.master), mas os nomes secretos das Aplicações de Contentor só permitem caracteres alfanuméricos minúsculos e traços. Quando monta um volume secreto, deve definir explicitamente o path campo para o nome do ficheiro pontilhado que o anfitrião Functions espera (por exemplo, secretRef: host-master → path: host.master). A plataforma não realiza qualquer tradução automática de nomes.

Escolha um backend de armazenamento

Defina a variável de ambiente AzureWebJobsSecretStorageType para controlar onde o runtime persiste as chaves de acesso. Azure Container Apps suporta três backends de grau de produção.

Configurar a loja secreta Container Apps

A loja secreta Container Apps é o backend recomendado. As chaves permanecem dentro da plataforma Container Apps e não requerem armazenamento externo nem Key Vault. Os registos de atividade do Azure Resource Manager acompanham alterações a segredos e variáveis de ambiente.

Com este backend, o host Functions lê chaves de ficheiros montados em volumes em /run/secrets/functions-keys/. O anfitrião não gera automaticamente as chaves. Deve criar cada chave como um segredo de Aplicações de Contentores, e a plataforma monta-os como ficheiros para o host ler.

Passo 1: Definir o tipo de armazenamento

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

Passo 2: Gerar e armazenar segredos da chave de acesso

Gerar valores-chave e armazená-los como segredos das Apps Container. No mínimo, precisas da chave mestra e de uma chave 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"

Passo 3: Configurar a montagem do volume

Monte os segredos como ficheiros 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

Passo 4: Verificar

Depois de a aplicação reiniciar, confirme que as teclas estão a funcionar:

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

Também pode verificar os registos da app para a mensagem Resolved secret storage provider ContainerAppsSecretsRepository, que confirma que o anfitrião está a usar a loja secreta Container Apps.

Rodar teclas

Para rodar uma chave criptográfica, atualize o segredo das Aplicações Container e reinicie a aplicação.

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 Armazenamento de Blob (Armazenamento de Blobs)

O backend do Armazenamento de Blobs permite ao runtime gerar e gerir automaticamente chaves de acesso. Use esta opção quando já tiver uma conta AzureWebJobsStorage de armazenamento e não precisar de governação centralizada.

1. Ative a identidade gerida na sua aplicação de contentores (se ainda não estiver ativada):

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

2. Conceda a função Contribuidor de Dados do Blob de Armazenamento na conta de armazenamento à identidade gerida:

   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 as chaves automaticamente no próximo arranque a frio. Verificar:

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

Configurar Cofre de Chaves

O backend do Key Vault armazena as chaves de acesso como segredos do Key Vault, proporcionando auditoria e controlo de acesso de nível empresarial.

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

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

2. Ative a identidade gerida na sua aplicação de contentores (se ainda não estiver ativada):

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

3. Conceda o papel de Oficial de Segredos do Cofre de Chaves à identidade gerida. O runtime necessita de acesso de leitura e escrita para criar e gerir 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 o URI do Key Vault:

   Para a identidade atribuída ao 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 utilizador, defina também o 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. Desencadear a criação de chaves ao listar chaves:

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

Gerir chaves de acesso

Independentemente do backend, use os seguintes comandos para listar, criar e eliminar 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

Passa a chave como parâmetro de consulta ou cabeçalho de pedido.

# 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 das funções
• Segredos ao nível da aplicação Store
• Gerir segredos em Azure Container Apps
• Teclas de Gestão de Funções
• Identidades gerenciadas em aplicativos de contêiner
• Visão geral de Funções do Azure em Azure Container Apps