Azure Key Vault Secret-clientbibliotheek voor JavaScript - versie 4.8.0

  • Artikel

Azure Key Vault is een service waarmee u verificatiesleutels, opslagaccountsleutels, gegevensversleutelingssleutels, PFX-bestanden en wachtwoorden kunt versleutelen met behulp van beveiligde sleutels. Als u meer wilt weten over Azure Key Vault, kunt u het volgende lezen: Wat is Azure Key Vault?

Met Azure Key Vault Geheimenbeheer kunt u de toegang tot tokens, wachtwoorden, certificaten, API-sleutels en andere geheimen veilig opslaan en strikt beheren.

Gebruik de clientbibliotheek voor Azure Key Vault Secrets in uw Node.js-toepassing om het volgende te doen:

  • Geheimen ophalen, instellen en verwijderen.
  • Werk een geheim en de kenmerken ervan bij.
  • Maak een back-up van een geheim en herstel deze.
  • Een verwijderd geheim ophalen, opschonen of herstellen.
  • Alle versies van een geheim ophalen.
  • Haal alle geheimen op.
  • Haal alle verwijderde geheimen op.

Opmerking: dit pakket kan niet worden gebruikt in de browser vanwege beperkingen van de Azure Key Vault-service. Raadpleeg dit document voor hulp.

Belangrijke koppelingen:

Aan de slag

Momenteel ondersteunde omgevingen

Vereisten

Het pakket installeren

Installeer de Azure Key Vault Secret-clientbibliotheek met behulp van npm:

npm install @azure/keyvault-secrets

De identiteitsbibliotheek installeren

Key Vault clients verifiëren met behulp van de Azure Identity Library. Installeer het ook met npm

npm install @azure/identity

TypeScript configureren

TypeScript-gebruikers moeten knooppunttypedefinities hebben geïnstalleerd:

npm install @types/node

U moet ook inschakelen compilerOptions.allowSyntheticDefaultImports in uw tsconfig.json. Houd er rekening mee dat als u hebt ingeschakeld compilerOptions.esModuleInterop, allowSyntheticDefaultImports standaard is ingeschakeld. Zie het handboek voor compileropties van TypeScript voor meer informatie.

Belangrijkste concepten

  • De Secret-client is de primaire interface voor interactie met de API-methoden met betrekking tot geheimen in de Azure Key Vault-API vanuit een JavaScript-toepassing. Zodra het is geïnitialiseerd, biedt het een basisset met methoden die kunnen worden gebruikt om geheimen te maken, lezen, bijwerken en verwijderen.
  • Een geheime versie is een versie van een geheim in de Key Vault. Telkens wanneer een gebruiker een waarde toewijst aan een unieke geheime naam, wordt er een nieuwe versie van dat geheim gemaakt. Als u een geheim op basis van een naam opvraagt, wordt altijd de meest recente waarde geretourneerd die is toegewezen, tenzij een specifieke versie wordt opgegeven voor de query.
  • Met voorlopig verwijderen kunnen Key Vaults het verwijderen en opschonen als twee afzonderlijke stappen ondersteunen, zodat verwijderde geheimen niet onmiddellijk verloren gaan. Dit gebeurt alleen als voor de Key Vault voorlopig verwijderen is ingeschakeld.
  • Er kan een back-up van het geheim worden gegenereerd op basis van elk gemaakt geheim. Deze back-ups worden geleverd als binaire gegevens en kunnen alleen worden gebruikt om een eerder verwijderd geheim opnieuw te genereren.

Verifiëren met Azure Active Directory

De Key Vault-service is afhankelijk van Azure Active Directory om aanvragen voor de API's te verifiëren. Het @azure/identity pakket biedt verschillende referentietypen die uw toepassing kan gebruiken om dit te doen. Leesmij voor @azure/identity biedt meer details en voorbeelden om u op weg te helpen.

Als u wilt communiceren met de Azure Key Vault-service, moet u een exemplaar van de SecretClient klasse, een kluis-URL en een referentieobject maken. De voorbeelden in dit document maken gebruik van een referentieobject met de naam DefaultAzureCredential, dat geschikt is voor de meeste scenario's, waaronder lokale ontwikkelings- en productieomgevingen. Daarnaast raden we u aan een beheerde identiteit te gebruiken voor verificatie in productieomgevingen.

Meer informatie over verschillende manieren van verificatie en de bijbehorende referentietypen vindt u in de Documentatie over Azure Identity.

Hier volgt een kort voorbeeld. DefaultAzureCredential Importeer eerst en SecretClient:

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

Zodra deze zijn geïmporteerd, kunnen we vervolgens verbinding maken met de Key Vault-service:

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

De API-versie van de Azure Key Vault-service opgeven

Dit pakket maakt standaard gebruik van de nieuwste serviceversie van Azure Key Vault, namelijk 7.1. De enige andere versie die wordt ondersteund, is 7.0. U kunt de gebruikte serviceversie wijzigen door de optie serviceVersion in te stellen in de clientconstructor, zoals hieronder wordt weergegeven:

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

