Azure Key Vault Certificates client library for JavaScript - version 4.10.3

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

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

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

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

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

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

الشروع

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

المتطلبات المسبقه

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

تثبيت الحزمة

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

npm install @azure/keyvault-certificates

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

يقوم عملاء Key Vault بالمصادقة باستخدام مكتبة Azure Identity. قم بتثبيته أيضا باستخدام 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، ورابط vault وكائن بيانات اعتماد. تستخدم الأمثلة الموضحة في هذا المستند كائن بيانات اعتماد يسمى DefaultAzureCredential، وهو مناسب لمعظم السيناريوهات، بما في ذلك بيئات التطوير والإنتاج المحلية. بالإضافة إلى ذلك، نوصي باستخدام هوية مدارة للمصادقة في بيئات الإنتاج.

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

فيما يلي مثال سريع. أولا، استيراد DefaultAzureCredentialCertificateClient. بمجرد استيرادها، يمكننا الاتصال بخدمة key vault:

import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@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);

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

  • عميل Certificates هو الواجهة الأساسية للتفاعل مع طرق واجهة برمجة التطبيقات المتعلقة بالشهادات في واجهة برمجة التطبيقات Azure Key Vault من تطبيق جافاسكريبت. بمجرد تهيئتها، يوفر مجموعة أساسية من الأساليب التي يمكن استخدامها لإنشاء الشهادات وقراءتها وتحديثها وحذفها.
  • إصدار Certificate هو نسخة من شهادة في Key Vault. في كل مرة يعين فيها مستخدم قيمة لاسم شهادة فريد، يتم إنشاء إصدار جديد من تلك الشهادة. دائما ما يؤدي استرداد شهادة باسم إلى إرجاع أحدث قيمة تم تعيينها، ما لم يتم توفير إصدار معين للاستعلام.
  • يسمح الحذف المبدئي ل Key Vaults بدعم الحذف والإزالة كخطوتين منفصلتين، لذلك لا يتم فقدان الشهادات المحذوفة على الفور. يحدث هذا فقط إذا كان Key Vault مفعل <حذف >soft-delete.
  • يمكن إنشاء النسخ الاحتياطي لشهادة من أي شهادة تم إنشاؤها. تأتي هذه النسخ الاحتياطية كبيانات ثنائية، ويمكن استخدامها فقط لإعادة إنشاء شهادة محذوفة مسبقا.

Specifying the Azure Key Vault service API version

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

import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@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.5",
});

امثله

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

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

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

import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@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.
await client.beginCreateCertificate(certificateName, {
  issuerName: "Self",
  subject: "cn=MyCert",
});

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

  • enabled: قيمة منطقية تحدد ما إذا كان يمكن استخدام الشهادة أم لا.
  • tags: أي مجموعة من قيم المفاتيح التي يمكن استخدامها للبحث عن الشهادات وتصفيتها.
import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@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",
};

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

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

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

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

import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@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",
};

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

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

import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@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",
};

const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

const poller = await client.beginCreateCertificate(certificateName, certificatePolicy);

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

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

الحصول على شهادة Key Vault

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

import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@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 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,
);

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

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

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

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

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@azure/keyvault-secrets";
import { writeFileSync } from "node:fs";

const credential = new DefaultAzureCredential();

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

const secretClient = new SecretClient(keyVaultUrl, credential);

const certificateName = "MyCertificateName";

// 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:
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 للشهادات والأسرار:

import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@azure/keyvault-certificates";
import { SecretClient } from "@azure/keyvault-secrets";

const credential = new DefaultAzureCredential();

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

const client = new CertificateClient(keyVaultUrl, credential);
const secretClient = new SecretClient(keyVaultUrl, credential);
// 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.
});
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.

import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@azure/keyvault-certificates";

const credential = new DefaultAzureCredential();

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

const client = new CertificateClient(keyVaultUrl, credential);

const certificateName = "MyCertificate";

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

تحديث شهادة

يمكن تحديث سمات الشهادة إلى إصدار شهادة موجود مع updateCertificate، كما يلي:

import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@azure/keyvault-certificates";

const credential = new DefaultAzureCredential();

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

const client = new CertificateClient(keyVaultUrl, credential);

const certificateName = "MyCertificate";

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

يمكن أيضا تحديث نهج الشهادة بشكل فردي باستخدام updateCertificatePolicy، كما يلي:

import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@azure/keyvault-certificates";

const credential = new DefaultAzureCredential();

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

const client = new CertificateClient(keyVaultUrl, credential);

const certificateName = "MyCertificate";

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

حذف شهادة

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

إذا تم تفعيل soft-delete على Key Vault، فإن هذه العملية ستصنف الشهادة فقط كشهادة deleted. لا يمكن تحديث شهادة محذوفة. يمكن قراءتها أو استردادها أو إزالتها فقط.

import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@azure/keyvault-certificates";

const credential = new DefaultAzureCredential();

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

const client = new CertificateClient(keyVaultUrl, credential);

const certificateName = "MyCertificate";

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

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

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

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

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

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

import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@azure/keyvault-certificates";

const credential = new DefaultAzureCredential();

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

const client = new CertificateClient(keyVaultUrl, credential);

const certificateName = "MyCertificate";

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

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

import { DefaultAzureCredential } from "@azure/identity";
import { CertificateClient } from "@azure/keyvault-certificates";

const credential = new DefaultAzureCredential();

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

const client = new CertificateClient(keyVaultUrl, credential);

const certificateName = "MyCertificate";

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

استكشاف الاخطاء

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

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

setLogLevel("info");

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

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

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

المساهمه

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