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

  • Cikk

Az Azure Key Vault egy felhőszolgáltatás, amely biztonságos tárolást és automatikus felügyeletet biztosít a felhőalkalmazások tanúsítványainak. Az Azure Key Vault több tanúsítványt és ugyanazon tanúsítvány több verzióját is megőrizheti. A tároló minden tanúsítványához tartozik egy szabályzat, amely szabályozza a tanúsítvány kiállítását és élettartamát, valamint a hamarosan lejáró tanúsítványokként végrehajtandó műveleteket.

Ha többet szeretne megtudni az Azure Key Vault-ról, tekintse át a következőt: Mi az az Azure Key Vault?

Használja az Azure Key Vault-tanúsítványok ügyfélkódtárát az Node.js alkalmazásban a következő célokra:

  • Tanúsítvány lekérése, beállítása és törlése.
  • Tanúsítvány, attribútumai, kiállítója, szabályzata, művelete és névjegyei frissítése.
  • Tanúsítvány biztonsági mentése és visszaállítása.
  • Törölt tanúsítvány lekérése, végleges törlése vagy helyreállítása.
  • A tanúsítvány összes verziójának lekérése.
  • Szerezze be az összes tanúsítványt.
  • Szerezze be az összes törölt tanúsítványt.

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

Az Azure Key Vault Certificates ügyfélkódtár telepítése az npm használatával

npm install @azure/keyvault-certificates

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.

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 CertificateClient 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 CertificateClient:

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

Miután importálta ezeket, a következő lépésben csatlakozhatunk a Key Vault szolgáltatáshoz:

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

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 certificates client and connect to the service
const client = new CertificateClient(url, credential);

Fő fogalmak

  • A Tanúsítványok ügyfél az elsődleges felület, amely egy JavaScript-alkalmazásból származó Azure Key Vault API-tanúsítványokhoz kapcsolódó API-metódusokkal kommunikál. Az inicializálást követően olyan egyszerű metóduskészletet biztosít, amellyel tanúsítványok hozhatók létre, olvashatók, frissíthetők és törölhetők.
  • A tanúsítványverzió a Key Vault tanúsítványának verziója. Minden alkalommal, amikor egy felhasználó egy értéket rendel egy egyedi tanúsítványnévhez, létrejön a tanúsítvány új verziója . A tanúsítvány 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 tanúsítványok nem vesznek el azonnal. Ez csak akkor fordul elő, ha a Key Vault engedélyezve van a helyreállítható törlés.
  • A tanúsítvány biztonsági mentése bármely létrehozott tanúsítványból létrehozható. Ezek a biztonsági másolatok bináris adatokként jönnek létre, és csak a korábban törölt tanúsítványok újragenerálásához használhatók.

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 { CertificateClient } = require("@azure/keyvault-certificates");

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 CertificateClient(url, credential, {
  serviceVersion: "7.0",
});

Példák

Az alábbi szakaszok olyan kódrészleteket nyújtanak, amelyek az Azure Key Vault-tanúsítványokat használó gyakori feladatok némelyikét ismertetik. Az itt tárgyalt forgatókönyvek a következőkből állnak:

Tanúsítvány létrehozása és beállítása

beginCreateCertificatelétrehoz egy tanúsítványt, amely az Azure Key Vault tárolandó. Ha már létezik ilyen nevű tanúsítvány, létrejön a tanúsítvány új verziója.

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

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new CertificateClient(url, credential);

const certificateName = "MyCertificateName";

async function main() {
  // Note: Sending `Self` as the `issuerName` of the certificate's policy will create a self-signed certificate.
  await client.beginCreateCertificate(certificateName, {
    issuerName: "Self",
    subject: "cn=MyCert",
  });
}

main();

A tanúsítvány és a szabályzat neve mellett a következő tulajdonságokat is átadhatja egy harmadik argumentumban opcionális értékekkel:

  • enabled: Logikai érték, amely meghatározza, hogy a tanúsítvány használható-e vagy sem.
  • tags: A tanúsítványok kereséséhez és szűréséhez használható kulcsértékek összes készlete.
