Share via

Azure Key Vault Secret ügyfélkódtár JavaScripthez – 4.8.0-s verzió

  • Cikk

Az Azure Key Vault egy olyan szolgáltatás, amellyel biztonságos kulcsokkal titkosíthatja a hitelesítési kulcsokat, a tárfiókkulcsokat, az adattitkosítási kulcsokat, a .pfx fájlokat és a jelszavakat. Ha többet szeretne megtudni az Azure Key Vault-ról, tekintse át a következőt: Mi az az Azure Key Vault?

Az Azure Key Vault Titkos kódok kezelése lehetővé teszi a jogkivonatokhoz, jelszavakhoz, tanúsítványokhoz, API-kulcsokhoz és egyéb titkos kulcsokhoz való hozzáférés biztonságos tárolását és szigorú szabályozását.

Használja az Azure Key Vault Secrets ügyfélkódtárát a Node.js alkalmazásban a következő célokra:

  • Titkos kódok beolvasása, beállítása és törlése.
  • Titkos kód és attribútumok frissítése.
  • Titkos kód biztonsági mentése és visszaállítása.
  • Törölt titkos kód lekérése, végleges törlése vagy helyreállítása.
  • A titkos kód összes verziójának lekérése.
  • Szerezd meg az összes titkos kódot.
  • Szerezze be az összes törölt titkos kódot.

Megjegyzés: Ez a csomag az Azure Key Vault szolgáltatás korlátozásai miatt nem használható a böngészőben. Útmutatásért tekintse meg ezt a dokumentumot.

Főbb hivatkozások:

Első lépések

Jelenleg támogatott környezetek

Előfeltételek

A csomag telepítése

Telepítse az Azure Key Vault Secret ügyfélkódtárat az npm használatával:

npm install @azure/keyvault-secrets

Az identitástár telepítése

Key Vault ügyfelek hitelesítése az Azure Identity Library használatával. Az npm használatával is telepítheti

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.json is engedélyeznie compilerOptions.allowSyntheticDefaultImports kell. Vegye figyelembe, hogy ha engedélyeztecompilerOptions.esModuleInteropallowSyntheticDefaultImports, a alapértelmezés szerint engedélyezve van. További információt a TypeScript fordítóbeállítási kézikönyvében talál.

Fő fogalmak

  • A Titkos ügyfél az elsődleges felület, amely egy JavaScript-alkalmazásból származó Azure Key Vault API titkos kódokkal kapcsolatos API-metódusaival kommunikál. Az inicializálás után a titkos kulcsok létrehozásához, olvasásához, frissítéséhez és törléséhez használható egyszerű metóduskészletet biztosít.
  • A titkos kód verziója a titkos kód egy verziója a Key Vault. 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 történő lekérése mindig a legújabb hozzárendelt értéket adja vissza, hacsak nem ad meg egy adott verziót a lekérdezésnek.
  • A helyreállítható törlés 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 fordul elő, ha a Key Vault engedélyezve van a helyreállítható törlés.
  • A titkos kódok biztonsági mentése 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 újbóli létrehozásához használhatók.

Hitelesítés az Azure Active Directoryval

A Key Vault szolgáltatás az Azure Active Directoryra támaszkodik az API-k felé irányuló kérések hitelesítéséhez. A @azure/identity csomag számos hitelesítőadat-típust biztosít, amelyeket az alkalmazás ehhez használhat. A README for @azure/identity további részleteket és mintákat tartalmaz az első lépésekhez.

Az Azure Key Vault szolgáltatás használatához létre kell hoznia SecretClient egy osztálypéldányt, egy tároló URL-címét és egy hitelesítőadat-objektumot. Az ebben a dokumentumban bemutatott példák egy nevű hitelesítő objektumot DefaultAzureCredentialhasználnak, amely a legtöbb forgatókönyvhöz, beleértve a helyi fejlesztési és éles környezeteket is. Emellett azt javasoljuk, hogy felügyelt identitást használjon a hitelesítéshez éles környezetben.

A hitelesítés különböző módjairól és a hozzájuk tartozó hitelesítő adatok típusairól az Azure Identity dokumentációjában talál további információt.

Íme egy gyors példa. Először importálja DefaultAzureCredential és SecretClient:

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

Az importálás után csatlakozhatunk a Key Vault szolgáltatáshoz:

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

Az Azure Key Vault szolgáltatás API-verziójának megadása

Alapértelmezés szerint ez a csomag az Azure Key Vault legújabb szolgáltatásverzióját használja, amely a következő7.1: . Az egyetlen támogatott verzió a 7.0következő: . A használt szolgáltatásverziót az ügyfélkonstruktorban az alábbi módon serviceVersion állíthatja be:

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

Példák

Az alábbi szakaszok olyan kódrészleteket nyújtanak, amelyek az Azure Key Vault Titkos kódokat használó gyakori feladatok némelyikét ismertetik. 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 egy új verziója.

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

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 a választható paraméterek részeként adja meg, a kulcs másik verzióját is lekérheti.

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

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

A titkos kódnak több információja 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: Bármely 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 érték 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 kód értéke nem kérhető le.

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

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

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

Az attribútumok frissíthetők egy meglévő titkos verzióra is a használatával updateSecretProperties, az alábbiak szerint:

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

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 történik, amint a szükséges erőforrások elérhetővé válnak.

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

Ha a helyreállítható törlés engedélyezve van a Key Vault, ez a művelet csak törölt titkos kódként címkézi fel a titkos kódot. A törölt titkos kódok nem frissíthetők. Csak olvashatók, helyreállíthatók vagy törölhetők.

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

Mivel a titkos kódok teljes törlése eltarthat egy ideig, egy Poller-objektumot ad vissza, beginDeleteSecret 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 következő hívásával: poller.getResult(). 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 a folyamat befejezését:

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

A titkos kód teljes törlésének egy másik módja az egyéni hívások lebonyolítása, az alábbiak szerint:

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

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

A SecretClient használatával lekérheti és iterálhatja egy Key Vault összes titkos kódját, valamint az összes törölt titkos kulcsot és egy adott titkos kód verzióit. A következő API-metódusok érhetők el:

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

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

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

Ezen metódusok mindegyike egyszerre adja vissza az összes elérhető eredményt . Ha oldalak alapján 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:

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

Hibaelhárítás

A különböző hibaforgatókönyvek diagnosztizálásával kapcsolatos részletekért tekintse meg a hibaelhárítási útmutatónkat .

A naplózás engedélyezése hasznos információkat deríthet fel a hibákról. A HTTP-kérések és -válaszok naplójának megtekintéséhez állítsa a környezeti változót értékre AZURE_LOG_LEVELinfo. A naplózás futásidőben is engedélyezhető a következő hívásával setLogLevel@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álhat:

Közreműködés

Ha hozzá szeretne járulni ehhez a kódtárhoz, olvassa el a közreműködői útmutatót , amelyből többet is megtudhat a kód buildeléséhez és teszteléséhez.

Megjelenések