Voorbeelden

De volgende secties bevatten codefragmenten die betrekking hebben op enkele veelvoorkomende taken met behulp van Azure Key Vault Geheimen. De scenario's die hier worden behandeld, bestaan uit:

Een geheim maken en instellen

setSecret wijst een opgegeven waarde toe aan de opgegeven geheime naam. Als er al een geheim met dezelfde naam bestaat, wordt er een nieuwe versie van het geheim gemaakt.

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

Een geheim ophalen

De eenvoudigste manier om geheimen uit de kluis te lezen, is door een geheim op naam op te halen. Hiermee wordt de meest recente versie van het geheim opgehaald. U kunt desgewenst een andere versie van de sleutel ophalen als u deze opgeeft als onderdeel van de optionele parameters.

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

Geheimen met kenmerken maken en bijwerken

Een geheim kan meer informatie bevatten dan de naam en de waarde ervan. Ze kunnen ook de volgende kenmerken bevatten:

  • tags: een set sleutelwaarden die kan worden gebruikt om geheimen te zoeken en te filteren.
  • contentType: elke tekenreeks die kan worden gebruikt om de ontvanger van het geheim te helpen begrijpen hoe de geheime waarde moet worden gebruikt.
  • enabled: Een booleaanse waarde die bepaalt of de geheime waarde kan worden gelezen of niet.
  • notBefore: Een opgegeven datum waarna de geheime waarde kan worden opgehaald.
  • expiresOn: Een opgegeven datum waarna de geheime waarde niet kan worden opgehaald.

Een object met deze kenmerken kan als volgt worden verzonden als de derde parameter van setSecret, direct na de naam en waarde van het geheim:

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

Hiermee wordt een nieuwe versie van hetzelfde geheim gemaakt, die de meest recente kenmerken heeft.

Kenmerken kunnen ook als volgt worden bijgewerkt naar een bestaande geheime versie met updateSecretProperties:

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

Een geheim verwijderen

Met beginDeleteSecret de methode wordt het verwijderen van een geheim gestart. Dit proces vindt plaats op de achtergrond zodra de benodigde resources beschikbaar zijn.

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

Als voorlopig verwijderen is ingeschakeld voor de Key Vault, wordt met deze bewerking het geheim alleen gelabeld als een verwijderd geheim. Een verwijderd geheim kan niet worden bijgewerkt. Ze kunnen alleen worden gelezen, hersteld of opgeschoond.

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

Omdat het enige tijd duurt voordat geheimen volledig zijn verwijderd, beginDeleteSecret wordt een Poller-object geretourneerd dat de onderliggende langlopende bewerking bijhoudt volgens onze richtlijnen: https://azure.github.io/azure-sdk/typescript_design.html#ts-lro

Met de ontvangen poller kunt u het verwijderde geheim ophalen door aan te roepen naar poller.getResult(). U kunt ook wachten totdat het verwijderen is voltooid, door afzonderlijke serviceoproepen uit te voeren totdat het geheim is verwijderd of door te wachten totdat het proces is voltooid:

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

Een andere manier om te wachten totdat het geheim volledig is verwijderd, is door als volgt afzonderlijke aanroepen uit te voeren:

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

Herhalende lijsten met geheimen

Met de SecretClient kunt u alle geheimen in een Key Vault ophalen en herhalen, evenals alle verwijderde geheimen en de versies van een specifiek geheim. De volgende API-methoden zijn beschikbaar:

  • listPropertiesOfSecrets vermeldt al uw niet-verwijderde geheimen op hun naam, alleen in hun nieuwste versies.
  • listDeletedSecrets vermeldt al uw verwijderde geheimen op hun naam, alleen in hun nieuwste versies.
  • listPropertiesOfSecretVersions geeft een lijst weer van alle versies van een geheim op basis van een geheime naam.

Deze kan als volgt worden gebruikt:

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

Al deze methoden retourneren alle beschikbare resultaten in één keer. Als u deze op pagina's wilt ophalen, voegt u als volgt toe .byPage() nadat u de API-methode hebt aangeroepen die u wilt gebruiken:

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

Problemen oplossen

Zie onze gids voor probleemoplossing voor meer informatie over het diagnosticeren van verschillende foutscenario's.

Het inschakelen van logboekregistratie kan helpen bij het ontdekken van nuttige informatie over fouten. Als u een logboek met HTTP-aanvragen en -antwoorden wilt zien, stelt u de AZURE_LOG_LEVEL omgevingsvariabele in op info. U kunt logboekregistratie ook tijdens runtime inschakelen door aan te roepen setLogLevel in de @azure/logger:

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

setLogLevel("info");

Volgende stappen

Meer codevoorbeelden vindt u via de volgende koppelingen:

Bijdragen

Als u een bijdrage wilt leveren aan deze bibliotheek, leest u de handleiding voor bijdragen voor meer informatie over het bouwen en testen van de code.

Weergaven