const { DefaultAzureCredential } = require("@azure/identity");
const { CertificateClient } = require("@azure/keyvault-certificates");

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new CertificateClient(url, credential);

const certificateName = "MyCertificateName";

// Note: Sending `Self` as the `issuerName` of the certificate's policy will create a self-signed certificate.
const certificatePolicy = {
  issuerName: "Self",
  subject: "cn=MyCert",
};
const enabled = true;
const tags = {
  myCustomTag: "myCustomTagsValue",
};

async function main() {
  await client.beginCreateCertificate(certificateName, certificatePolicy, {
    enabled,
    tags,
  });
}

main();

Az azonos nevű hívás beginCreateCertificate ugyanannak a tanúsítványnak egy új verzióját hozza létre, amely a legújabb attribútumokkal rendelkezik.

Mivel a tanúsítványok létrehozása némi időt vesz igénybe, egy lekérdezési objektumot ad vissza, beginCreateCertificate 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 létrehozott tanúsítvány 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 tanúsítvány létrehozásához, vagy megvárja a folyamat befejezését:

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

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new CertificateClient(url, credential);

const certificateName = "MyCertificateName";
const certificatePolicy = {
  issuerName: "Self",
  subject: "cn=MyCert",
};

async function main() {
  const poller = await client.beginCreateCertificate(certificateName, certificatePolicy);

  // You can use the pending certificate immediately:
  const pendingCertificate = poller.getResult();

  // Or you can wait until the certificate finishes being signed:
  const keyVaultCertificate = await poller.pollUntilDone();
  console.log(keyVaultCertificate);
}

main();

A tanúsítvány aláírását úgy is megvárhatja, ha egyéni hívásokat végez, az alábbiak szerint:

const { DefaultAzureCredential } = require("@azure/identity");
const { CertificateClient } = require("@azure/keyvault-certificates");
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 CertificateClient(url, credential);

const certificateName = "MyCertificateName";
const certificatePolicy = {
  issuerName: "Self",
  subject: "cn=MyCert",
};

async function main() {
  const poller = await client.beginCreateCertificate(certificateName, certificatePolicy);

  while (!poller.isDone()) {
    await poller.poll();
    await delay(5000);
  }

  console.log(`The certificate ${certificateName} is fully created`);
}

main();

Key Vault tanúsítvány beszerzése

A tanúsítványok a tárolóból való visszaolvasásának legegyszerűbb módja a tanúsítvány név szerinti lekérése. getCertificate lekéri a tanúsítvány legújabb verzióját, valamint a tanúsítvány házirendjét. Ha megadja a verziót, meghívhatja a tanúsítvány getCertificateVersion egy másik verzióját is. getCertificateVersion nem adja vissza a tanúsítvány szabályzatát.

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

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new CertificateClient(url, credential);

const certificateName = "MyCertificateName";

async function main() {
  const latestCertificate = await client.getCertificate(certificateName);
  console.log(`Latest version of the certificate ${certificateName}: `, latestCertificate);
  const specificCertificate = await client.getCertificateVersion(
    certificateName,
    latestCertificate.properties.version
  );
  console.log(
    `The certificate ${certificateName} at the version ${latestCertificate.properties.version}: `,
    specificCertificate
  );
}

main();

Tanúsítvány teljes adatainak lekérése

Az Azure Key Vault kialakítása éles különbségeket tesz a kulcsok, a titkos kódok és a tanúsítványok között. A Key Vault szolgáltatás Tanúsítványfunkciói a Kulcsok és titkos kódok funkcióit használva lettek kialakítva. Értékeljük ki egy Key Vault tanúsítvány összetételét:

A Key Vault tanúsítvány létrehozásakor a rendszer egy címzhető kulcsot és titkos kulcsot is létrehoz ugyanazzal a névvel. A Key Vault kulcs lehetővé teszi a kulcsműveleteket, a Key Vault titkos kód pedig a tanúsítványérték titkos kulcsként való lekérését. A Key Vault tanúsítvány nyilvános x509-tanúsítvány metaadatokat is tartalmaz. Forrás: Tanúsítvány összetétele.

