Quickstart: Azure Key Vault-certificaatclientbibliotheek voor JavaScript

Artikel
08/07/2024

Ga aan de slag met de Azure Key Vault-clientbibliotheek met certificaten voor JavaScript. Azure Key Vault is een cloudservice die werkt als een beveiligd archief voor certificaten. U kunt veilig sleutels, wachtwoorden, certificaten en andere geheime informatie opslaan. Azure-sleutelkluizen kunnen worden gemaakt en beheerd via Azure Portal. In deze quickstart leert u hoe u certificaten maakt, ophaalt en verwijdert uit een Azure-sleutelkluis met behulp van de JavaScript-clientbibliotheek.

Resources voor de Key Vault-clientbibliotheek:

API-referentiedocumentatie | Bibliotheekbroncode | Package (npm)

Zie voor meer informatie over Key Vault en certificaten:

Vereisten

Een Azure-abonnement (u kunt een gratis abonnement maken).
Huidige Node.js LTS.
Azure-CLI
Een bestaande sleutelkluis: u kunt er een maken met:

Een Azure-abonnement (u kunt een gratis abonnement maken).
Huidige Node.js LTS.
TypeScript 5+
Azure-CLI
Een bestaande sleutelkluis: u kunt er een maken met:

In deze quickstart wordt ervan uitgegaan dat u Azure CLI uitvoert.

Voer de opdracht login uit.
```
az login
```
Als de CLI uw standaardbrowser kan openen, gebeurt dat ook en wordt er een Azure-aanmeldingspagina geladen.

Als dat niet het geval is, opent u een browserpagina op https://aka.ms/devicelogin en voert u de autorisatiecode in die wordt weergegeven in de terminal.
Meldt u zich in de browser aan met uw accountreferenties.

Een nieuwe Node.js-toepassing maken

Maak een Node.js-toepassing die gebruikmaakt van uw sleutelkluis.

Maak in een terminal een map met de naam key-vault-node-app en ga naar die map:
```
mkdir key-vault-node-app && cd key-vault-node-app
```
Initialiseer het Node.js project:
```
npm init -y
```

Key Vault-pakketten installeren

Installeer met behulp van de terminal de Azure Key Vault-geheimenbibliotheek, @azure/keyvault-certificates voor Node.js.
```
npm install @azure/keyvault-certificates
```
Installeer de Azure Identity-clientbibliotheek, @azure/identiteit, om te verifiëren bij een Key Vault.
```
npm install @azure/identity
```

Als u uw toepassingsmachtigingen wilt verlenen aan uw sleutelkluis via op rollen gebaseerd toegangsbeheer (RBAC), wijst u een rol toe met behulp van de Azure CLI-opdracht az role assignment create.

az role assignment create --role "Key Vault Secrets User" --assignee "<app-id>" --scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.KeyVault/vaults/<your-unique-keyvault-name>"

Als u uw toepassingsmachtigingen wilt verlenen aan uw sleutelkluis via op rollen gebaseerd toegangsbeheer (RBAC), wijst u een rol toe met behulp van de Azure PowerShell-cmdlet New-AzRoleAssignment.

New-AzRoleAssignment -ObjectId "<app-id>" -RoleDefinitionName "Key Vault Secrets User" -Scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.KeyVault/vaults/<your-unique-keyvault-name>"

Vervang , <subscription-id><resource-group-name> en <your-unique-keyvault-name> door <app-id>uw werkelijke waarden. <app-id> is de toepassings-id (client) van uw geregistreerde toepassing in Microsoft Entra.

Omgevingsvariabelen instellen

Deze toepassing gebruikt key vault-eindpunt als een omgevingsvariabele met de naam KEY_VAULT_URL.

set KEY_VAULT_URL=<your-key-vault-endpoint>

Windows PowerShell

$Env:KEY_VAULT_URL="<your-key-vault-endpoint>"

export KEY_VAULT_URL=<your-key-vault-endpoint>

Een client verifiëren en maken

Toepassingsaanvragen voor de meeste Azure-services moeten worden geautoriseerd. Het gebruik van de DefaultAzureCredential-methode die wordt geleverd door de Azure Identity-clientbibliotheek is de aanbevolen methode voor het implementeren van verbindingen zonder wachtwoord met Azure-services in uw code. DefaultAzureCredential ondersteunt meerdere verificatiemethoden en bepaalt welke methode tijdens runtime moet worden gebruikt. Met deze aanpak kan uw app verschillende verificatiemethoden gebruiken in verschillende omgevingen (lokaal versus productie) zonder omgevingsspecifieke code te implementeren.

