Biblioteka klienta usługi Azure Key Vault Secret dla języka JavaScript — wersja 4.8.0

Artykuł
02/16/2024

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 przejrzeć: Co to jest usługa Azure Key Vault?

Zarządzanie wpisami tajnymi platformy Azure Key Vault pozwala bezpiecznie przechowywać i ściśle kontrolować dostęp 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.
Zaktualizuj wpis tajny i jest to atrybuty.
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: ten pakiet nie może być używany w przeglądarce ze względu na ograniczenia usługi Azure Key Vault, zapoznaj się z tym dokumentem, aby uzyskać wskazówki.

Kluczowe linki:

Wprowadzenie

Obecnie obsługiwane środowiska

Wersje ltS Node.js

Wymagania wstępne

Subskrypcja platformy Azure
Zasób Key Vault
Istniejąca usługa Azure Key Vault. Jeśli musisz utworzyć magazyn kluczy, możesz to zrobić w witrynie Azure Portal, wykonując kroki opisane w tym dokumencie. Alternatywnie możesz użyć interfejsu wiersza polecenia platformy Azure, wykonując kroki opisane w tym dokumencie.

Instalowanie pakietu

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

npm install @azure/keyvault-secrets

Instalowanie biblioteki tożsamości

Key Vault klienci 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. Pamiętaj, że jeśli włączono compilerOptions.esModuleInteropusługę , allowSyntheticDefaultImports jest domyślnie włączona. Aby uzyskać więcej informacji, zobacz podręcznik dotyczący opcji kompilatora języka TypeScript .

Kluczowe pojęcia

Klient wpisu tajnego to podstawowy interfejs umożliwiający 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 podstawowy zestaw metod, których można użyć do tworzenia, odczytywania, aktualizowania i usuwania wpisów tajnych.
Wersja wpisu tajnego to wersja wpisu tajnego w Key Vault. Za każdym razem, gdy użytkownik przypisuje wartość do unikatowej nazwy wpisu tajnego, tworzona jest nowa wersja tego wpisu tajnego. Pobieranie wpisu tajnego według nazwy będzie zawsze zwracać najnowszą przypisaną wartość, chyba że do zapytania zostanie podana określona wersja.
Usuwanie nietrwałe umożliwia usłudze Key Vault obsługę usuwania i przeczyszczania jako dwóch oddzielnych kroków, więc usunięte wpisy tajne nie zostaną natychmiast utracone. Dzieje się tak tylko wtedy, gdy Key Vault ma włączone usuwanie nietrwałe.
Tworzenie kopii zapasowej wpisu tajnego można wygenerować na podstawie dowolnego utworzonego wpisu tajnego. Te kopie zapasowe pochodzą jako dane binarne i mogą być używane tylko do ponownego generowania 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 zawiera @azure/identity więcej szczegółów i przykładów, aby rozpocząć pracę.

Aby móc korzystać z usługi Azure Key Vault, należy utworzyć wystąpienie SecretClient klasy, 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 usługi Azure Identity.

Oto szybki przykład. Najpierw zaimportuj DefaultAzureCredential i SecretClient:

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

Po zaimportowaniu tych elementów możemy nawiązać połączenie z usługą 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);

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 to .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:

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

Przykłady

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

Tworzenie i ustawianie wpisu tajnego.
Uzyskiwanie wpisu tajnego.
Tworzenie i aktualizowanie wpisów tajnych za pomocą atrybutów.
Usuwanie wpisu tajnego.
Iterowanie list wpisów tajnych.

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.

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

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.

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

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óry może służyć do wyszukiwania i filtrowania wpisów tajnych.
contentType: dowolny ciąg, który może służyć do ułatwienia odbiorcy wpisu tajnego zrozumienia 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 , setSecretbezpośrednio po nazwie i wartości wpisu tajnego w następujący sposób:

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

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ą polecenia updateSecretPropertiesw następujący sposób:

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

Usuwanie wpisu tajnego

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

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

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

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

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

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

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

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

Iterowanie list wpisów tajnych

Za pomocą elementu SecretClient można pobrać i wykonać iterację wszystkich wpisów tajnych w 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 program wyświetli listę wszystkich nieautomowanych 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 najnowszych wersjach.
listPropertiesOfSecretVersions wyświetli listę wszystkich wersji wpisu tajnego na podstawie nazwy wpisu tajnego.

Które mogą być używane w następujący sposób:

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

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:

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

Rozwiązywanie problemów

Zobacz nasz przewodnik rozwiązywania problemów, 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ń HTTP i odpowiedzi, ustaw zmienną AZURE_LOG_LEVEL środowiskową na info. Możesz też włączyć rejestrowanie w czasie wykonywania, wywołując polecenie w elemecie setLogLevel@azure/logger:

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

setLogLevel("info");

Następne kroki

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

Współtworzenie

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

Wrażenia

Udostępnij za pośrednictwem