Tudva, hogy a titkos kulcs egy Key Vault Titkos kódban van tárolva, és a nyilvános tanúsítványt is tartalmazza, lekérhetjük a Key Vault Titkos kódok ügyfélalkalmazással.

// Using the same credential object we used before,
// and the same keyVaultUrl,
// let's create a SecretClient
import { SecretClient } from "@azure/keyvault-secrets";

const secretClient = new SecretClient(keyVaultUrl, credential);

// Assuming you've already created a Key Vault certificate,
// and that certificateName contains the name of your certificate
const certificateSecret = await secretClient.getSecret(certificateName);

// Here we can find both the private key and the public certificate, in PKCS 12 format:
const PKCS12Certificate = certificateSecret.value!;

// You can write this into a file:
fs.writeFileSync("myCertificate.p12", PKCS12Certificate);

Vegye figyelembe, hogy alapértelmezés szerint a tanúsítványok tartalomtípusa PKCS 12. A tanúsítvány tartalomtípusának megadásával PEM formátumban lekérheti. Mielőtt bemutatjuk, hogyan hozhat létre PEM-tanúsítványokat, először ismerkedjünk meg a PEM titkos kulcsának lekérése egy PKCS 12-tanúsítványból.

A használatával opensslpEM formátumban lekérheti a nyilvános tanúsítványt a következő paranccsal:

openssl pkcs12 -in myCertificate.p12 -out myCertificate.crt.pem -clcerts -nokeys

A titkos kulcs lekéréséhez az alábbiak szerint is használhatja openssl :

openssl pkcs12 -in myCertificate.p12 -out myCertificate.key.pem -nocerts -nodes

Vegye figyelembe, hogy az openssl mindkét esetben a tanúsítvány létrehozásához használt jelszót kéri. Az eddig használt mintakód nem adott meg jelszót, így az egyes parancsok végéhez hozzáfűzhetők -passin 'pass:' .

Tanúsítványok PEM formátumban

Ha PEM formátumú tanúsítványokkal szeretne dolgozni, az Azure Key Vault szolgáltatása PEM formátumban hozhatja létre és kezelheti a tanúsítványokat, ha megadja a contentType tulajdonságot a tanúsítványok létrehozásakor.

Az alábbi példa bemutatja, hogyan hozhatja létre és kérdezheti le egy PEM formátumú tanúsítvány nyilvános és privát részeit a tanúsítványok és titkos kódok Key Vault ügyfélalkalmazásával:

// Creating the certificate
const certificateName = "MyCertificate";
const createPoller = await client.beginCreateCertificate(certificateName, {
  issuerName: "Self",
  subject: "cn=MyCert",
  contentType: "application/x-pem-file", // Here you specify you want to work with PEM certificates.
});
const keyVaultCertificate = await createPoller.pollUntilDone();

// Getting the PEM formatted private key and public certificate:
const certificateSecret = await secretClient.getSecret(certificateName);
const PEMPair = certificateSecret.value!;

console.log(PEMPair);

Ne feledje, hogy a nyilvános tanúsítvány ugyanabban a tartalomblobban lesz, mint a titkos kulcs. A PEM-fejlécek használatával ennek megfelelően nyerheti ki őket.

Az összes tanúsítvány listázása

listPropertiesOfCertificateslistázni fogja az Key Vault összes tanúsítványát.

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

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new CertificateClient(url, credential);

async function main() {
  for await (let certificateProperties of client.listPropertiesOfCertificates()) {
    console.log("Certificate properties: ", certificateProperties);
  }
}

main();

Tanúsítvány frissítése

A tanúsítványattribútumok frissíthetők egy meglévő tanúsítványverzióra a következővel updateCertificate:

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

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new CertificateClient(url, credential);

const certificateName = "MyCertificateName";

async function main() {
  const result = await client.getCertificate(certificateName);
  await client.updateCertificateProperties(certificateName, result.properties.version, {
    enabled: false,
    tags: {
      myCustomTag: "myCustomTagsValue",
    },
  });
}

main();

A tanúsítvány szabályzata külön is frissíthető a következővel updateCertificatePolicy:

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

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new CertificateClient(url, credential);