In deze quickstart DefaultAzureCredential verifieert u zich bij de sleutelkluis met behulp van de referenties van de lokale ontwikkelgebruiker die is aangemeld bij de Azure CLI. Wanneer de toepassing in Azure wordt geïmplementeerd, kan dezelfde DefaultAzureCredential code automatisch een beheerde identiteit detecteren en gebruiken die is toegewezen aan een App Service, virtuele machine of andere services. Zie Overzicht van beheerde identiteiten voor meer informatie.

In deze code wordt het eindpunt van uw sleutelkluis gebruikt om de sleutelkluisclient te maken. De eindpuntindeling ziet eruit, https://<your-key-vault-name>.vault.azure.net maar kan veranderen voor onafhankelijke clouds. Zie Gids voor ontwikkelaars voor meer informatie over het verifiëren van een sleutelkluis.

Voorbeeld van code

Deze code maakt gebruik van de volgende Key Vault-certificaatklassen en -methoden:

Stel het app-framework in

Maak een nieuw tekstbestand en plak de volgende code in het bestand index.js .

const { CertificateClient, DefaultCertificatePolicy } = require("@azure/keyvault-certificates");
const { DefaultAzureCredential } = require("@azure/identity");

async function main() {
  // If you're using MSI, DefaultAzureCredential should "just work".
  // Otherwise, DefaultAzureCredential expects the following three environment variables:
  // - AZURE_TENANT_ID: The tenant ID in Azure Active Directory
  // - AZURE_CLIENT_ID: The application (client) ID registered in the AAD tenant
  // - AZURE_CLIENT_SECRET: The client secret for the registered application
  const credential = new DefaultAzureCredential();

  const keyVaultUrl = process.env["KEY_VAULT_URL"];
  if(!keyVaultUrl) throw new Error("KEY_VAULT_URL is empty");

  const client = new CertificateClient(keyVaultUrl, credential);

  const uniqueString = new Date().getTime();
  const certificateName = `cert${uniqueString}`;

  // Creating a self-signed certificate
  const createPoller = await client.beginCreateCertificate(
    certificateName,
    DefaultCertificatePolicy
  );

  const pendingCertificate = createPoller.getResult();
  console.log("Certificate: ", pendingCertificate);

  // To read a certificate with their policy:
  let certificateWithPolicy = await client.getCertificate(certificateName);
  // Note: It will always read the latest version of the certificate.

  console.log("Certificate with policy:", certificateWithPolicy);

  // To read a certificate from a specific version:
  const certificateFromVersion = await client.getCertificateVersion(
    certificateName,
    certificateWithPolicy.properties.version
  );
  // Note: It will not retrieve the certificate's policy.
  console.log("Certificate from a specific version:", certificateFromVersion);

  const updatedCertificate = await client.updateCertificateProperties(certificateName, "", {
    tags: {
      customTag: "value"
    }
  });
  console.log("Updated certificate:", updatedCertificate);

  // Updating the certificate's policy:
  await client.updateCertificatePolicy(certificateName, {
    issuerName: "Self",
    subject: "cn=MyOtherCert"
  });
  certificateWithPolicy = await client.getCertificate(certificateName);
  console.log("updatedCertificate certificate's policy:", certificateWithPolicy.policy);

  // delete certificate
  const deletePoller = await client.beginDeleteCertificate(certificateName);
  const deletedCertificate = await deletePoller.pollUntilDone();
  console.log("Recovery Id: ", deletedCertificate.recoveryId);
  console.log("Deleted Date: ", deletedCertificate.deletedOn);
  console.log("Scheduled Purge Date: ", deletedCertificate.scheduledPurgeDate);
}

main().catch((error) => {
  console.error("An error occurred:", error);
  process.exit(1);
});

De voorbeeldtoepassing uitvoeren

De app uitvoeren:
```
node index.js
```

De methoden voor maken en ophalen retourneren een volledig JSON-object voor het certificaat:

