Azure Key Vault Secret client library for JavaScript - verze 4.11.1

Azure Key Vault je služba, která umožňuje šifrovat autentizační klíče, klíče k úložným účtům, šifrovací klíče dat, .pfx soubory a hesla pomocí zabezpečených klíčů. Pokud byste se chtěli o Azure Key Vault dozvědět více, možná byste měli přečíst: Co je Azure Key Vault?

Správa Azure Key Vault Secrets vám umožňuje bezpečně ukládat a přísně kontrolovat přístup k tokenům, heslům, certifikátům, API klíčům a dalším tajemstvím.

Použijte klientskou knihovnu pro Azure Key Vault tajemství ve vaší Node.js aplikaci, abyste:

  • Získejte, nastavte a odstraňte tajné kódy.
  • Aktualizujte tajný klíč a jeho atributy.
  • Zálohování a obnovení tajného kódu
  • Získejte, vyprázdně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 v prohlížeči používat kvůli Azure Key Vault omezením služeb, pro doporučení se prosím podívejte na tento dokument pro doporučení.

Klíčové odkazy:

Začínáme

Aktuálně podporovaná prostředí

Požadavky

Nainstalujte balíček

Nainstalujte klientskou knihovnu Azure Key Vault Secret pomocí npm:

npm install @azure/keyvault-secrets

Instalace knihovny identit

Klienti Key Vault se autentizují pomocí Azure Identity Library. Nainstalujte ho i pomocí npm.

npm install @azure/identity

Konfigurace TypeScriptu

Uživatelé TypeScriptu musí mít nainstalované definice typu Node:

npm install @types/node

Musíte také povolit compilerOptions.allowSyntheticDefaultImports ve svém 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 možnosti kompilátoru TypeScriptu.

Klíčové koncepty

  • Secret client je primární rozhraní pro interakci s API metodami souvisejícími se sekrety v Azure Key Vault API z JavaScriptové aplikace. 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á je verze tajemství 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 kódu. Načtení tajného kódu podle názvu vždy vrátí nejnovější přiřazenou hodnotu, pokud není pro dotaz zadána konkrétní verze.
  • obnovitelného odstranění umožňuje službě Key Vault podporovat odstranění a vyprázdnění jako dva samostatné kroky, takže odstraněné tajné kódy se okamžitě neztratí. To se děje jen tehdy, pokud má Key Vault zapnuté soft-delete.
  • Zálohování tajných kódů lze vygenerovat z jakéhokoli vytvořeného tajného kódu. Tyto zálohy pocházejí jako binární data a lze je použít pouze k opětovnému vygenerování dříve odstraněného tajného kódu.

Autentizace pomocí Azure Active Directory

Služba Key Vault spoléhá na Azure Active Directory k autentizaci požadavků na své API. Balíček @azure/identity poskytuje řadu typů přihlašovacích údajů, které může vaše aplikace použít k tomu. README pro @azure/identity poskytuje více podrobností a ukázky, které vám pomohou začít.

Pro interakci se službou Azure Key Vault budete muset vytvořit instanci třídy , URL vault a objekt s přihlašováním. 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ího vývojového a produkčního prostředí. Kromě toho doporučujeme použít spravovanou identitu pro ověřování v produkčních prostředích.

Více informací o různých způsobech ověřování a jejich odpovídajících typech přihlašovacích údajů najdete v Azure Identity documentation.

Tady je rychlý příklad. Nejprve importujte DefaultAzureCredential a SecretClient. Jakmile jsou importovány, můžeme se připojit ke službě Key Vault:

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@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);

Pro prostředí prohlížeče použijte k ověření InteractiveBrowserCredential z balíčku @azure/identity.

import { InteractiveBrowserCredential } from "@azure/identity";
import { SecretClient } from "@azure/keyvault-secrets";

