مكتبة عميل شهادات Azure Key Vault ل JavaScript - الإصدار 4.8.0

مقالة
02/16/2024

Azure Key Vault هي خدمة سحابية توفر تخزينا آمنا وإدارة تلقائية للشهادات المستخدمة في جميع أنحاء تطبيق السحابة. يمكن الاحتفاظ بشهادات متعددة وإصدارات متعددة من نفس الشهادة في Key Vault Azure. كل شهادة في المخزن لها نهج مقترن بها يتحكم في إصدار الشهادة وعمرها، بالإضافة إلى الإجراءات التي يجب اتخاذها كشهادات بالقرب من انتهاء الصلاحية.

إذا كنت ترغب في معرفة المزيد حول Azure Key Vault، فقد تحتاج إلى مراجعة: ما هو Azure Key Vault؟

استخدم مكتبة العميل لشهادات Azure Key Vault في تطبيق Node.js الخاص بك من أجل:

الحصول على شهادة وتعيينها وحذفها.
تحديث شهادة وسماتها ومصدرها ونهجها وتشغيلها وجهات الاتصال.
النسخ الاحتياطي واستعادة الشهادة.
الحصول على شهادة محذوفة أو إزالتها أو استردادها.
احصل على جميع إصدارات الشهادة.
احصل على جميع الشهادات.
احصل على جميع الشهادات المحذوفة.

ملاحظة: لا يمكن استخدام هذه الحزمة في المستعرض بسبب قيود خدمة Azure Key Vault، يرجى الرجوع إلى هذا المستند للحصول على إرشادات.

الروابط الرئيسية:

الشروع في العمل

البيئات المعتمدة حاليًا

إصدارات "LTS" من "Node.js".

المتطلبات الأساسية

اشتراك Azure
Key Vault Azure موجود. إذا كنت بحاجة إلى إنشاء مخزن مفاتيح، يمكنك القيام بذلك في مدخل Microsoft Azure باتباع الخطوات الواردة في هذا المستند. بدلا من ذلك، استخدم Azure CLI باتباع هذه الخطوات.

تثبيت الحِزَمة

تثبيت مكتبة عميل Azure Key Vault Certificates باستخدام npm

npm install @azure/keyvault-certificates

تثبيت مكتبة الهوية

Key Vault العملاء المصادقة باستخدام مكتبة هوية Azure. قم بتثبيته أيضا باستخدام npm

npm install @azure/identity

تكوين TypeScript

يحتاج مستخدمو TypeScript إلى تثبيت تعريفات نوع العقدة:

npm install @types/node

تحتاج أيضا إلى التمكين compilerOptions.allowSyntheticDefaultImports في tsconfig.json. لاحظ أنه إذا قمت بتمكين compilerOptions.esModuleInterop، allowSyntheticDefaultImports يتم تمكينه بشكل افتراضي. راجع دليل خيارات المحول البرمجي ل TypeScript للحصول على مزيد من المعلومات.

المصادقة باستخدام Azure Active Directory

تعتمد خدمة Key Vault على Azure Active Directory لمصادقة الطلبات على واجهات برمجة التطبيقات الخاصة بها. @azure/identity توفر الحزمة مجموعة متنوعة من أنواع بيانات الاعتماد التي يمكن للتطبيق الخاص بك استخدامها للقيام بذلك. يوفر README لمزيد @azure/identity من التفاصيل والعينات لبدء الاستخدام.

للتفاعل مع خدمة Azure Key Vault، ستحتاج إلى إنشاء مثيل للفئة CertificateClient وعنوان url للمخزن وعنصر بيانات اعتماد. تستخدم الأمثلة الموضحة في هذا المستند كائن بيانات اعتماد يسمى DefaultAzureCredential، وهو مناسب لمعظم السيناريوهات، بما في ذلك بيئات التطوير والإنتاج المحلية. بالإضافة إلى ذلك، نوصي باستخدام هوية مدارة للمصادقة في بيئات الإنتاج.

يمكنك العثور على مزيد من المعلومات حول الطرق المختلفة للمصادقة وأنواع بيانات الاعتماد المقابلة لها في وثائق Azure Identity.

فيما يلي مثال سريع. أولا، استيراد DefaultAzureCredential و CertificateClient:

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

بمجرد استيرادها، يمكننا الاتصال بعد ذلك بخدمة key vault:

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

المفاهيم الرئيسية