{
  "keyId": undefined,
  "secretId": undefined,
  "name": "YOUR-CERTIFICATE-NAME",
    "reuseKey": false,
    "keyCurveName": undefined,
    "exportable": true,
    "issuerName": 'Self',
    "certificateType": undefined,
    "certificateTransparency": undefined
  },
  "properties": {
    "createdOn": 2021-11-29T20:17:45.000Z,
    "updatedOn": 2021-11-29T20:17:45.000Z,
    "expiresOn": 2022-11-29T20:17:45.000Z,
    "id": "https://YOUR-KEY-VAULT-NAME-ENDPOINT/certificates/YOUR-CERTIFICATE-NAME/YOUR-CERTIFICATE-VERSION",
    "enabled": false,
    "notBefore": 2021-11-29T20:07:45.000Z,
    "recoveryLevel": "Recoverable+Purgeable",
    "name": "YOUR-CERTIFICATE-NAME",
    "vaultUrl": "https://YOUR-KEY-VAULT-NAME-ENDPOINT",
    "version": "YOUR-CERTIFICATE-VERSION",
    "tags": undefined,
    "x509Thumbprint": undefined,
    "recoverableDays": 90
  }
}

Maak een nieuw tekstbestand en plak de volgende code in het index.ts-bestand .

import {
  CertificateClient,
  DefaultCertificatePolicy,
  KeyVaultCertificate,
  DeletedCertificate,
  CertificatePolicy,
  KeyVaultCertificateWithPolicy,
} from "@azure/keyvault-certificates";
import { DefaultAzureCredential } from "@azure/identity";
import "dotenv/config";

const credential = new DefaultAzureCredential();

// Get Key Vault name from environment variables
// such as `https://${keyVaultName}.vault.azure.net`
const keyVaultUrl = process.env.KEY_VAULT_URL;
if (!keyVaultUrl) throw new Error("KEY_VAULT_URL is empty");

function printCertificate(
  certificate: KeyVaultCertificate | KeyVaultCertificateWithPolicy
): void {
  console.log("-- printCertificate ---------------------------");

  // if policy is defined, it's a KeyVaultCertificateWithPolicy
  if ((certificate as KeyVaultCertificateWithPolicy).policy) {
    const { name, properties, policy } =
      certificate as KeyVaultCertificateWithPolicy;
    const { createdOn, updatedOn, expiresOn, vaultUrl, version, tags } =
      properties;
    console.log("Certificate: ", {
      name,
      createdOn,
      updatedOn,
      expiresOn,
      vaultUrl,
      version,
    });
    console.log("Certificate Policy: ", policy);
    printObjectProperties(tags);
    return;
  } else {
    const { name, properties } = certificate;
    const { createdOn, updatedOn, expiresOn, vaultUrl, version, tags } =
      properties;
    console.log("Certificate: ", {
      name,
      createdOn,
      updatedOn,
      expiresOn,
      vaultUrl,
      version,
    });
    printObjectProperties(tags);
  }
}
// Object properties are tags and CertificatePolicy
function printObjectProperties(obj: Record<string, any>): void {
  if (!obj) return;

  console.log("-- printObjectProperties ---------------------------");

  Object.entries(obj).forEach(([key, value]) => {
    if (key === "lifetimeActions") {
      console.log(`${key}: ${JSON.stringify(value)}`);
    } else {
      console.log(`${key}: ${value}`);
    }
  });
}
function printDeletedCertificate(deletedCertificate: DeletedCertificate): void {
  const { recoveryId, deletedOn, scheduledPurgeDate } = deletedCertificate;
  console.log("Deleted Certificate: ", {
    recoveryId,
    deletedOn,
    scheduledPurgeDate,
  });
}
async function main(): Promise<void> {
  // Create a new CertificateClient
  const client = new CertificateClient(keyVaultUrl, credential);

  // Create a unique certificate name
  const uniqueString = new Date().getTime().toString();
  const certificateName = `cert${uniqueString}`;

  // Creating a self-signed certificate
  const createPoller = await client.beginCreateCertificate(
    certificateName,
    DefaultCertificatePolicy
  );

  // Get the created certificate
  const pendingCertificate = await createPoller.getResult();
  printCertificate(pendingCertificate);

  // Get certificate by name
  let certificateWithPolicy = await client.getCertificate(certificateName);
  printCertificate(pendingCertificate);

  // Get certificate by version
  const certificateFromVersion = await client.getCertificateVersion(
    certificateName,
    certificateWithPolicy.properties.version!
  );
  printCertificate(certificateFromVersion);

  // Update properties of the certificate
  const updatedCertificate = await client.updateCertificateProperties(
    certificateName,
    certificateWithPolicy.properties.version!,
    {
      tags: {
        customTag: "my value",
      },
    }
  );
  printCertificate(updatedCertificate);

  // Updating the certificate's policy
  const certificatePolicy = await client.updateCertificatePolicy(
    certificateName,
    {
      issuerName: "Self",
      subject: "cn=MyOtherCert",
    }
  );
  printObjectProperties(certificatePolicy);

  // Get certificate again to see the updated policy
  certificateWithPolicy = await client.getCertificate(certificateName);
  printCertificate(certificateWithPolicy);

  // Delete certificate
  const deletePoller = await client.beginDeleteCertificate(certificateName);
  const deletedCertificate = await deletePoller.pollUntilDone();
  printDeletedCertificate(deletedCertificate);
}

