Udostępnij za pośrednictwem

Biblioteka klienta wpisu tajnego usługi Azure Key Vault dla języka JavaScript — wersja 4.10.0

Azure Key Vault to usługa, która umożliwia szyfrowanie kluczy uwierzytelniania, kluczy konta magazynu, kluczy szyfrowania danych, plików pfx i haseł przy użyciu zabezpieczonych kluczy. Jeśli chcesz dowiedzieć się więcej o usłudze Azure Key Vault, warto zapoznać się z tematem: Co to jest usługa Azure Key Vault?

Zarządzanie wpisami tajnymi usługi Azure Key Vault umożliwia bezpieczne przechowywanie i ścisłe kontrolowanie dostępu do tokenów, haseł, certyfikatów, kluczy interfejsu API i innych wpisów tajnych.

Użyj biblioteki klienta dla wpisów tajnych usługi Azure Key Vault w aplikacji Node.js, aby:

  • Pobieranie, ustawianie i usuwanie wpisów tajnych.
  • Aktualizowanie wpisu tajnego i jego atrybutów.
  • Tworzenie kopii zapasowej i przywracanie wpisu tajnego.
  • Pobieranie, przeczyszczanie lub odzyskiwanie usuniętego wpisu tajnego.
  • Pobierz wszystkie wersje wpisu tajnego.
  • Pobierz wszystkie wpisy tajne.
  • Pobierz wszystkie usunięte wpisy tajne.

Uwaga: nie można używać tego pakietu w przeglądarce z powodu ograniczeń usługi Azure Key Vault, zapoznaj się z tym dokumencie wskazówki.

Kluczowe linki:

Wprowadzenie

Obecnie obsługiwane środowiska

  • Wersje LTS systemu Node.js

Wymagania wstępne

Instalowanie pakietu

Zainstaluj bibliotekę klienta wpisu tajnego usługi Azure Key Vault przy użyciu narzędzia npm:

npm install @azure/keyvault-secrets

Instalowanie biblioteki tożsamości

Klienci usługi Key Vault uwierzytelniają się przy użyciu biblioteki tożsamości platformy Azure. Zainstaluj go również przy użyciu narzędzia npm

npm install @azure/identity

Konfigurowanie języka TypeScript

Użytkownicy języka TypeScript muszą mieć zainstalowane definicje typu węzła:

npm install @types/node

Należy również włączyć compilerOptions.allowSyntheticDefaultImports w tsconfig.json. Należy pamiętać, że jeśli włączono compilerOptions.esModuleInterop, allowSyntheticDefaultImports jest domyślnie włączona. Aby uzyskać więcej informacji, zobacz podręcznik opcje kompilatora języka TypeScript.

Najważniejsze pojęcia

  • klienta wpisu tajnego jest podstawowym interfejsem umożliwiającym interakcję z metodami interfejsu API powiązanymi z wpisami tajnymi w interfejsie API usługi Azure Key Vault z poziomu aplikacji JavaScript. Po zainicjowaniu udostępnia on podstawowy zestaw metod, których można użyć do tworzenia, odczytywania, aktualizowania i usuwania wpisów tajnych.
  • wersja wpisu tajnego jest wersją wpisu tajnego w usłudze Key Vault. Za każdym razem, gdy użytkownik przypisuje wartość do unikatowej nazwy wpisu tajnego, tworzona jest nowa wersja tego wpisu tajnego. Pobranie wpisu tajnego według nazwy zawsze zwróci najnowszą przypisaną wartość, chyba że do zapytania zostanie podana określona wersja.
  • usuwanie nietrwałe umożliwia magazynom kluczy obsługę usuwania i przeczyszczania jako dwóch oddzielnych kroków, dlatego usunięte wpisy tajne nie zostaną natychmiast utracone. Dzieje się tak tylko wtedy, gdy usługa Key Vault włączona usuwania nietrwałego.
  • kopii zapasowej wpisu tajnego można wygenerować na podstawie dowolnego utworzonego wpisu tajnego. Te kopie zapasowe są danymi binarnymi i mogą być używane tylko do ponownego wygenerowania wcześniej usuniętego wpisu tajnego.

Uwierzytelnianie za pomocą usługi Azure Active Directory

Usługa Key Vault korzysta z usługi Azure Active Directory do uwierzytelniania żądań w swoich interfejsach API. Pakiet @azure/identity udostępnia różne typy poświadczeń, których aplikacja może użyć do tego celu. Plik README dla @azure/identity zawiera więcej szczegółów i przykładów, które ułatwiają rozpoczęcie pracy.

Aby móc korzystać z usługi Azure Key Vault, należy utworzyć wystąpienie klasy SecretClient, adres URL magazynu i obiekt poświadczeń. Przykłady przedstawione w tym dokumencie używają obiektu poświadczeń o nazwie DefaultAzureCredential, który jest odpowiedni dla większości scenariuszy, w tym lokalnych środowisk programistycznych i produkcyjnych. Ponadto zalecamy użycie tożsamości zarządzanej do uwierzytelniania w środowiskach produkcyjnych.

Więcej informacji na temat różnych sposobów uwierzytelniania i odpowiadających im typów poświadczeń można znaleźć w dokumentacji Azure Identity.

Oto szybki przykład. Najpierw zaimportuj DefaultAzureCredential i SecretClient. Po zaimportowaniu tych elementów możemy połączyć się z usługą 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);

Określanie wersji interfejsu API usługi Azure Key Vault