عميل الشهادات هو الواجهة الأساسية للتفاعل مع أساليب واجهة برمجة التطبيقات المتعلقة بالشهادات في Azure Key Vault API من تطبيق JavaScript. بمجرد تهيئتها، فإنها توفر مجموعة أساسية من الأساليب التي يمكن استخدامها لإنشاء الشهادات وقراءتها وتحديثها وحذفها.
إصدار الشهادة هو إصدار من شهادة في Key Vault. في كل مرة يعين فيها المستخدم قيمة لاسم شهادة فريد، يتم إنشاء إصدار جديد من تلك الشهادة. سيؤدي استرداد شهادة بالاسم دائما إلى إرجاع أحدث قيمة تم تعيينها، ما لم يتم توفير إصدار معين للاستعلام.
يسمح الحذف المبدئي ل Key Vaults بدعم الحذف والإزالة كخطوتين منفصلتين، لذلك لا يتم فقدان الشهادات المحذوفة على الفور. يحدث هذا فقط إذا تم تمكين الحذف المبدئي Key Vault.
يمكن إنشاء نسخة احتياطية للشهادة من أي شهادة تم إنشاؤها. تأتي هذه النسخ الاحتياطية كبيانات ثنائية، ولا يمكن استخدامها إلا لإعادة إنشاء شهادة محذوفة مسبقا.

تحديد إصدار واجهة برمجة تطبيقات خدمة Azure Key Vault

بشكل افتراضي، تستخدم هذه الحزمة أحدث إصدار من خدمة Azure Key Vault وهو 7.1. الإصدار الآخر الوحيد المدعوم هو 7.0. يمكنك تغيير إصدار الخدمة المستخدم عن طريق تعيين الخيار serviceVersion في منشئ العميل كما هو موضح أدناه:

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

أمثلة

توفر الأقسام التالية قصاصات برمجية تغطي بعض المهام الشائعة باستخدام شهادات Key Vault Azure. تتكون السيناريوهات التي تتم تغطيتها هنا من:

إنشاء شهادة وتعيينها.
الحصول على شهادة Key Vault.
الحصول على المعلومات الكاملة للشهادة.
الشهادات بتنسيق PEM.
سرد جميع الشهادات.
تحديث شهادة.
حذف شهادة.
تكرار قوائم الشهادات.

إنشاء شهادة وتعيينها

beginCreateCertificateينشئ شهادة ليتم تخزينها في Key Vault Azure. إذا كانت هناك شهادة بنفس الاسم موجودة بالفعل، يتم إنشاء إصدار جديد من الشهادة.

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

بالإضافة إلى اسم الشهادة والنهج، يمكنك أيضا تمرير الخصائص التالية في وسيطة ثالثة بقيم اختيارية:

enabled: قيمة منطقية تحدد ما إذا كان يمكن استخدام الشهادة أم لا.
tags: أي مجموعة من قيم المفاتيح التي يمكن استخدامها للبحث عن الشهادات وتصفيتها.

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

سيؤدي الاتصال بنفس الاسم إلى beginCreateCertificate إنشاء إصدار جديد من نفس الشهادة، والتي سيكون لها أحدث السمات المقدمة.

نظرا لأن الشهادات تستغرق بعض الوقت لإنشاءها بالكامل، beginCreateCertificate فترجع عنصر الاستقصاء الذي يتعقب عملية التشغيل الطويل الأساسية وفقا لإرشاداتنا: https://azure.github.io/azure-sdk/typescript_design.html#ts-lro

سيسمح لك الاستقصاء المستلم بالحصول على الشهادة التي تم إنشاؤها عن طريق الاتصال ب poller.getResult(). يمكنك أيضا الانتظار حتى ينتهي الحذف، إما عن طريق تشغيل استدعاءات الخدمة الفردية حتى يتم إنشاء الشهادة، أو بالانتظار حتى تنتهي العملية:

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

هناك طريقة أخرى للانتظار حتى يتم توقيع الشهادة وهي إجراء مكالمات فردية، كما يلي:

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

أبسط طريقة لقراءة الشهادات مرة أخرى من المخزن هي الحصول على شهادة بالاسم. getCertificate سيسترد أحدث إصدار من الشهادة، جنبا إلى جنب مع نهج الشهادة. يمكنك اختياريا الحصول على إصدار مختلف من الشهادة عن طريق الاتصال getCertificateVersion إذا قمت بتحديد الإصدار. getCertificateVersion لا يرجع نهج الشهادة.

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

الحصول على المعلومات الكاملة لشهادة

يميز تصميم Azure Key Vault بشكل حاد بين المفاتيح والأسرار والشهادات. تم تصميم ميزات شهادات خدمة Key Vault للاستفادة من قدرات المفاتيح والأسرار. دعونا نقيم تكوين شهادة Key Vault:

عند إنشاء شهادة "مفتاح Vault"، يتم أيضاً إنشاء مفتاح وبيانات سرية قابلين للعنونة بنفس الاسم. يسمح مفتاح Key Vault بالعمليات الرئيسية ويسمح مفتاح Key Vault باسترداد قيمة الشهادة كونها بيانات سرية. تحتوي شهادة Key Vault أيضاً على بيانات تعريف عامة لشهادة x509. المصدر: تكوين شهادة.

مع العلم أن المفتاح الخاص مخزن في Key Vault Secret، مع تضمين الشهادة العامة، يمكننا استرداده باستخدام عميل Key Vault Secrets.

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

