Azure Key Vault Secret client library for JavaScript - version 4.11.1

Az Azure Key Vault egy olyan szolgáltatás, amely lehetővé teszi hitelesítési kulcsok, tárolófiókkulcsok, adattitkosító kulcsok, .pfx fájlok és jelszavak titkosítását biztonságos kulcsok használatával. Ha többet szeretnél megtudni Azure Key Vault-ről, érdemes lehet áttekinteni: Mi az a Azure Key Vault?

Az Azure Key Vault titkok kezelése lehetővé teszi, hogy biztonságosan tárold és szigorúan kezeld a hozzáférést tokenekhez, jelszavakhoz, tanúsítványokhoz, API-kulcsokhoz és egyéb titkokhoz.

Használd a Node.js alkalmazásodban a Azure Key Vault titkok kliens könyvtárát a következőkhez:

  • Titkos kulcsok lekérése, beállítása és törlése.
  • Frissítsen egy titkos kulcsot és attribútumokat.
  • Titkos kulcs biztonsági mentése és visszaállítása.
  • Törölt titkos kód lekérése, törlése vagy helyreállítása.
  • A titkos kódok összes verziójának lekérése.
  • Szerezze meg az összes titkos elemet.
  • Szerezze be az összes törölt titkos kódot.

Megjegyzés: Ez a csomag a böngészőben nem használható Azure Key Vault szolgáltatási korlátok miatt, kérjük, lássa meg a this document útmutatót.

Főbb hivatkozások:

Kezdő lépések

Jelenleg támogatott környezetek

Előfeltételek

A csomag telepítése

Telepítsd az Azure Key Vault Secret client library npm-en:

npm install @azure/keyvault-secrets

Az identitástár telepítése

A Key Vault kliensei az Azure Identity Library segítségével autentikálják a hitelesítést. Telepítse az npm használatával is

npm install @azure/identity

TypeScript konfigurálása

A TypeScript-felhasználóknak telepítve kell lenniük a csomóponttípus-definícióknak:

npm install @types/node

A tsconfig.jsoncompilerOptions.allowSyntheticDefaultImports is engedélyeznie kell. Vegye figyelembe, hogy ha engedélyezte a compilerOptions.esModuleInterop, a allowSyntheticDefaultImports alapértelmezés szerint engedélyezve van. További információért tekintse meg TypeScript fordítóbeállítási kézikönyvét.

Főbb fogalmak

  • A Secret kliens az elsődleges interfész, amely a JavaScript alkalmazásból származó Azure Key Vault API titkaihoz kapcsolódó API-módszerekkel interakcióba lép. Az inicializálás után a titkos kulcsok létrehozására, olvasására, frissítésére és törlésére használható alapvető módszereket biztosít.
  • A Secret verzió egy titok változata a Key Vault-ben. Minden alkalommal, amikor egy felhasználó egy értéket rendel egy egyedi titkos kódnévhez, létrejön a titkos kód új verziója,. A titkos kód névvel való lekérése mindig a legújabb hozzárendelt értéket adja vissza, kivéve, ha a lekérdezés egy adott verziót ad meg.
  • helyreállítható törlési lehetővé teszi, hogy a Key Vaultok két külön lépésként támogassák a törlést és a törlést, így a törölt titkos kulcsok nem vesznek el azonnal. Ez csak akkor történik, ha a Key Vault bekapcsolva van a soft-delete.
  • A titkos biztonsági mentési bármely létrehozott titkos kódból létrehozható. Ezek a biztonsági másolatok bináris adatokként jönnek létre, és csak egy korábban törölt titkos kód újragenerálásához használhatók.

Authenticating with Azure Active Directory

A Key Vault szolgáltatás az Azure Active Directory-ra támaszkodik az API-jai iránti kérések hitelesítéséhez. A @azure/identity csomag számos hitelesítő adattípust biztosít, amelyeket az alkalmazás használhat erre. A README @azure/identity további részleteket és mintákat kínál, hogy elindulj.

Ahhoz, hogy az Azure Key Vault szolgáltatással interakcióba léphessen, létre kell hoznod a SecretClient osztály példányát, egy vault URL és egy credential objektumot. A dokumentumban bemutatott példák egy DefaultAzureCredentialnevű hitelesítő objektumot használnak, amely a legtöbb forgatókönyvhez, beleértve a helyi fejlesztési és éles környezeteket is. Emellett azt is javasoljuk, hogy felügyelt identitás használjon éles környezetekben történő hitelesítéshez.

További információt a hitelesítés különböző módjairól és azok megfelelő hitelesítési típusairól a Azure Identity dokumentáció oldalon találhat.

Íme egy gyors példa. Először importálja DefaultAzureCredential és SecretClient. Miután ezek importáltak, legközelebb csatlakozhatunk a Key Vault szolgáltatáshoz:

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

Böngészőkörnyezetek esetén a hitelesítéshez használja a InteractiveBrowserCredential csomagból származó @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);

Azure Key Vault service API verziójának meghatározása

