Klientská knihovna Azure Key Vault Secret pro JavaScript – verze 4.8.0

  • Článek

Azure Key Vault je služba, která umožňuje šifrovat ověřovací klíče, klíče účtu úložiště, šifrovací klíče dat, soubory .pfx a hesla pomocí zabezpečených klíčů. Pokud se chcete o Azure Key Vault dozvědět více, můžete si projít téma Co je Azure Key Vault?

Správa tajných kódů Azure Key Vault umožňuje bezpečně ukládat tokeny, hesla, certifikáty, klíče rozhraní API a další tajné kódy a přísně řídit přístup k nim.

Pomocí klientské knihovny pro tajné kódy Azure Key Vault ve vaší Node.js aplikaci:

  • Získání, nastavení a odstranění tajných kódů
  • Aktualizace tajného kódu a jeho atributů
  • Zálohujte a obnovte tajný klíč.
  • Získání, vymazání nebo obnovení odstraněného tajného kódu
  • Získejte všechny verze tajného kódu.
  • Získejte všechny tajné kódy.
  • Získejte všechny odstraněné tajné kódy.

Poznámka: Tento balíček nelze použít v prohlížeči kvůli omezením služby Azure Key Vault. Pokyny najdete v tomto dokumentu.

Klíčové odkazy:

Začínáme

Aktuálně podporovaná prostředí

Požadavky

Instalace balíčku

Nainstalujte klientskou knihovnu Azure Key Vault Secret pomocí npm:

npm install @azure/keyvault-secrets

Instalace knihovny identit

Key Vault klienti se ověřují pomocí knihovny identit Azure. Nainstalujte ho také pomocí npm.

npm install @azure/identity

Konfigurace TypeScriptu

Uživatelé TypeScriptu musí mít nainstalované definice typů uzlů:

npm install @types/node

Musíte také povolit compilerOptions.allowSyntheticDefaultImports v tsconfig.json. Všimněte si, že pokud jste povolili compilerOptions.esModuleInterop, allowSyntheticDefaultImports je ve výchozím nastavení povolená. Další informace najdete v příručce k možnostem kompilátoru TypeScriptu .

Klíčové koncepty

  • Klient tajných kódů je primárním rozhraním pro interakci s metodami rozhraní API souvisejícími s tajnými kódy v rozhraní API Azure Key Vault z aplikace JavaScriptu. Po inicializaci poskytuje základní sadu metod, které lze použít k vytváření, čtení, aktualizaci a odstraňování tajných kódů.
  • Verze tajného kódu je verze tajného kódu v Key Vault. Pokaždé, když uživatel přiřadí hodnotu jedinečnému názvu tajného kódu, vytvoří se nová verze tohoto tajného klíče. Načtení tajného kódu podle názvu vždy vrátí nejnovější přiřazenou hodnotu, pokud není dotazu poskytnuta konkrétní verze.
  • Obnovitelné odstranění umožňuje službě Key Vault podporovat odstranění a vymazání ve dvou samostatných krocích, takže odstraněné tajné kódy se okamžitě neztratí. K tomu dochází pouze v případě, že má Key Vault povolené obnovitelné odstranění.
  • Zálohu tajného kódu je možné vygenerovat z libovolného vytvořeného tajného kódu. Tyto zálohy přicházejí jako binární data a dají se použít pouze k opětovnému vygenerování dříve odstraněného tajného kódu.

Ověřování pomocí Azure Active Directory

Služba Key Vault se při ověřování požadavků na rozhraní API spoléhá na Azure Active Directory. Balíček @azure/identity poskytuje různé typy přihlašovacích údajů, které k tomu může vaše aplikace použít. Soubor README pro @azure/identity obsahuje další podrobnosti a ukázky, které vám pomůžou začít.

Abyste mohli pracovat se službou Azure Key Vault, budete muset vytvořit instanci SecretClient třídy, adresu URL trezoru a objekt přihlašovacích údajů. Příklady uvedené v tomto dokumentu používají objekt přihlašovacích údajů s názvem DefaultAzureCredential, který je vhodný pro většinu scénářů, včetně místních vývojových a produkčních prostředí. Kromě toho doporučujeme použít spravovanou identitu pro ověřování v produkčních prostředích.

Další informace o různých způsobech ověřování a jejich odpovídajících typech přihlašovacích údajů najdete v dokumentaci k Identitě Azure.

Tady je stručný příklad. Nejprve import DefaultAzureCredential a SecretClient:

const { DefaultAzureCredential } = require("@azure/identity");
const { SecretClient } = require("@azure/keyvault-secrets");

Po importu se můžeme dále připojit ke službě Key Vault:

const { DefaultAzureCredential } = require("@azure/identity");
const { SecretClient } = require("@azure/keyvault-secrets");

const credential = new DefaultAzureCredential();

// Build the URL to reach your key vault
const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