لاحظ أن نوع محتوى الشهادات هو PKCS 12 بشكل افتراضي. من خلال تحديد نوع محتوى شهادتك، ستتمكن من استردادها بتنسيق PEM. قبل إظهار كيفية إنشاء شهادات PEM، دعنا أولا نستكشف كيفية استرداد مفتاح سر PEM من شهادة PKCS 12 أولا.

باستخدام openssl، يمكنك استرداد الشهادة العامة بتنسيق PEM باستخدام الأمر التالي:

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

يمكنك أيضا استخدام openssl لاسترداد المفتاح الخاص، كما يلي:

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

لاحظ أنه في كلتا الحالتين، سيطلب منك openssl كلمة المرور المستخدمة لإنشاء الشهادة. لم تحدد عينة التعليمات البرمجية التي استخدمناها حتى الآن كلمة مرور، حتى تتمكن من إلحاق -passin 'pass:' نهاية كل أمر.

الشهادات بتنسيق PEM

إذا كنت ترغب في العمل مع الشهادات بتنسيق PEM، يمكنك إخبار خدمة Key Vault Azure بإنشاء شهاداتك وإدارتها بتنسيق PEM من خلال توفير contentType الخاصية في لحظة إنشاء الشهادات.

يوضح المثال التالي كيفية إنشاء واسترداد الأجزاء العامة والخاصة من شهادة بتنسيق PEM باستخدام عملاء Key Vault للشهادات والأسرار:

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

ضع في اعتبارك أن شهادتك العامة ستكون في نفس الكائن الثنائي كبير الحجم للمحتوى مثل مفتاحك الخاص. يمكنك استخدام رؤوس PEM لاستخراجها وفقا لذلك.

سرد جميع الشهادات

listPropertiesOfCertificatesسيسرد جميع الشهادات في Key Vault.

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

تحديث شهادة

يمكن تحديث سمات الشهادة إلى إصدار شهادة موجود باستخدام 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();

يمكن أيضا تحديث نهج الشهادة بشكل فردي باستخدام 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();

حذف شهادة

يقوم beginDeleteCertificate الأسلوب بإعداد شهادة للحذف. ستحدث هذه العملية في الخلفية بمجرد توفر الموارد الضرورية.

إذا تم تمكين الحذف المبدئي Key Vault، فستسمي هذه العملية الشهادة فقط كشهادة محذوفة. لا يمكن تحديث شهادة محذوفة. يمكن قراءتها أو استردادها أو إزالتها فقط.

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

نظرا لأن حذف الشهادة لن يحدث على الفور، فإن هناك حاجة إلى بعض الوقت بعد beginDeleteCertificate استدعاء الأسلوب قبل أن تتوفر الشهادة المحذوفة للقراءة أو الاسترداد أو إزالتها.

تكرار قوائم الشهادات

باستخدام CertificateClient، يمكنك استرداد وتكرار جميع الشهادات في مخزن الشهادات، وكذلك من خلال جميع الشهادات المحذوفة وإصدارات شهادة معينة. تتوفر أساليب واجهة برمجة التطبيقات التالية:

listPropertiesOfCertificates سيدرج جميع الشهادات غير المحذوفة حسب أسمائها، فقط في أحدث إصداراتها.
listDeletedCertificates سيدرج جميع الشهادات المحذوفة حسب أسمائها، فقط في أحدث إصداراتها.
listPropertiesOfCertificateVersions سيسرد جميع إصدارات الشهادة استنادا إلى اسم الشهادة.

والتي يمكن استخدامها على النحو التالي:

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

سترجع جميع هذه الأساليب جميع النتائج المتاحة في وقت واحد. لاستردادها حسب الصفحات، أضف .byPage() مباشرة بعد استدعاء أسلوب واجهة برمجة التطبيقات الذي تريد استخدامه، كما يلي:

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

استكشاف الأخطاء وإصلاحها

قد يساعد تمكين التسجيل في الكشف عن معلومات مفيدة حول حالات الفشل. للاطلاع على سجل لطلبات HTTP واستجاباته، قم بتعيين AZURE_LOG_LEVELمتغير البيئة إلى info. بدلًا من ذلك، يمكن تمكين التسجيل في وقت التشغيل عن طريق الاتصال setLogLevelبـ @azure/logger:

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

setLogLevel("info");

راجع دليل استكشاف الأخطاء وإصلاحها للحصول على تفاصيل حول كيفية تشخيص سيناريوهات الفشل المختلفة.

الخطوات التالية

يمكنك العثور على المزيد من نماذج التعليمات البرمجية من خلال الارتباطات التالية:

المساهمة

إذا كنت ترغب في المساهمة في هذه المكتبة، يرجى قراءة دليل المساهمة لمعرفة المزيد حول كيفية إنشاء التعليمات البرمجية واختبارها.

مرات الظهور

مشاركة عبر