Condividi tramite

Usare @akv() per la sostituzione dei segreti di Azure Key Vault in Generatore API dati

Il generatore di API dati (DAB) consente di evitare di memorizzare segreti, come le stringhe di connessione del database, nel file di configurazione di runtime sostituendoli al momento del caricamento. Originariamente questa operazione è stata eseguita con la funzione per le @env() variabili di ambiente. A partire dalla versione 1.6, DAB aggiunge il supporto per Azure Key Vault tramite la @akv() funzione .

Che cosa @akv() fa

È possibile fare riferimento a un segreto archiviato in Azure Key Vault direttamente nel codice JSON di configurazione:

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

In fase di caricamento della configurazione, DAB risolve il segnaposto e lo sostituisce con il valore del segreto, simile a come funziona @env('VAR_NAME'). Se non è possibile recuperare il segreto, il caricamento della configurazione non riesce. Gli errori includono segreti mancanti o errori di autorizzazione.

Struttura di configurazione

Aggiungi la sezione azure-key-vault alla radice della configurazione:

{
  "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
    }
  }
}

Proprietà

Proprietà Obbligatorio TIPO Description
endpoint Sì se si usa Key Vault corda URL completo dell'endpoint del Key Vault
retry-policy NO oggetto Sovrascrive il comportamento di ripetizione dei tentativi durante la chiamata a Key Vault

Oggetto criteri di ripetizione dei tentativi

Campo Predefinito Note
mode exponential Valori consentiti: fixed o exponential
max-count 3 Deve essere maggiore di 0
delay-seconds 1 Deve essere maggiore di 0
max-delay-seconds 60 Deve essere maggiore di 0, limite massimo per il backoff esponenziale
network-timeout-seconds 60 Deve essere maggiore di 0

Modalità dei criteri di ripetizione dei tentativi

Mode Comportamento
fixed Attende un intervallo costante delay-seconds tra i tentativi fino a quando max-count
exponential Raddoppia il ritardo fino a raggiungere max-delay-seconds o max-count

Sviluppo locale: file .akv

Per lo sviluppo senza Azure Key Vault, usare un .akv file per simulare i segreti. Il formato è name=value per riga:

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

Annotazioni

Se si specifica un file locale .akv per lo sviluppo, le relative voci vengono utilizzate per soddisfare @akv(le interrogazioni "secret-name" senza effettuare una chiamata di rete ad Azure Key Vault.

Istruzioni:

  • Tieni .akv fuori dal controllo del codice sorgente
  • I nomi dei segreti devono corrispondere ai nomi usati in @akv('name')

Aggiunta delle impostazioni di configurazione di Azure Key Vault utilizzando l'interfaccia della riga di comando

È possibile configurare le impostazioni di Key Vault usando l'interfaccia della riga di comando:

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

Convalida:

  • Campi dei criteri dei tentativi di ripetizione senza un endpoint portano a un errore di validazione.
  • I parametri di ripetizione dei tentativi facoltativi devono essere numeri interi positivi

Uso @akv() nella configurazione

Sostituzione di base

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

Misto con @env()

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

Annotazioni

All'avvio, le sostituzioni @env() vengono eseguite prima delle sostituzioni @akv().

Parametri della stored procedure

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

Risoluzione dei problemi

Sintomo Steps
Segreto non trovato Verificare il nome, l'esistenza nel vault e le autorizzazioni di accesso
Valore di ripetizione non valido Usare un numero intero positivo o rimuovere per usare le impostazioni predefinite
L'aggiornamento della configurazione non riesce Controllare la presenza di errori di convalida nei log
@akv() non sostituito Verificare che l'endpoint, il nome del segreto e la risoluzione dei segreti siano abilitati
401/403 dal Key Vault Controllare l'assegnazione di identità e le autorizzazioni

Configurazione completa di esempio

{
  "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" ] }
      ]
    }
  }
}

File di esempio .akv :

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

Importante

Non eseguire il commit .akv di file contenenti segreti. |

Riferimento rapido

Elemento Riassunto
Sintassi @akv('secret-name')
Endpoint obbligatorio Yes
File di simulazione .akv con name=value linee
Combinazione con @env() Supportato.

Review

Usare @akv() per risolvere i segreti da Azure Key Vault. Configurare le politiche di riprova per l'affidabilità e usare i file .akv per simulare dei segreti in fase di sviluppo. In questo modo i valori sensibili non sono presenti nei file di configurazione, supportando flussi di lavoro coerenti per lo sviluppo e la produzione.

  • Last updated on