// Lastly, create our secrets client and connect to the service
const client = new SecretClient(url, credential);

Určení verze rozhraní API služby Azure Key Vault

Ve výchozím nastavení tento balíček používá nejnovější verzi služby Azure Key Vault, která je 7.1. Jediná další podporovaná verze je 7.0. Verzi používané služby můžete změnit nastavením možnosti serviceVersion v konstruktoru klienta, jak je znázorněno níže:

const { DefaultAzureCredential } = require("@azure/identity");
const { SecretClient } = require("@azure/keyvault-secrets");

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

// Change the Azure Key Vault service API version being used via the `serviceVersion` option
const client = new SecretClient(url, credential, {
  serviceVersion: "7.0",
});

Příklady

Následující části obsahují fragmenty kódu, které pokrývají některé běžné úlohy s využitím Tajných kódů Azure Key Vault. Scénáře, které jsou zde popsané, se skládají z těchto:

Vytvoření a nastavení tajného klíče

setSecret přiřadí zadanou hodnotu zadanému názvu tajného klíče. Pokud tajný kód se stejným názvem již existuje, vytvoří se nová verze tajného klíče.

const { DefaultAzureCredential } = require("@azure/identity");
const { SecretClient } = require("@azure/keyvault-secrets");

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

async function main() {
  const result = await client.setSecret(secretName, "MySecretValue");
  console.log("result: ", result);
}

main();

Získání tajného kódu

Nejjednodušší způsob, jak číst tajné kódy z trezoru, je získat tajný kód podle názvu. Tím se načte nejnovější verze tajného kódu. Volitelně můžete získat jinou verzi klíče, pokud ji zadáte jako součást volitelných parametrů.

const { DefaultAzureCredential } = require("@azure/identity");
const { SecretClient } = require("@azure/keyvault-secrets");

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

async function main() {
  const latestSecret = await client.getSecret(secretName);
  console.log(`Latest version of the secret ${secretName}: `, latestSecret);
  const specificSecret = await client.getSecret(secretName, { version: latestSecret.properties.version! });
  console.log(`The secret ${secretName} at the version ${latestSecret.properties.version!}: `, specificSecret);
}

main();

Vytváření a aktualizace tajných kódů pomocí atributů

Tajný kód může obsahovat více informací než jeho název a jeho hodnota. Můžou také obsahovat následující atributy:

  • tags: Libovolná sada hodnot klíč-hodnota, kterou je možné použít k vyhledávání a filtrování tajných kódů.
  • contentType: Jakýkoli řetězec, který lze použít k tomu, aby příjemci tajného kódu pomohl pochopit, jak používat hodnotu tajného klíče.
  • enabled: Logická hodnota, která určuje, jestli je možné hodnotu tajného klíče přečíst, nebo ne.
  • notBefore: Zadané datum, po kterém je možné načíst hodnotu tajného kódu.
  • expiresOn: Zadané datum, po kterém nelze načíst hodnotu tajného kódu.

Objekt s těmito atributy je možné odeslat jako třetí parametr setSecret, hned za názvem a hodnotou tajného klíče, a to následujícím způsobem:

const { DefaultAzureCredential } = require("@azure/identity");
const { SecretClient } = require("@azure/keyvault-secrets");

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

async function main() {
  const result = await client.setSecret(secretName, "MySecretValue", {
    enabled: false,
  });
}

main();

Tím se vytvoří nová verze stejného tajného kódu, která bude mít nejnovější poskytnuté atributy.

Atributy lze také aktualizovat na existující verzi tajného kódu pomocí updateSecretPropertiespříkazu , a to následujícím způsobem:

const { DefaultAzureCredential } = require("@azure/identity");
const { SecretClient } = require("@azure/keyvault-secrets");

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

async function main() {
  const result = await client.getSecret(secretName);
  await client.updateSecretProperties(secretName, result.properties.version, { enabled: false });
}

main();

Odstranění tajného kódu

Metoda beginDeleteSecret spustí odstranění tajného kódu. Tento proces bude probíhat na pozadí, jakmile budou k dispozici potřebné prostředky.

const { DefaultAzureCredential } = require("@azure/identity");
const { SecretClient } = require("@azure/keyvault-secrets");

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

async function main() {
  await client.beginDeleteSecret(secretName);
}

main();

Pokud je pro Key Vault povolené obnovitelné odstranění, označí tato operace tajný klíč pouze jako odstraněný tajný klíč. Odstraněný tajný klíč nejde aktualizovat. Dají se jenom číst, obnovit nebo vymazat.

const { DefaultAzureCredential } = require("@azure/identity");
const { SecretClient } = require("@azure/keyvault-secrets");

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

