Sdílet prostřednictvím

Použití @akv() pro nahrazování tajných kódů služby Azure Key Vault v Tvůrci rozhraní DATA API

Datový API builder (DAB) umožňuje uchovávat tajemství, jako jsou připojovací řetězce k databázi, mimo konfigurační soubor běhového prostředí tím, že je při načítání nahrazuje. Původně to bylo provedeno pomocí @env() funkce pro proměnné prostředí. Počínaje verzí 1.6 přidává DAB podporu služby Azure Key Vault prostřednictvím funkce @akv().

Co @akv() dělá

Na tajný klíč uložený ve službě Azure Key Vault můžete odkazovat přímo v konfiguračním kódu JSON:

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

Při načítání konfigurace DAB vyřeší zástupný symbol a nahradí jej hodnotou z tajného klíče, podobně jako funguje @env('VAR_NAME'). Pokud se tajný klíč nedá načíst, načtení konfigurace se nezdaří. Chyby zahrnují chybějící tajné kódy nebo chyby autorizace.

Struktura konfigurace

Přidejte část azure-key-vault na kořenovou úroveň vaší konfigurace:

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

Vlastnosti

Vlastnictví Povinné Typ Description
endpoint Ano , pokud používáte Key Vault řetězec Úplná adresa URL koncového bodu služby Key Vault
retry-policy Ne objekt Přepíše chování opakování při volání služby Key Vault.

Objekt zásad opakování

Obor Výchozí Poznámky
mode exponential Povolené hodnoty: fixed nebo exponential
max-count 3 Musí být větší než 0.
delay-seconds 1 Musí být větší než 0.
max-delay-seconds 60 Musí být větší než 0, horní hranice pro exponenciální zálohování
network-timeout-seconds 60 Musí být větší než 0.

Režimy politiky opakování

Mode Chování
fixed Čeká konstantu delay-seconds mezi pokusy, dokud max-count
exponential Zdvojnásobí zpoždění do dosažení max-delay-seconds nebo max-count

Místní vývoj: Soubory .akv

K vývoji bez služby Azure Key Vault použijte .akv soubor k simulaci tajných kódů. Formát je name=value na každý řádek:

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

Poznámka:

Pokud zadáte místní .akv soubor pro vývoj, použijí se jeho položky k uspokojení @akv(vyhledávání "secret-name", aniž by bylo nutné volat síť do služby Azure Key Vault.

Pokyny:

  • Udržujte .akv mimo správu zdrojového kódu
  • Názvy tajných kódů se musí shodovat s názvy použitými v @akv('name')

Přidání nastavení služby Azure Key Vault pomocí rozhraní příkazového řádku

Nastavení služby Key Vault můžete nakonfigurovat pomocí rozhraní příkazového řádku:

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

Validace:

  • Pole zásad opakování bez koncového bodu způsobují chybu ověření
  • Volitelné parametry opakování musí být kladné celé číslo.

Použití @akv() v konfiguraci

Základní náhrada

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

Smíšené s @env()

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

Poznámka:

Při spuštění dochází k @env() náhradám před @akv() náhradami.

Parametry uložené procedury

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

Řešení problémů

Příznaky Postup
Tajný kód nebyl nalezen. Ověřte název, existenci v trezoru a oprávnění pro identity
Neplatná hodnota opakování Použijte kladné celé číslo nebo odstraňte pro použití výchozích hodnot.
Selhání aktualizace konfigurace Zkontrolujte protokoly kvůli chybám ověřování
@akv() nenahrazuje se Potvrďte koncový bod, název tajemství a že je povoleno rozlišení tajemství
401/403 ze služby Key Vault Kontrola přiřazení identit a oprávnění

Úplná ukázková konfigurace

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

Příklad .akv souboru:

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

Důležité

Neposílejte .akv soubory obsahující citlivé informace. |

Stručná referenční dokumentace

Položka Shrnutí
Syntaxe @akv('secret-name')
Vyžaduje se koncový bod. Ano
Soubor simulace .akvs čárami name=value
Míchání s @env() Supported.

Review

Slouží @akv() k vyřešení tajemství ze služby Azure Key Vault. Nakonfigurujte zásady opakování pro spolehlivost a pomocí .akv souborů simulujte tajné kódy při vývoji. Díky tomu jsou citlivé hodnoty mimo konfigurační soubory a zároveň podporují konzistentní vývojové a produkční pracovní postupy.

  • Last updated on