Alapértelmezés szerint ez a csomag a Azure Key Vault legújabb szolgáltatási verzióját használja, amely 7.1. Az egyetlen támogatott verzió a 7.0. A használt szolgáltatásverziót az ügyfélkonstruktor serviceVersion beállításával módosíthatja az alábbiak szerint:

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éldák

Az alábbi szakaszok kódrészleteket tartalmaznak, amelyek az Azure Key Vault Secrets használatával kapcsolatos gyakori feladatokat fedik le. Az itt tárgyalt forgatókönyvek a következőkből állnak:

Titkos kód létrehozása és beállítása

setSecret hozzárendel egy megadott értéket a megadott titkos kódnévhez. Ha már létezik ilyen nevű titkos kód, akkor létrejön a titkos kód új verziója.

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

Titkos kód lekérése

A titkos kulcsok visszaolvasásának legegyszerűbb módja a titkos kulcsok név szerinti lekérése. Ez lekéri a titkos kód legújabb verzióját. Ha az opcionális paraméterek részeként adja meg, a kulcs másik verzióját is lekérheti.

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

Titkos kódok létrehozása és frissítése attribútumokkal

A titkos kódoknak több információjuk lehet, mint a neve és értéke. A következő attribútumokat is tartalmazhatják:

  • tags: A titkos kulcsok keresésére és szűrésére használható kulcsértékek összes készlete.
  • contentType: Minden olyan sztring, amely segíthet a titkos kód fogadójának megérteni a titkos érték használatát.
  • enabled: Logikai érték, amely meghatározza, hogy a titkos kulcs olvasható-e vagy sem.
  • notBefore: Egy adott dátum, amely után a titkos kód értéke lekérhető.
  • expiresOn: Egy adott dátum, amely után a titkos kulcs értéke nem kérhető le.

Az ilyen attribútumokkal rendelkező objektumok a setSecretharmadik paramétereként küldhetők el közvetlenül a titkos kód neve és értéke után, az alábbiak szerint:

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

Ezzel létrehoz egy új verziót ugyanannak a titkos kódnak, amely a legújabban megadott attribútumokkal rendelkezik.

Az attribútumok egy meglévő titkos verzióra is frissíthetők updateSecretPropertiesaz alábbiak szerint:

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

Titkos kód törlése

A beginDeleteSecret metódus elindítja egy titkos kód törlését. Ez a folyamat a háttérben fog történni, amint a szükséges erőforrások rendelkezésre állnak.

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

Ha a soft-delete engedélyezett a Key Vault számára, ez a művelet csak deleted titkként jelöli meg a titkot. A törölt titkos kódok nem frissíthetők. Csak olvashatók, helyreállíthatók vagy törölhetők.

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

Mivel a titkos kódok teljes törlése eltarthat egy ideig, beginDeleteSecret egy Poller-objektumot ad vissza, amely nyomon követi a mögöttes hosszú futású műveletet az irányelveink szerint: https://azure.github.io/azure-sdk/typescript_design.html#ts-lro

A kapott lekérdezés lehetővé teszi a törölt titkos kód lekérését a poller.getResult()hívásával. A törlés befejezését is megvárhatja, ha egyéni szolgáltatáshívásokat futtat a titkos kód törléséig, vagy megvárja, amíg a folyamat befejeződik:

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

A titkos kód teljes törlésének egy másik módja, ha egyéni hívásokat hajt végre, az alábbiak szerint:

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

Titkos kódok listájának iterálása

A SecretClient segítségével visszanyerheted és átfuttathatod az összes titkot egy Key Vault-ban, valamint az összes törölt titkot és egy adott titok verzióit. A következő API-metódusok érhetők el:

  • listPropertiesOfSecrets listázni fogja az összes nem törölt titkos kulcsát a nevük alapján, csak a legújabb verziókban.
  • listDeletedSecrets az összes törölt titkos kulcsát a nevük alapján listázhatja, csak a legújabb verziókban.
  • listPropertiesOfSecretVersions egy titkos kód összes verzióját egy titkos név alapján listázni fogja.

A következő módon használható:

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

Ezek a módszerek egyszerre az összes elérhető eredményt. Ha oldalak szerint szeretné lekérni őket, adja hozzá .byPage() közvetlenül a használni kívánt API-metódus meghívása után, az alábbiak szerint:

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

Hibaelhárítás

Lásd hibakeresési útmutatónkat a különböző hibaesetek diagnosztizálásáról.

A naplózás engedélyezése segíthet a hibákról szóló hasznos információk feltárásában. A HTTP-kérések és válaszok naplójának megtekintéséhez állítsa a környezeti változót a AZURE_LOG_LEVEL következőre info: . Alternatívaként a naplózás futásidőben is engedélyezhető a setLogLevel hívásával a @azure/logger.

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

setLogLevel("info");

Következő lépések

További kódmintákat az alábbi hivatkozásokon talál:

Közreműködés

Ha szeretnél hozzájárulni ehhez a könyvtárhoz, kérjük, olvasd el a hozzájárulás útmutatót hogy többet megtudj arról, hogyan lehet elkészíteni és tesztelni a kódot.

  • Last updated on