Udostępnij za pośrednictwem

Azure Key Vault Secret client library for JavaScript - version 4.11.1

Azure Key Vault to usługa, która pozwala szyfrować klucze uwierzytelniające, konta magazynowego, klucze do szyfrowania danych, pliki .pfx oraz hasła za pomocą kluczy zabezpieczonych. Jeśli chcesz dowiedzieć się więcej o Azure Key Vault, możesz zapoznać się z napisem: Co to jest Azure Key Vault?

Zarządzanie sekretami Azure Key Vault pozwala bezpiecznie przechowywać i ściśle kontrolować dostęp do tokenów, haseł, certyfikatów, kluczy API i innych sekretów.

Użyj biblioteki klienta do Azure Key Vault Sekretów 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: Ten pakiet nie może być używany w przeglądarce ze względu na ograniczenia Azure Key Vault usługi, prosimy o odwiedzenie ten dokument w celu uzyskania wskazówek.

Kluczowe linki:

Wprowadzenie

Obecnie obsługiwane środowiska

  • Wersje LTS systemu Node.js

Wymagania wstępne

Instalowanie pakietu

Zainstaluj bibliotekę klienta Azure Key Vault Secret za pomocą npm:

npm install @azure/keyvault-secrets

Instalowanie biblioteki tożsamości

Klienci Key Vault uwierzytelniają się za pomocą biblioteki Azure Identity. 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

  • Secret client jest głównym interfejsem do interakcji z metodami API dotyczącymi sekretów w API Azure Key Vault z 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 Tajna to wersja sekretu w 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 Key Vault ma włączone soft-delete włączone.
  • 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 z Azure Active Directory

Usługa Key Vault polega na Azure Active Directory do uwierzytelniania żądań do swoich API. Pakiet @azure/identity udostępnia różne typy poświadczeń, których aplikacja może użyć do tego celu. README dla @azure/identity zawiera więcej szczegółów i przykładów, które pomogą Ci zacząć.

Aby wchodzić w interakcję z usługą Azure Key Vault, musisz utworzyć instancję klasy SecretClient, adres URL vault oraz obiekt poświadczenia. 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 o różnych sposobach uwierzytelniania i ich typach poświadczeń znajdziesz w Azure Dokument tożsamości.

Oto szybki przykład. Najpierw zaimportuj DefaultAzureCredential i SecretClient. Po ich zaimportowaniu możemy następnie 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 secrets client and connect to the service
const client = new SecretClient(url, credential);

W przypadku środowisk przeglądarki użyj InteractiveBrowserCredential z pakietu @azure/identity do uwierzytelniania.

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

Specifying the Azure Key Vault service API version

Domyślnie ten pakiet korzysta z 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

Poniższe sekcje zawierają fragmenty kodu obejmujące niektóre z typowych zadań korzystających z Azure Key Vault Secrets. 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 soft-delete jest włączony dla Key Vault, operacja ta oznaczy sekret jedynie jako sekret deleted sekret. 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

Korzystając z SecretClient, możesz pobierać i iterować wszystkie sekrety w Key Vault, a także wszystkie usunięte sekrety i wersje konkretnego sekretu. 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 trouble aby uzyskać szczegóły dotyczące 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 przyczynić się do tej biblioteki, przeczytaj przewodnik wkład aby dowiedzieć się więcej o budowaniu i testowaniu kodu.

  • Last updated on