main().catch((error) => {
  console.error("An error occurred:", error);
  process.exit(1);
});

De voorbeeldtoepassing uitvoeren

Bouw de TypeScript-app:
```
tsc
```
De app uitvoeren:
```
node index.js
```

De methoden voor maken en ophalen retourneren een volledig JSON-object voor het certificaat:

{
  "keyId": undefined,
  "secretId": undefined,
  "name": "YOUR-CERTIFICATE-NAME",
    "reuseKey": false,
    "keyCurveName": undefined,
    "exportable": true,
    "issuerName": 'Self',
    "certificateType": undefined,
    "certificateTransparency": undefined
  },
  "properties": {
    "createdOn": 2021-11-29T20:17:45.000Z,
    "updatedOn": 2021-11-29T20:17:45.000Z,
    "expiresOn": 2022-11-29T20:17:45.000Z,
    "id": "https://YOUR-KEY-VAULT-NAME-ENDPOINT/certificates/YOUR-CERTIFICATE-NAME/YOUR-CERTIFICATE-VERSION",
    "enabled": false,
    "notBefore": 2021-11-29T20:07:45.000Z,
    "recoveryLevel": "Recoverable+Purgeable",
    "name": "YOUR-CERTIFICATE-NAME",
    "vaultUrl": "https://YOUR-KEY-VAULT-NAME-ENDPOINT",
    "version": "YOUR-CERTIFICATE-VERSION",
    "tags": undefined,
    "x509Thumbprint": undefined,
    "recoverableDays": 90
  }
}

Integreren met App Configuration

De Azure SDK biedt een helpermethode, parseKeyVaultCertificateIdentifier, om de opgegeven Key Vault-certificaat-id te parseren. Dit is nodig als u App Configuration-verwijzingen naar Key Vault gebruikt. In app-configuratie wordt de Key Vault-certificaat-id opgeslagen. U hebt de methode parseKeyVaultCertificateIdentifier nodig om die id te parseren om de certificaatnaam op te halen. Zodra u de certificaatnaam hebt, kunt u het huidige certificaat ophalen met behulp van code uit deze quickstart.

Volgende stappen

In deze quickstart hebt u een sleutelkluis gemaakt, een certificaat opgeslagen en dat certificaat opgehaald. Ga verder met deze artikelen voor meer informatie over Key Vault en hoe u deze integreert met uw toepassingen.

Lees een Overzicht van Azure Key Vault
Lees een Overzicht van certificaten
Zie een zelfstudie over toegang tot Key Vault vanuit een App Service-toepassing
Zie een zelfstudie over toegang tot Key Vault vanuit een virtuele machine
Zie de Gids voor Azure Key Vault-ontwikkelaars
Raadpleeg het Overzicht voor Key Vault-beveiliging

Share via

Quickstart: Azure Key Vault-certificaatclientbibliotheek voor JavaScript

Vereisten

Een nieuwe Node.js-toepassing maken

Key Vault-pakketten installeren

Toegang verlenen tot uw sleutelkluis

Omgevingsvariabelen instellen

Een client verifiëren en maken

Voorbeeld van code

Stel het app-framework in

De voorbeeldtoepassing uitvoeren

De voorbeeldtoepassing uitvoeren

Integreren met App Configuration

Volgende stappen

Feedback

Aanvullende resources

Share via

Quickstart: Azure Key Vault-certificaatclientbibliotheek voor JavaScript

Vereisten

Aanmelden bij Azure

Een nieuwe Node.js-toepassing maken

Key Vault-pakketten installeren

Toegang verlenen tot uw sleutelkluis

Omgevingsvariabelen instellen

Een client verifiëren en maken

Voorbeeld van code

Stel het app-framework in

De voorbeeldtoepassing uitvoeren

De voorbeeldtoepassing uitvoeren

Integreren met App Configuration

Volgende stappen

Feedback

Aanvullende resources