Cofre de Chaves do Azure para IA: objetos, SDK, rotação e cache
Centralize segredos, chaves e certificados, autentique sem credenciais armazenadas, recupere e versione segredos com o SDK do Python, faça rotação sem indisponibilidade e mantenha cache com atualização controlada.
Tempo de estudo sugerido: 125 minutos • Nível intermediário • Reescrita autoral completa com versão resumida de cada tópico, avaliação comentada e laboratório Python guiado
Por João Ricardo Dutra••Conteúdo autoral completo
1. Cenário e objetivos de aprendizagem
Um RAG cria embeddings com o , lê vetores do e grava documentos processados no . Desenvolvimento, homologação e produção usam credenciais diferentes. Manter strings de conexão e chaves de em arquivos de ambiente enviados ao repositório expõe os valores, enquanto alterar uma credencial comprometida por reimplantação dificulta a meta de quatro horas sem indisponibilidade.
Selecionar o objeto correto do para segredo, chave criptográfica ou certificado.
Autenticar com e autorizar pelo do com privilégio mínimo.
Recuperar valores e pelos clientes síncrono e assíncrono do do Python.
Usar versões, rotação, repetição e invalidação de para transições seguras.
Reduzir chamadas ao cofre sem prolongar a vida de uma credencial comprometida.
Resumo rápido
O desenho substitui credenciais no código por um repositório central auditável e trata rotação, transição e atualização do como partes da arquitetura.
2. Recursos, camadas e interfaces do
O do armazena segredos, chaves e certificados e criptografa os . O autentica, e o do autoriza operações. Aplicativos podem usar , CLI do , portal ou SDKs compatíveis para Python, .NET, Java, JavaScript e Go.
Escolha de proteção
Opção
Proteção de chaves
Uso indicado
Standard
e curva elíptica protegidas por software; validação 140-2 Nível 1
Segredos e cargas com chaves de software
Premium
Acrescenta chaves em ; novas versões usam a plataforma 140-3 Nível 3
Políticas ou cargas reguladas que exigem material em
Gerenciado
Recurso separado que guarda somente chaves protegidas por
Gerenciamento dedicado e de alta escala; não armazena segredos nem certificados
O tipo de objeto define operações e ciclo de vida; a camada define a proteção do material criptográfico.
Resumo rápido
Cofres armazenam três tipos de objeto; Standard e Premium diferem sobretudo na proteção das chaves, enquanto Gerenciado é um serviço separado e exclusivo para chaves.
3. Segredos: valores opacos com
Um segredo é uma cadeia opaca de até 25 KB para chaves de , senhas, , strings de conexão, chaves SSH privadas ou credenciais compostas pequenas. O serviço não interpreta o valor. content_type, propriedades da versão e tags documentam formato, responsável, ambiente e política de rotação.
Não use o cofre como banco de configuração ou conteúdo. , nomes de serviço e feature pertencem à ; cargas grandes pertencem ao do com criptografia adequada. Como quem lista pode ver tags, elas nunca devem conter credenciais.
Resumo rápido
Segredos são cadeias sensíveis pequenas; descrevem o objeto, mas configurações comuns e conteúdo volumoso ficam em outros armazenamentos.
4. Chaves: criptografia sem exportar o material
Chaves executam criptografia, descriptografia, assinatura, verificação e encapsulamento. Operações no servidor mantêm a chave privada dentro do limite do serviço. por software admite 2.048, 3.072 e 4.096 bits; EC admite P-256, P-384, P-521 e secp256k1/P-256K. Premium acrescenta variantes . Chaves simétricas oct- continuam em e carregam as limitações desse estágio.
Escolha uma chave, e não um segredo, quando um serviço do precisar de chave gerenciada pelo cliente, quando o aplicativo precisar assinar ou encapsular remotamente ou quando a política exigir material não exportável.
Resumo rápido
Uma chave oferece operações criptográficas controladas sem expor seu material privado protegido.
5. Certificados e os objetos de chave e segredo vinculados
Um certificado do gerencia e a chave privada correspondente, incluindo emissão, renovação, revogação e integração com autoridade certificadora para ou mútuo. Criar ou importar um certificado também gera uma chave e uma representação em segredo; por isso a leitura da chave privada exige uma função cuidadosamente escolhida.
Use o objeto certificado para credenciais com ciclo de vida, em vez de guardar um pacote como segredo genérico. Assim permanecem disponíveis política, emissor, renovação e versões.
Resumo rápido
Certificados adicionam gerenciamento e criam objetos relacionados; o acesso à chave privada deve ser restrito.
6. Limites do cofre, nomes e tags
Um limite prático é um cofre por aplicativo, região e ambiente. Separar desenvolvimento, pré-produção e produção reduz o raio de impacto e simplifica funções. Uma identidade comprometida em desenvolvimento não deve descobrir credenciais de produção.
O nome do cofre é globalmente exclusivo, tem 3–24 caracteres, começa com letra, termina com letra ou dígito, aceita alfanuméricos e hífens e proíbe hífens consecutivos.
Use nomes descritivos como cosmosdb-connection-string e openai--key.
Cada segredo admite até 15 tags; os limites atuais são 512 caracteres no nome e 256 no valor.
Ambiente, equipe, aplicativo, política de rotação e classificação são tags úteis; o valor secreto nunca é.
Resumo rápido
Cofres separados criam limites de segurança; nomes consistentes e tags não sensíveis tornam o inventário operável.
7. do , plano de controle e plano de dados
O plano de controle cria e configura o recurso pelo . O plano de dados lê e altera segredos, chaves e certificados no do cofre. Contributor gerencia o recurso, mas não lê valores no plano de dados.
Funções internas representativas
Função
Uso adequado
Secrets User
Ler valores de segredos, inclusive a parte secreta de certificado com chave privada; indicada ao runtime
Secrets Officer
Gerenciar todo o ciclo dos segredos, exceto permissões; indicada a operadores ou automação controlada
Reader
Ler do cofre e dos objetos, sem valores sensíveis nem material de chave
Administrator
Executar todas as operações do plano de dados; não gerencia o recurso nem atribuições
Contributor
Gerenciar apenas o recurso no plano de controle; sem acesso aos dados
Prefira do às políticas de acesso herdadas, atribua no escopo do cofre, use para administração just-in-time e evite concessões amplas na assinatura. Nas versões atuais da , é o modelo padrão de cofres recém-criados.
Resumo rápido
A identidade autentica; a função no plano de dados autoriza as operações exatas, e Contributor no plano de controle não lê segredos.
8. e cadeia atual de credenciais
Uma permite que ,,, e outros recursos autentiquem sem segredo de cliente. Conceda Secrets User quando o aplicativo apenas lê em runtime.
DefaultAzureCredential ajuda o mesmo código no ambiente local e no . A cadeia atual do Python pode tentar Environment, Workload Identity, , Shared ,, CLI do ,, Developer CLI, navegador interativo opcional e broker. A cadeia muda entre versões. Em produção, a Microsoft recomenda compreender o requisito e considerar ManagedIdentityCredential diretamente para reduzir ambiguidade e sobrecarga.
Identidade determina quem chama; do determina o que essa identidade pode fazer no cofre.
Resumo rápido
elimina credenciais armazenadas; DefaultAzureCredential conecta ambientes, mas a cadeia de produção deve ser explícita e observável.
9. Exclusão reversível, proteção contra limpeza e recuperação
A exclusão reversível vem habilitada por padrão e não pode ser desativada depois. Cofres e objetos excluídos permanecem recuperáveis pelo intervalo definido na criação: de 7 a 90 dias, com 90 como padrão. O intervalo não pode ser alterado depois.
A proteção contra limpeza é opcional, mas fortemente recomendada em produção. Quando habilitada, nem um principal privilegiado pode eliminar permanentemente o objeto antes do fim da retenção. Recuperar um cofre não restaura atribuições nem assinaturas da ; o runbook precisa recriá-las.
Resumo rápido
Exclusão reversível cria a janela, proteção contra limpeza a impõe, e a recuperação ainda exige reconstruir funções e assinaturas.
10. Instalar o do Python e criar SecretClient
-keyvault-secrets fornece SecretClient; -identity fornece credenciais. A segue ://<vault-name>.vault..net/. Crie credencial e cliente uma vez e reutilize-os para aproveitar de e conexões .
pip install azure-identity azure-keyvault-secrets
az keyvault show --name <vault-name> --query properties.vaultUri
from azure.identity import DefaultAzureCredential
from azure.keyvault.secrets import SecretClient
credential = DefaultAzureCredential()
client = SecretClient(
vault_url="https://<vault-name>.vault.azure.net/",
credential=credential,
)
client.set_secret(
"openai-api-key",
"<secret-value>",
content_type="text/plain",
tags={"environment": "production", "owner": "ai-platform"},
)
Resumo rápido
Instale identidade e segredos, crie um SecretClient reutilizável com e nunca registre o valor armazenado.
11. Recuperar valores, e inventário com segurança
get_secret(nome) sem versão retorna a versão habilitada mais recente. KeyVaultSecret contém value e propriedades como versão, criação, expiração, estado, tipo e tags. Registre apenas nome e versão.
list_properties_of_secrets() enumera sem buscar valores. Ele atende inventário e validação no startup, permitindo conferir todos os nomes antes de aceitar tráfego.
from azure.core.exceptions import (
HttpResponseError, ResourceNotFoundError, ServiceRequestError
)
def read_secret(client: SecretClient, name: str) -> str:
try:
secret = client.get_secret(name) # latest enabled version
print(f"Loaded {name}, version={secret.properties.version}")
return secret.value
except ResourceNotFoundError as exc:
raise RuntimeError(f"Missing secret: {name}") from exc
except HttpResponseError as exc:
raise RuntimeError(f"Key Vault rejected {name}: {exc.status_code}") from exc
except ServiceRequestError as exc:
raise RuntimeError("Network path to Key Vault failed") from exc
for props in client.list_properties_of_secrets():
print(props.name, props.enabled, props.content_type, props.tags)
Resumo rápido
get_secret lê um valor; a listagem de propriedades descobre e valida objetos sem revelar o conteúdo.
12. Exceções, acesso assíncrono e ciclo do cliente
ResourceNotFoundError normalmente indica nome ou cofre incorreto. HttpResponseError cobre autenticação, autorização, limitação e outras respostas do serviço. ServiceRequestError aponta transporte, , ou conectividade. Classifique antes de repetir para não transformar erro permanente em tempestade de tentativas.
O cliente aio não bloqueia o event loop de FastAPI ou aiohttp. Cliente e credencial são gerenciadores de contexto assíncronos. Em serviço web, crie-os no startup, reutilize entre requisições e feche no shutdown.
from azure.identity.aio import DefaultAzureCredential
from azure.keyvault.secrets.aio import SecretClient
async def load_runtime_secret() -> str:
async with DefaultAzureCredential() as credential:
async with SecretClient(
vault_url="https://<vault-name>.vault.azure.net/",
credential=credential,
) as client:
secret = await client.get_secret("openai-api-key")
return secret.value
# In a web service, create and reuse one client during app startup,
# then close the client and credential during app shutdown.
Resumo rápido
Diferencie ausência, rejeição e falha de transporte; aplicativos assíncronos devem reutilizar um cliente e encerrá-lo corretamente.
13. Versões, expiração, auditoria e reversão
Cada set_secret com o mesmo nome cria um identificador de versão imutável, sem sobrescrever o anterior. A leitura sem versão retorna a habilitada mais recente; a leitura versionada recupera o valor histórico exato. Listar propriedades mostra criação, expiração e estado para auditoria e .
expires_on é sinal de ciclo de vida, não bloqueio rígido: um segredo expirado ainda pode ser recuperado. Combine expiração com monitoramento e automação e só desabilite a versão antiga depois que todas as instâncias migrarem.
from datetime import datetime, timedelta, timezone
created = client.set_secret(
"cosmosdb-connection-string",
"<new-value>",
expires_on=datetime.now(timezone.utc) + timedelta(days=90),
tags={"rotation-policy": "90-days", "service": "cosmos-db"},
)
latest = client.get_secret("cosmosdb-connection-string")
exact = client.get_secret("cosmosdb-connection-string", created.properties.version)
for version in client.list_properties_of_secret_versions("cosmosdb-connection-string"):
print(version.version, version.created_on, version.expires_on, version.enabled)
# Disable the previous version only after every instance has moved.
client.update_secret_properties(
"cosmosdb-connection-string", "<old-version>", enabled=False
)
Resumo rápido
Versões permitem coexistência; expiração aciona operações, e desabilitar encerra o uso somente após implantação ou janela de reversão.
14. Rotação manual, pela e com duas credenciais
Estratégias
Estratégia
Fluxo
Uso indicado
Manual ou CI/CD
Criar no serviço-alvo, publicar nova versão e sinalizar ou reiniciar o aplicativo
Credenciais externas alteradas raramente
Orientada a eventos
SecretNearExpiry ocorre 30 dias antes; Function ou Logic App cria no alvo e grava nova versão
Credenciais repetíveis com de rotação
Duas credenciais
Criar/regenerar secundária, publicar, aguardar instâncias e regenerar a primária antiga
do ou com duas chaves ativas
Crie a credencial no serviço-alvo.
Grave-a como nova versão no cofre.
Invalide ou notifique instâncias.
Confirme a adoção.
Desabilite ou regenere a antiga e registre evidências.
Microsoft.KeyVault.SecretNewVersionCreated, SecretNearExpiry e SecretExpired são eventos atuais da . Expirar ou notificar não altera sozinho a credencial externa; o manipulador coordena serviço-alvo e cofre.
Resumo rápido
A capacidade do serviço-alvo define a estratégia; criar uma versão no cofre é apenas uma etapa da rotação completa.
15. Transição sem indisponibilidade e atualização após falha
Durante a rotação, instâncias podem manter valores diferentes no . O aplicativo tenta o serviço com a credencial atual, interpreta rejeição de autenticação como possível rotação, busca a versão habilitada mais recente e repete uma única vez. Isso evita loops e restringe a leitura extra ao momento da transição.
from azure.core.exceptions import HttpResponseError
def call_with_rotation_refresh(client, cache, name, downstream_call):
value = cache.get(name)
try:
return downstream_call(value)
except AuthenticationError:
# One refresh and one retry: do not create an infinite loop.
fresh = client.get_secret(name).value
cache.put(name, fresh)
return downstream_call(fresh)
é o limite de segurança; eventos e atualização por falha encurtam a transição sem consultar o cofre a cada requisição.
Resumo rápido
Mantenha versões válidas durante a implantação, atualize uma vez em falha, observe a convergência e revogue a antiga no final.
16. por tempo, escopo e orçamento de atualização
Uma chamada remota pode levar dezenas de milissegundos; memória local, microssegundos. Ler o cofre em toda requisição de IA aumenta latência e pode atingir limites. Um baseado em relógio monotônico evita que ajustes do relógio do sistema corrompam a idade.
import time
class SecretCache:
def __init__(self, client: SecretClient, ttl_seconds: int = 900):
self.client = client
self.ttl = ttl_seconds
self.values: dict[str, tuple[str, float]] = {}
def get(self, name: str) -> str:
value = self.values.get(name)
now = time.monotonic()
if value and now - value[1] < self.ttl:
return value[0]
secret = self.client.get_secret(name)
self.values[name] = (secret.value, now)
return secret.value
def invalidate(self, name: str) -> None:
self.values.pop(name, None)
Escopo
Escopo
Vantagem
Compromisso
Por processo
Simples e rápido; ponto inicial recomendado
Chamadas crescem com réplicas e cada processo tem sua janela
distribuído, como
Uma atualização serve muitas instâncias
Acrescenta operação e outro local protegido para o segredo
Pré-carregamento no startup
Sem leitura no caminho da requisição e valida nomes cedo
Precisa de atualização periódica ou por evento
Defina pelo atraso tolerável: 5–15 minutos mais para rotação frequente, 30–60 minutos para mudanças mensais ou trimestrais e preload com atualização de horas para valores quase estáticos. Em comprometimento, invalide ou reinicie imediatamente.
Resumo rápido
Comece com em memória, derive da tolerância a desatualização e associe um mecanismo explícito de atualização.
17. Invalidação, limites, e laboratório guiado
Assine Microsoft.KeyVault.SecretNewVersionCreated e encaminhe por , ou . Valide origem e tipo e remova somente o segredo citado. Preserve como fallback.
Os limites atuais por cofre, região e 10 segundos permitem 4.000 outras transações; CREATE secret, IMPORT certificate e IMPORT key compartilham 300 gravações. A assinatura agrega cinco vezes o limite por cofre. Em 429, aplique exponencial com jitter. Respostas persistentes indicam ausência de , curto ou manada na implantação; escalone o startup e reutilize clientes.
Laboratório Flask guiado
Crie ou selecione um cofre com , exclusão reversível e proteção contra limpeza; use Secrets Officer para o desenvolvedor e Secrets User para a aplicação.
Baixe ou clone um projeto inicial Flask, abra no , crie ambiente Python 3.12+, instale -identity, -keyvault-secrets e Flask e entre com a CLI do atualizada usando az login.
Complete o aplicativo inicial com SecretClient, armazene segredos com tipo e tags e imprima somente nomes, versões e .
Execute as operações: liste propriedades, leia um valor, crie segunda versão e confirme a leitura sem versão.
Adicione de 15 minutos, faça várias leituras, rotacione, invalide e confirme o novo valor.
Exercite as três exceções e observe repetição de 429 sem registrar segredos.
Remova recursos e funções do laboratório.
Resumo rápido
Eventos aceleram atualização, cobre notificações perdidas, limites recompensam , e o laboratório valida todo o ciclo.
18. Revisão da avaliação, checklist e referências
Decisões da avaliação
Questão
Melhor resposta
Motivo
Runtime apenas lê valores
Secrets User
Leitura sem administração do ciclo
Mesmo código usa CLI local e identidade em produção
DefaultAzureCredential
A cadeia conecta ambientes
get_secret(nome) sem versão
Versão habilitada mais recente
A sem versão acompanha o valor atual
Serviço aceita duas chaves
Rotação com duas credenciais
Sempre existe uma credencial válida
500 requisições/s e rotação a cada 90 dias
em memória com de uma hora
Remove leitura por requisição e limita desatualização
Checklist final
Separe cofre por aplicativo, região e ambiente.
Escolha o objeto pelas operações necessárias.
Use e de menor privilégio.
Habilite proteção contra limpeza e documente a recuperação.
Reutilize SecretClient e nunca registre valores.
Trate serviço-alvo, versão, e revogação como um fluxo.
Use , e uma atualização após falha.
Monitore acesso, expiração, 429, conclusão e desabilitação.
