Delen via

Azure Key Vault Secret client library voor JavaScript - versie 4.11.1

Azure Key Vault is een dienst waarmee je authenticatiesleutels, opslagrekeningsleutels, data-encryptiesleutels, .pfx-bestanden en wachtwoorden kunt versleutelen door beveiligde sleutels te gebruiken. Als je meer over Azure Key Vault wilt weten, kun je het volgende bekijken: Wat is Azure Key Vault?

Azure Key Vault Secrets-beheer stelt je in staat om tokens, wachtwoorden, certificaten, API-sleutels en andere geheimen veilig op te slaan en streng te controleren.

Gebruik de clientbibliotheek voor Azure Key Vault Secrets in je Node.js-applicatie om:

  • Geheimen ophalen, instellen en verwijderen.
  • Werk een geheim bij en dit zijn kenmerken.
  • Back-up maken en een geheim herstellen.
  • Een verwijderd geheim ophalen, opschonen of herstellen.
  • Haal alle versies van een geheim op.
  • Haal alle geheimen op.
  • Haal alle verwijderde geheimen op.

Opmerking: Dit pakket kan niet in de browser worden gebruikt vanwege Azure Key Vault servicebeperkingen, raadpleeg dit document voor richtlijnen.

Sleutelkoppelingen:

Aan de slag

Momenteel ondersteunde omgevingen

Vereiste voorwaarden

Installeer het pakket

Installeer de Azure Key Vault Secret clientbibliotheek met npm:

npm install @azure/keyvault-secrets

De identiteitsbibliotheek installeren

Key Vault-clients authenticeren zich 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 compilerOptions.allowSyntheticDefaultImports inschakelen in uw tsconfig.json. Houd er rekening mee dat als u compilerOptions.esModuleInterophebt ingeschakeld, allowSyntheticDefaultImports standaard is ingeschakeld. Zie het handboek voor compileropties van TypeScript voor meer informatie.

Belangrijke concepten

  • De Secret client is de primaire interface om te communiceren met de API-methoden die betrekking hebben op geheimen in de Azure Key Vault API vanuit een JavaScript-applicatie. Zodra het is geïnitialiseerd, biedt het een basisset methoden die kunnen worden gebruikt voor het maken, lezen, bijwerken en verwijderen van geheimen.
  • Een Secret versie is een versie van een secret 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. Het ophalen van een geheim op basis van een naam retourneert altijd de meest recente waarde die is toegewezen, tenzij er een specifieke versie aan de query wordt verstrekt.
  • Voorlopig verwijderen kan Key Vaults ondersteuning bieden voor verwijdering en opschonen als twee afzonderlijke stappen, zodat verwijderde geheimen niet onmiddellijk verloren gaan. Dit gebeurt alleen als de Key Vault soft-delete heeft ingeschakeld.
  • Een Back-up van geheim kan 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.

Authenticatie met Azure Active Directory

De Key Vault-service is afhankelijk van Azure Active Directory om verzoeken aan zijn API's te authenticeren. Het @azure/identity-pakket biedt verschillende referentietypen die uw toepassing hiervoor kan gebruiken. De README voor @azure/identity geeft meer details en voorbeelden om je op weg te helpen.

Om met de Azure Key Vault-service te kunnen interageren, moet je een instantie van de klasse SecretClient aanmaken, een vault url en een credential-object. In de voorbeelden in dit document wordt een referentieobject met de naam DefaultAzureCredentialgebruikt. Dit is geschikt voor de meeste scenario's, waaronder lokale ontwikkel- en productieomgevingen. Daarnaast raden we u aan een beheerde identiteit te gebruiken voor verificatie in productieomgevingen.

Meer informatie over verschillende manieren van authenticatie en hun bijbehorende credentialtypes vindt u in de Azure Identiteitsdocumentatie.

Hier volgt een snel voorbeeld. Importeer eerst DefaultAzureCredential en SecretClient. Zodra deze zijn geïmporteerd, kunnen we vervolgens verbinding maken met de Key Vault-dienst:

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

Gebruik voor browseromgevingen de InteractiveBrowserCredential uit het @azure/identity-pakket om te verifiëren.

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

Het specificeren van de Azure Key Vault service API-versie

Standaard gebruikt dit pakket de nieuwste Azure Key Vault service-versie, namelijk 7.1. De enige andere versie die wordt ondersteund, is 7.0. U kunt de serviceversie wijzigen die wordt gebruikt door de optie in te stellen serviceVersion in de clientconstructor, zoals hieronder wordt weergegeven:

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

Voorbeelden

De volgende secties bieden codefragmenten die enkele veelvoorkomende taken behandelen met Azure Key Vault Secrets. 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.

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

Een geheim ophalen

De eenvoudigste manier om geheimen terug te lezen uit de kluis is door een geheim op naam te krijgen. 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.

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

Geheimen maken en bijwerken met kenmerken

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

  • tags: elke set sleutelwaarden die kunnen worden gebruikt om geheimen te doorzoeken 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 al dan niet kan worden gelezen.
  • notBefore: een bepaalde datum waarna de geheime waarde kan worden opgehaald.
  • expiresOn: een bepaalde datum waarna de geheime waarde niet kan worden opgehaald.

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

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

Hiermee maakt u een nieuwe versie van hetzelfde geheim, met de meest recente opgegeven kenmerken.

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

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

Een geheim verwijderen

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

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

Als soft-delete is ingeschakeld voor de Key Vault, zal deze bewerking het geheim alleen labelen als een deleted geheim. Een verwijderd geheim kan niet worden bijgewerkt. Ze kunnen alleen worden gelezen, hersteld of verwijderd.

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

Omdat geheimen enige tijd in beslag nemen om volledig te worden verwijderd, retourneert beginDeleteSecret een Poller-object dat de onderliggende langdurige 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 naar poller.getResult()aan te roepen. U kunt ook wachten totdat het verwijderen is voltooid, door afzonderlijke service-aanroepen uit te voeren totdat het geheim is verwijderd of door te wachten totdat het proces is voltooid:

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

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

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

Lijsten met geheimen herhalen

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

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

Dit kan als volgt worden gebruikt:

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

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

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

Probleemoplossingsproces

Zie onze probleemoplossingsgids voor details over hoe je verschillende storingsscenario's kunt diagnosticeren.

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

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

setLogLevel("info");

Volgende stappen

U vindt meer codevoorbeelden via de volgende koppelingen:

Bijdragen

Als je wilt bijdragen aan deze bibliotheek, lees dan de bijdragende gids om meer te weten te komen over hoe je de code bouwt en test.

  • Last updated on