Domyślnie ten pakiet używa najnowszej wersji usługi Azure Key Vault, która jest 7.1. Jedyną obsługiwaną wersją jest 7.0. Możesz zmienić używaną wersję usługi, ustawiając opcję serviceVersion w konstruktorze klienta, jak pokazano poniżej:

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

Przykłady

W poniższych sekcjach przedstawiono fragmenty kodu, które obejmują niektóre typowe zadania korzystające z wpisów tajnych usługi Azure Key Vault. Scenariusze, które zostały tutaj omówione, składają się z następujących elementów:

Tworzenie i ustawianie wpisu tajnego

setSecret przypisuje podaną wartość do określonej nazwy wpisu tajnego. Jeśli wpis tajny o tej samej nazwie już istnieje, zostanie utworzona nowa wersja wpisu tajnego.

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

Uzyskiwanie wpisu tajnego

Najprostszym sposobem odczytu wpisów tajnych z magazynu jest uzyskanie wpisu tajnego według nazwy. Spowoduje to pobranie najnowszej wersji wpisu tajnego. Opcjonalnie możesz pobrać inną wersję klucza, jeśli określisz go jako część parametrów opcjonalnych.

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

Tworzenie i aktualizowanie wpisów tajnych za pomocą atrybutów

Wpis tajny może zawierać więcej informacji niż jego nazwa i jego wartość. Mogą również zawierać następujące atrybuty:

  • tags: dowolny zestaw klucz-wartości, których można użyć do wyszukiwania i filtrowania wpisów tajnych.
  • contentType: dowolny ciąg, którego można użyć, aby ułatwić odbiorcy wpisu tajnego zrozumienie sposobu używania wartości wpisu tajnego.
  • enabled: wartość logiczna określająca, czy wartość wpisu tajnego może być odczytywana, czy nie.
  • notBefore: dana data, po której można pobrać wartość wpisu tajnego.
  • expiresOn: dana data, po której nie można pobrać wartości wpisu tajnego.

Obiekt z tymi atrybutami można wysłać jako trzeci parametr setSecret, bezpośrednio po nazwie i wartości wpisu tajnego w następujący sposób:

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

Spowoduje to utworzenie nowej wersji tego samego wpisu tajnego, która będzie zawierać najnowsze udostępnione atrybuty.

Atrybuty można również zaktualizować do istniejącej wersji wpisu tajnego za pomocą updateSecretProperties, w następujący sposób:

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

Usuwanie wpisu tajnego

Metoda beginDeleteSecret rozpoczyna usuwanie wpisu tajnego. Ten proces będzie występować w tle natychmiast po udostępnieniu niezbędnych zasobów.

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

Jeśli usuwania nietrwałego jest włączona dla usługi Key Vault, ta operacja będzie oznaczać tylko wpis tajny jako usunięty wpis tajny. Nie można zaktualizować usuniętego wpisu tajnego. Mogą być tylko odczytywane, odzyskiwane lub czyszczone.

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

Ponieważ wpisy tajne zajmują trochę czasu, aby w pełni usunąć, beginDeleteSecret zwraca obiekt Poller, który śledzi podstawową operację długotrwałą zgodnie z naszymi wytycznymi: https://azure.github.io/azure-sdk/typescript_design.html#ts-lro

Odebrany element poller umożliwia pobranie usuniętego wpisu tajnego przez wywołanie polecenia poller.getResult(). Możesz również poczekać na zakończenie usuwania, uruchamiając poszczególne wywołania usługi do momentu usunięcia wpisu tajnego lub czekając na zakończenie 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);

Innym sposobem oczekiwania na pełne usunięcie wpisu tajnego jest wykonywanie poszczególnych wywołań w następujący sposób:

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

Iterowanie list wpisów tajnych

Za pomocą obiektu SecretClient można pobierać i iterować wszystkie wpisy tajne w usłudze Key Vault, a także za pośrednictwem wszystkich usuniętych wpisów tajnych i wersji określonego wpisu tajnego. Dostępne są następujące metody interfejsu API:

  • listPropertiesOfSecrets wyświetli listę wszystkich nieu usuniętych wpisów tajnych według ich nazw, tylko w najnowszych wersjach.
  • listDeletedSecrets wyświetli listę wszystkich usuniętych wpisów tajnych według ich nazw, tylko w ich najnowszych wersjach.
  • listPropertiesOfSecretVersions wyświetli listę wszystkich wersji wpisu tajnego na podstawie nazwy wpisu tajnego.

Których można użyć w następujący sposób:

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

Wszystkie te metody będą zwracać wszystkie dostępne wyniki jednocześnie. Aby pobrać je według stron, dodaj .byPage() bezpośrednio po wywołaniu metody interfejsu API, której chcesz użyć, w następujący sposób:

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

Rozwiązywanie problemów

Zobacz nasz przewodnik rozwiązywania problemów z , aby uzyskać szczegółowe informacje na temat diagnozowania różnych scenariuszy awarii.

Włączenie rejestrowania może pomóc odkryć przydatne informacje o błędach. Aby wyświetlić dziennik żądań i odpowiedzi HTTP, ustaw zmienną środowiskową AZURE_LOG_LEVEL na info. Alternatywnie rejestrowanie można włączyć w czasie wykonywania, wywołując setLogLevel w @azure/logger:

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

setLogLevel("info");

Dalsze kroki

Więcej przykładów kodu można znaleźć za pośrednictwem następujących linków:

Wkład

Jeśli chcesz współtworzyć tę bibliotekę, przeczytaj przewodnik dotyczący współtworzenia , aby dowiedzieć się więcej na temat tworzenia i testowania kodu.