Tajná klientská knihovna Azure Key Vault pro JavaScript – verze 4.10.0

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 dozvědět více o službě Azure Key Vault, můžete si projít: Co je Azure Key Vault?

Správa tajných kódů služby Azure Key Vault umožňuje bezpečně ukládat a přísně řídit přístup k tokenům, heslům, certifikátům, klíčům rozhraní API a dalším tajným klíčům.

Pomocí klientské knihovny pro tajné kódy služby Azure Key Vault ve vaší aplikaci Node.js můžete:

• 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 se nedá použít v prohlížeči kvůli omezením služby Azure Key Vault. Pokyny najdete v tomto dokumentu.

Klíčové odkazy:

• Zdrojový kód
• Balíček (npm)
• Referenční dokumentace k rozhraní API
• dokumentace k produktu
• Ukázky

Začínáme

Aktuálně podporovaná prostředí

• LTS verze Node.js

Požadavky

• Předplatné Azure
• Prostředek služby Key Vault
• Existující azure Key Vault. Pokud potřebujete vytvořit trezor klíčů, můžete to udělat na webu Azure Portal pomocí kroků v tomto dokumentu. Případně můžete použít Azure CLI pomocí postupu v tomto dokumentu.

Nainstalujte balíček

Nainstalujte klientskou knihovnu tajných klíčů služby Azure Key Vault pomocí npm:

npm install @azure/keyvault-secrets

Instalace knihovny identit

Klienti služby Key Vault se ověřují pomocí knihovny identit Azure. 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

• Klient tajných kódů je primární rozhraní pro interakci s metodami rozhraní API souvisejícími s tajnými kódy v rozhraní API služby Azure Key Vault 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ého kódu je verze tajného kódu ve službě 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í. K tomu dochází jenom v případě, že služba Key Vault obnovitelné odstranění povolená.
• 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.

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

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

Pokud chcete pracovat se službou Azure Key Vault, budete muset vytvořit instanci třídy SecretClient, 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í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.

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 dokumentaci k identitě Azure.

Tady je rychlý příklad. Nejprve importujte DefaultAzureCredential a SecretClient. Po importu se můžeme 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 keys 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á 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í části obsahují fragmenty kódu, které pokrývají některé běžné úlohy pomocí tajných kódů služby Azure Key Vault. Zde popsané scénáře se skládají z:

• Vytvoření a nastavení tajného.
• Získání tajného.
• Vytváření a aktualizace tajných kódů pomocí atributů.
• Odstranění tajného.
• iterace seznamů tajných kódů.

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 službu Key Vault povolená obnovitelné odstranění, označí tato operace tajný klíč jenom jako odstraněný tajný klíč. 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í SecretClient můžete načíst a iterovat všechny tajné kódy ve službě Key Vault, stejně jako všechny odstraněné tajné kódy a verze 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 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ářů 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 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:

• ukázky tajných kódů služby Key Vault (JavaScript)
• ukázky tajných kódů služby Key Vault (TypeScript)
• testovací případy tajných kódů služby Key Vault

Přispění

Pokud chcete přispívat do této knihovny, přečtěte si průvodce přispívání a přečtěte si další informace o vytváření a testování kódu.