Partilhar via

Usar @akv() para substituição de segredos do Cofre de Chaves do Azure no construtor de API de Dados

O construtor de API de dados (DAB) permite manter segredos, como cadeias de conexão de banco de dados, fora do arquivo de configuração de tempo de execução, substituindo-os no momento do carregamento. Originalmente, isto era feito com a @env() função para variáveis de ambiente. A partir da versão 1.6, o DAB adiciona suporte para o Azure Key Vault por meio da @akv() função.

O que @akv() faz

Você pode fazer referência a um segredo armazenado no Cofre de Chaves do Azure diretamente na configuração JSON:

{
  "data-source": {
    "connection-string": "@akv('my-connection-secret')"
  }
}

No momento do carregamento da configuração, o DAB resolve o espaço reservado e substitui-o pelo valor do segredo, da mesma forma que @env('VAR_NAME') funciona. Se o segredo não puder ser recuperado, o carregamento da configuração falhará. Os erros incluem segredos ausentes ou falhas de autorização.

Estrutura de configuração

Adicione a azure-key-vault seção no nível raiz da sua configuração:

{
  "azure-key-vault": {
    "endpoint": "https://my-vault-name.vault.azure.net/",
    "retry-policy": {
      "mode": "exponential",
      "max-count": 5,
      "delay-seconds": 2,
      "max-delay-seconds": 30,
      "network-timeout-seconds": 45
    }
  }
}

Propriedades

Propriedade Obrigatório Tipo Description
endpoint Sim se estiver a utilizar o Cofre de Chaves cadeia (de caracteres) A URL completa do ponto de extremidade do Cofre de Chaves
retry-policy Não objecto Substitui o comportamento de repetição ao chamar o Azure Key Vault

Repetir objeto de política

Campo Default Observações
mode exponential Valores permitidos: fixed ou exponential
max-count 3 Deve ser maior que 0
delay-seconds 1 Deve ser maior que 0
max-delay-seconds 60 Deve ser maior que 0, teto para recuo exponencial
network-timeout-seconds 60 Deve ser maior que 0

Modelos de política de repetição

Mode Comportamento
fixed Aguarda um intervalo constante delay-seconds entre as tentativas até max-count
exponential Duplica o atraso até atingir max-delay-seconds ou max-count

Desenvolvimento local: arquivos .akv

Para desenvolvimento sem um Cofre de Chaves do Azure, use um .akv arquivo para simular segredos. O formato é name=value por linha:

my-connection-secret=Server=.;Database=AppDb;User Id=app;Password=local-dev;
api-key=dev-api-key-123

Observação

Se fornecer um arquivo local .akv para desenvolvimento, as suas entradas serão utilizadas para atender às pesquisas de @akv('nome secreto', sem fazer uma chamada de rede para o Cofre de Chaves do Azure.

Diretrizes:

  • Manter .akv fora do controle do código-fonte
  • Os nomes secretos devem corresponder aos nomes usados em @akv('name')

Adicionando configurações do Azure Key Vault com a CLI

Você pode definir as configurações do Cofre da Chave usando a CLI:

dab configure \
  --azure-key-vault.endpoint "https://my-vault.vault.azure.net/" \
  --azure-key-vault.retry-policy.mode exponential \
  --azure-key-vault.retry-policy.max-count 5 \
  --azure-key-vault.retry-policy.delay-seconds 2 \
  --azure-key-vault.retry-policy.max-delay-seconds 30 \
  --azure-key-vault.retry-policy.network-timeout-seconds 45 \
  --config dab-config.json

Validação:

  • Campos de política de repetição sem um ponto de extremidade causam falha de validação
  • Os parâmetros de repetição opcionais devem ser inteiros positivos

Usando @akv() na configuração

Substituição de base

{
  "data-source": {
    "database-type": "mssql",
    "connection-string": "@akv('primary-sql-connection')"
  }
}

Misturado com @env()

{
  "data-source": {
    "database-type": "@env('DB_TYPE')",
    "connection-string": "@akv('sql-connection')"
  },
  "runtime": {
    "rest": { "enabled": true }
  }
}

Observação

No arranque, as substituições @env() ocorrem antes das substituições @akv().

Parâmetros do procedimento armazenado

{
  "entities": {
    "RunJob": {
      "source": {
        "object": "dbo.RunJob",
        "type": "stored-procedure",
        "parameters": {
          "apiKey": "@akv('job-runner-apikey')"
        }
      },
      "permissions": [
        { "role": "anonymous", "actions": [ "execute" ] }
      ]
    }
  }
}

Solução de problemas

Sintoma Steps
Segredo não encontrado Verificar nome, existência no cofre e permissões de identidade
Valor de repetição inválido Use um inteiro positivo ou remova para usar os valores padrão
Falha na atualização da configuração Verifique se há erros de validação nos logs
@akv() não substituído Confirme o ponto de extremidade, o nome secreto e se a resolução secreta está ativada
401/403 do Key Vault Verificar atribuição de identidade e permissões

Exemplo completo de configuração

{
  "data-source": {
    "database-type": "mssql",
    "connection-string": "@akv('primary-sql-connection')"
  },
  "azure-key-vault": {
    "endpoint": "https://my-vault.vault.azure.net/",
    "retry-policy": {
      "mode": "exponential",
      "max-count": 5,
      "delay-seconds": 2,
      "max-delay-seconds": 30,
      "network-timeout-seconds": 45
    }
  },
  "runtime": {
    "rest": { "enabled": true }
  },
  "entities": {
    "Books": {
      "source": "dbo.Books",
      "permissions": [
        { "role": "anonymous", "actions": [ "read" ] }
      ]
    }
  }
}

Exemplo .akv de ficheiro:

primary-sql-connection=Server=localhost;Database=BooksDb;User Id=app;Password=password;

Importante

Não comprometa .akv ficheiros que contenham segredos. |

Referência rápida

Item Resumo
Sintaxe @akv('secret-name')
Ponto final necessário Yes
Arquivo de simulação .akv com name=value linhas
Misturar com @env() Supported.

Revisão

Use @akv() para resolver segredos do Cofre de Chaves do Azure. Configure políticas de repetição para confiabilidade e utilize arquivos .akv para simular segredos no desenvolvimento. Isso mantém os valores confidenciais fora dos arquivos de configuração e, ao mesmo tempo, oferece suporte a fluxos de trabalho consistentes de desenvolvimento e produção.

  • Last updated on