Connection string de banco, chave de API, senha de serviço — se esses valores estão em texto puro nas Application Settings do App Service, qualquer pessoa com acesso de leitura ao recurso consegue ver o segredo. As Key Vault References resolvem isso: o app setting vira só um ponteiro pro Key Vault, e o valor real nunca fica exposto na configuração.
Neste guia rápido você vai configurar a Managed Identity do App Service, liberar a leitura do segredo no cofre e trocar um app setting em texto puro por uma referência resolvida automaticamente pela plataforma — tudo via Azure CLI.
Sumário
- Como funciona a referência
- Passo 1 — Habilitar a Managed Identity
- Passo 2 — Dar permissão de leitura no Key Vault
- Passo 3 — Trocar o valor pela referência
- Passo 4 — Validar a resolução
- Versão fixa vs. sempre a mais recente
- Troubleshooting comum
- Conclusão
- Referências oficiais
Como funciona a referência
Uma Key Vault Reference é uma sintaxe especial no valor do app setting — a chave continua normal, só o conteúdo muda:
@Microsoft.KeyVault(SecretUri=https://kv-meuapp.vault.azure.net/secrets/db-password/)Quando a aplicação inicia, o próprio runtime do App Service resolve essa referência usando a Managed Identity do recurso, busca o segredo no Key Vault e injeta o valor real como variável de ambiente — o código da aplicação nem sabe que existe um Key Vault por trás, só lê a variável normalmente.
Passo 1 — Habilitar a Managed Identity
Sem uma identidade, o App Service não tem como se autenticar no Key Vault. O caminho mais simples é a identidade gerenciada atribuída pelo sistema (system-assigned):
az webapp identity assign \
--name meuapp-prod \
--resource-group rg-appservice-lab \
--query principalId -o tsvGuarde o principalId retornado — ele identifica essa Managed Identity dentro do Azure AD, e é o que você vai usar pra conceder acesso no Key Vault no próximo passo.
Passo 2 — Dar permissão de leitura no Key Vault
O modelo de permissão do Key Vault depende de qual modo de autorização o cofre usa. Se for o modelo mais novo (RBAC), a role certa é Key Vault Secrets User — só leitura de segredo, nada de escrita:
# Modelo RBAC (recomendado)
principalId=$(az webapp identity show --name meuapp-prod --resource-group rg-appservice-lab --query principalId -o tsv)
az role assignment create \
--role "Key Vault Secrets User" \
--assignee "$principalId" \
--scope "$(az keyvault show --name kv-meuapp --query id -o tsv)"Se o cofre ainda usa o modelo legado de access policy, o equivalente é:
# Modelo Access Policy (legado)
az keyvault set-policy \
--name kv-meuapp \
--object-id "$principalId" \
--secret-permissions get listPasso 3 — Trocar o valor pela referência
Com a identidade autorizada, é só apontar o app setting pro segredo. O --settings aceita a sintaxe direto — não precisa de nenhum parâmetro especial:
az webapp config appsettings set \
--name meuapp-prod \
--resource-group rg-appservice-lab \
--settings DB_PASSWORD="@Microsoft.KeyVault(SecretUri=https://kv-meuapp.vault.azure.net/secrets/db-password/)"Em PowerShell, o mesmo resultado sai com um hashtable de app settings e Set-AzWebApp:
$appSettings = @{
"DB_PASSWORD" = "@Microsoft.KeyVault(SecretUri=https://kv-meuapp.vault.azure.net/secrets/db-password/)"
}
Set-AzWebApp -ResourceGroupName rg-appservice-lab -Name meuapp-prod -AppSettings $appSettingsPasso 4 — Validar a resolução
A CLI não devolve o valor resolvido por segurança, mas o portal mostra o status da resolução em Configuration → Application settings, na coluna “Source”: Resolved confirma que a identidade conseguiu ler o segredo. Pra checar por script, o mesmo status vem no endpoint do Kudu:
curl -s -u "\$meuapp-prod:" \
https://meuapp-prod.scm.azurewebsites.net/api/settings | grep -A2 DB_PASSWORDSe o status vier como Disabled ou Error, a aplicação não sobe corretamente — é sinal de identidade sem permissão ou URI errada, cobertos na tabela de troubleshooting mais abaixo.
Versão fixa vs. sempre a mais recente
A URI do segredo pode incluir ou omitir a versão. Isso muda o comportamento quando você rotaciona o segredo no Key Vault:
| Formato da URI | Comportamento |
|---|---|
.../secrets/db-password/ (sem versão) |
Sempre resolve pra versão mais recente — rotacionar o segredo no cofre já atualiza o app na próxima resolução, sem redeploy |
.../secrets/db-password/abc123.../ (com versão) |
Fixa naquela versão específica — rotacionar o segredo não afeta o app até você atualizar o app setting manualmente |
Pra a maioria dos casos, a versão omitida é a escolha certa: rotação de segredo vira uma operação só no Key Vault, sem tocar no App Service.
Troubleshooting comum
| Sintoma | Causa | Solução |
|---|---|---|
Status Disabled na Application Settings |
Managed Identity não habilitada ou sem permissão no cofre | Confirmar az webapp identity show e a role/policy no Key Vault |
Status Error mesmo com permissão certa |
Firewall do Key Vault bloqueando serviços do Azure | Habilitar “Allow trusted Microsoft services to bypass this firewall” nas Networking settings do cofre |
| App sobe mas a variável vem vazia | URI do segredo com nome errado ou versão inexistente | Conferir o nome exato do secret com az keyvault secret list --vault-name kv-meuapp |
| Referência funciona em produção mas não no slot | Identity só foi habilitada no slot de produção | Habilitar Managed Identity e a permissão também no slot (--slot em ambos os comandos) |
Conclusão
Com Key Vault References, o segredo sai do texto puro da configuração e passa a viver só no Key Vault — o App Service resolve tudo em tempo de execução, sem precisar de SDK nem código extra na aplicação. É um dos ajustes de segurança mais baratos de aplicar em qualquer App Service que ainda guarda senha ou connection string direto nas Application Settings.
Referências oficiais
- Usar referências do Key Vault no App Service (Microsoft Learn)
- az webapp identity — referência da CLI (Microsoft Learn)
- Azure RBAC no Key Vault (Microsoft Learn)
Interessado em saber mais sobre artigos relacionados ao Microsoft Azure CLIQUE AQUI
🚀 Vamos nos conectar?
Não perca nenhuma oportunidade! Cadastre-se nas minhas redes e no canal do YouTube para receber conteúdos de TI, Cloud, Azure, Kubernetes e DevOps em primeira mão.
Dica: No Facebook, todos os artigos do blog são publicados automaticamente. Vale a pena curtir!
💬 Dúvidas ou Problemas?
Com o intuito de ajudar a comunidade, caso você tenha dúvidas ou encontre problemas na execução dos comandos deste artigo, deixe um comentário abaixo. Responderei o mais breve possível!
Muito obrigado pela visita e até o próximo post!
Jefferson Castilho Especialista em Cloud & DevOps.Este guia técnico é exclusivo do Blog do Castilho. Explore mais conteúdos sobre Cloud e DevOps.