const credential = new InteractiveBrowserCredential({
  tenantId: "<YOUR_TENANT_ID>",
  clientId: "<YOUR_CLIENT_ID>",
});
const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;
const client = new SecretClient(url, credential);

Specificifying the Azure Key Vault service API version

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

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@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`;

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

Příklady

Následující sekce poskytují úryvky kódu, které pokrývají některé běžné úkoly využívající Azure Key Vault Secrets. Zde popsané scénáře se skládají z:

Vytvoření a nastavení tajného kódu

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

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@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";

const result = await client.setSecret(secretName, "MySecretValue");
console.log("result: ", result);

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. Pokud ho zadáte jako součást volitelných parametrů, můžete volitelně získat jinou verzi klíče.

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@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";

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,
);

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

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

  • tags: Libovolná sada hodnot klíčů, které lze použít k vyhledávání a filtrování tajných kódů.
  • contentType: Libovolný řetězec, který lze použít k tomu, aby příjemci tajného klíče pomohl pochopit, jak používat tajnou hodnotu.
  • enabled: Logická hodnota, která určuje, zda je možné hodnotu tajného kódu číst, nebo ne.
  • notBefore: Zadané datum, po kterém lze 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 lze odeslat jako třetí parametr setSecret, hned za názvem a hodnotou tajného kódu následujícím způsobem:

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@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";

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

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

Atributy lze také aktualizovat na existující verzi tajného kódu pomocí updateSecretPropertiesnásledujícím způsobem:

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@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";

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

Odstranění tajného kódu

Metoda beginDeleteSecret spustí odstranění tajného kódu. K tomuto procesu dojde na pozadí, jakmile budou k dispozici potřebné prostředky.

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@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";

await client.beginDeleteSecret(secretName);

Pokud je pro Key Vault povoleno soft-delete, tato operace označí tajemství pouze jako deleted tajemství. Odstraněný tajný kód nejde aktualizovat. Dají se buď číst, obnovit nebo vyprázdnit.

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@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";

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);

Vzhledem k tomu, že úplné odstranění tajných kódů nějakou dobu trvá, beginDeleteSecret vrátí objekt Poller, který sleduje základní dlouho běží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 poller.getResult(). Můžete také počkat, až se odstranění dokončí, a to buď spuštěním jednotlivých volání služeb, dokud se tajný klíč odstraní, nebo čekáním na dokončení procesu:

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@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";

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);

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

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@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";

const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

const poller = await client.beginDeleteSecret(secretName);
while (!poller.isDone()) {
  await poller.poll();
  await delay(5000);
}

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

Iterace seznamů tajných kódů

Pomocí SecretClientu můžete vyhledávat a iterovat všechna tajemství v Key Vault, stejně jako všechna smazaná tajemství a verze konkrétního tajemství. 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 nejnovějších verzích.
  • listDeletedSecrets zobrazí seznam všech odstraněných tajných kódů podle jejich názvů, pouze v 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 následujícím způsobem:

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@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";

for await (const secretProperties of client.listPropertiesOfSecrets()) {
  console.log("Secret properties: ", secretProperties);
}

for await (const deletedSecret of client.listDeletedSecrets()) {
  console.log("Deleted secret: ", deletedSecret);
}

for await (const versionProperties of client.listPropertiesOfSecretVersions(secretName)) {
  console.log("Version properties: ", versionProperties);
}

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

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@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";

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

Řešení problémů

Podrobnosti o diagnostice různých scénářů poruch najdete v našem trouble guide pro podrobnosti.

Povolení protokolování může pomoct odhalit užitečné informace o chybách. Pokud chcete zobrazit protokol požadavků a odpovědí HTTP, nastavte proměnnou prostředí AZURE_LOG_LEVEL na info. Případně můžete 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ění

Pokud byste chtěli přispět do této knihovny, přečtěte si prosím průvodce přispívání kde se dozvíte více o tom, jak kód sestavit a testovat.

  • Last updated on