const certificateName = "MyCertificateName";

async function main() {
  const result = client.getCertificate(certificateName);
  // Note: Sending `Self` as the `issuerName` of the certificate's policy will create a self-signed certificate.
  await client.updateCertificatePolicy(certificateName, {
    issuerName: "Self",
    subject: "cn=MyCert",
  });
}

main();

Tanúsítvány törlése

A beginDeleteCertificate metódus beállít egy tanúsítványt a törléshez. Ez a folyamat a háttérben történik, amint rendelkezésre állnak a szükséges erőforrások.

Ha a helyreállítható törlés engedélyezve van a Key Vault, ez a művelet csak törölt tanúsítványként címkézi fel a tanúsítványt. A törölt tanúsítványok nem frissíthetők. Ezek csak olvashatók, helyreállíthatók vagy törölhetők.

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

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new CertificateClient(url, credential);

const certificateName = "MyCertificateName";

async function main() {
  const poller = await client.beginDeleteCertificate(certificateName);

  // You can use the deleted certificate immediately:
  const deletedCertificate = poller.getResult();

  // The certificate 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 certificate this way:
  await client.getDeletedCertificate(certificateName);

  // Deleted certificates can also be recovered or purged.

  // recoverDeletedCertificate returns a poller, just like beginDeleteCertificate.
  // const recoverPoller = await client.beginRecoverDeletedCertificate(certificateName);
  // await recoverPoller.pollUntilDone();

  // If a certificate is done and the Key Vault has soft-delete enabled, the certificate can be purged with:
  await client.purgeDeletedCertificate(certificateName);
}

main();

Mivel a tanúsítvány törlése nem történik meg azonnal, a metódus meghívása után beginDeleteCertificate időre van szükség ahhoz, hogy a törölt tanúsítvány olvasható, helyreállítható vagy törölhető legyen.

Tanúsítványlisták iterálása

A CertificateClient használatával lekérheti és iterálhatja egy tanúsítványtároló összes tanúsítványát, valamint az összes törölt tanúsítványt és egy adott tanúsítvány verzióját. A következő API-metódusok érhetők el:

  • listPropertiesOfCertificates az összes nem törölt tanúsítványt listázni fogja a nevük alapján, csak a legújabb verziójukban.
  • listDeletedCertificates az összes törölt tanúsítványt listázni fogja a nevük alapján, csak a legújabb verziókban.
  • listPropertiesOfCertificateVersions a tanúsítvány összes verzióját felsorolja egy tanúsítványnév alapján.

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

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

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new CertificateClient(url, credential);

const certificateName = "MyCertificateName";

async function main() {
  for await (let certificateProperties of client.listPropertiesOfCertificates()) {
    console.log("Certificate properties: ", certificateProperties);
  }
  for await (let deletedCertificate of client.listDeletedCertificates()) {
    console.log("Deleted certificate: ", deletedCertificate);
  }
  for await (let certificateProperties of client.listPropertiesOfCertificateVersions(
    certificateName
  )) {
    console.log("Certificate properties: ", certificateProperties);
  }
}

main();

A metódusok mindegyike egyszerre adja vissza 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:

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

const credential = new DefaultAzureCredential();

const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;

const client = new CertificateClient(url, credential);

const certificateName = "MyCertificateName";

async function main() {
  for await (let page of client.listPropertiesOfCertificates().byPage()) {
    for (let certificateProperties of page) {
      console.log("Certificate properties: ", certificateProperties);
    }
  }
  for await (let page of client.listDeletedCertificates().byPage()) {
    for (let deletedCertificate of page) {
      console.log("Deleted certificate: ", deletedCertificate);
    }
  }
  for await (let page of client.listPropertiesOfCertificateVersions(certificateName).byPage()) {
    for (let certificateProperties of page) {
      console.log("Properties of certificate: ", certificateProperties);
    }
  }
}

main();

Hibaelhárítás

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 értékre info. A naplózás futásidőben is engedélyezhető a következő hívással setLogLevel@azure/logger:

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

setLogLevel("info");

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 .

Következő lépések

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

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 összeállításáról és teszteléséről.

Megjelenések