async function main() {
  const poller = await client.beginDeleteSecret(secretName);

  // You can use the deleted secret immediately:
  const deletedSecret = poller.getResult();

  // The secret is being deleted. Only wait for it if you want to restore it or purge it.
  await poller.pollUntilDone();

  // You can also get the deleted secret this way:
  await client.getDeletedSecret(secretName);

  // Deleted secrets can also be recovered or purged.

  // recoverDeletedSecret returns a poller, just like beginDeleteSecret.
  const recoverPoller = await client.beginRecoverDeletedSecret(secretName);
  await recoverPoller.pollUntilDone();

  // And then, to purge the deleted secret:
  await client.purgeDeletedSecret(secretName);
}

main();

Vzhledem k tomu, že úplné odstranění tajných kódů nějakou dobu trvá, beginDeleteSecret vrátí pollerový objekt, který sleduje základní dlouhotrvající operaci podle našich pokynů: https://azure.github.io/azure-sdk/typescript_design.html#ts-lro

Přijatý poller vám umožní získat odstraněný tajný kód voláním na poller.getResult(). Můžete také počkat, až se odstranění dokončí, a to buď spuštěním jednotlivých volání služby, dokud se tajný klíč nesmažou, nebo čekáním na dokončení procesu:

const { DefaultAzureCredential } = require("@azure/identity");
const { SecretClient } = require("@azure/keyvault-secrets");

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

async function main() {
  const poller = await client.beginDeleteSecret(secretName);

  // You can use the deleted secret immediately:
  let deletedSecret = poller.getResult();

  // Or you can wait until the secret finishes being deleted:
  deletedSecret = await poller.pollUntilDone();
  console.log(deletedSecret);
}

main();

Dalším způsobem, jak počkat na úplné odstranění tajného kódu, je provést jednotlivá volání, a to následujícím způsobem:

const { DefaultAzureCredential } = require("@azure/identity");
const { SecretClient } = require("@azure/keyvault-secrets");
const { delay } = require("@azure/core-util");

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

async function main() {
  const poller = await client.beginDeleteSecret(secretName);

  while (!poller.isDone()) {
    await poller.poll();
    await delay(5000);
  }

  console.log(`The secret ${secretName} is fully deleted`);
}

main();

Iterace seznamů tajných kódů

Pomocí SecretClient můžete načíst a iterovat všemi tajnými kódy v Key Vault, stejně jako všemi odstraněnými tajnými klíči a verzemi konkrétního tajného kódu. K dispozici jsou následující metody rozhraní API:

  • listPropertiesOfSecrets zobrazí seznam všech neodstraněných tajných kódů podle jejich názvů, pouze v jejich nejnovějších verzích.
  • listDeletedSecrets zobrazí seznam všech odstraněných tajných kódů podle jejich názvů, pouze v jejich nejnovějších verzích.
  • listPropertiesOfSecretVersions zobrazí seznam všech verzí tajného kódu na základě názvu tajného kódu.

Které lze použít takto:

const { DefaultAzureCredential } = require("@azure/identity");
const { SecretClient } = require("@azure/keyvault-secrets");

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

async function main() {
  for await (let secretProperties of client.listPropertiesOfSecrets()) {
    console.log("Secret properties: ", secretProperties);
  }
  for await (let deletedSecret of client.listDeletedSecrets()) {
    console.log("Deleted secret: ", deletedSecret);
  }
  for await (let versionProperties of client.listPropertiesOfSecretVersions(secretName)) {
    console.log("Version properties: ", versionProperties);
  }
}

main();

Všechny tyto metody vrátí všechny dostupné výsledky najednou. Pokud je chcete načíst po stránkách, přidejte .byPage() hned po vyvolání metody rozhraní API, kterou chcete použít, následujícím způsobem:

const { DefaultAzureCredential } = require("@azure/identity");
const { SecretClient } = require("@azure/keyvault-secrets");

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

async function main() {
  for await (let page of client.listPropertiesOfSecrets().byPage()) {
    for (let secretProperties of page) {
      console.log("Secret properties: ", secretProperties);
    }
  }
  for await (let page of client.listDeletedSecrets().byPage()) {
    for (let deletedSecret of page) {
      console.log("Deleted secret: ", deletedSecret);
    }
  }
  for await (let page of client.listPropertiesOfSecretVersions(secretName).byPage()) {
    for (let versionProperties of page) {
      console.log("Version properties: ", versionProperties);
    }
  }
}

main();

Poradce při potížích

Podrobnosti o tom, jak diagnostikovat různé scénáře selhání, najdete v našem průvodci odstraňováním potíží.

Povolení protokolování může pomoct odhalit užitečné informace o selháních. Pokud chcete zobrazit protokol požadavků a odpovědí HTTP, nastavte proměnnou AZURE_LOG_LEVEL prostředí na info. Případně je možné protokolování povolit za běhu voláním setLogLevel v :@azure/logger

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

Další kroky

Další ukázky kódu najdete na následujících odkazech:

Přispívání

Pokud chcete přispívat do této knihovny, přečtěte si příručku pro přispívání , kde najdete další informace o tom, jak sestavit a otestovat kód.

Imprese