مكتبة عميل شهادات Azure Key Vault ل JavaScript - الإصدار 4.8.0
Azure Key Vault هي خدمة سحابية توفر تخزينا آمنا وإدارة تلقائية للشهادات المستخدمة في جميع أنحاء تطبيق السحابة. يمكن الاحتفاظ بشهادات متعددة وإصدارات متعددة من نفس الشهادة في Key Vault Azure. كل شهادة في المخزن لها نهج مقترن بها يتحكم في إصدار الشهادة وعمرها، بالإضافة إلى الإجراءات التي يجب اتخاذها كشهادات بالقرب من انتهاء الصلاحية.
إذا كنت ترغب في معرفة المزيد حول Azure Key Vault، فقد تحتاج إلى مراجعة: ما هو Azure Key Vault؟
استخدم مكتبة العميل لشهادات Azure Key Vault في تطبيق Node.js الخاص بك من أجل:
- الحصول على شهادة وتعيينها وحذفها.
- تحديث شهادة وسماتها ومصدرها ونهجها وتشغيلها وجهات الاتصال.
- النسخ الاحتياطي واستعادة الشهادة.
- الحصول على شهادة محذوفة أو إزالتها أو استردادها.
- احصل على جميع إصدارات الشهادة.
- احصل على جميع الشهادات.
- احصل على جميع الشهادات المحذوفة.
ملاحظة: لا يمكن استخدام هذه الحزمة في المستعرض بسبب قيود خدمة Azure Key Vault، يرجى الرجوع إلى هذا المستند للحصول على إرشادات.
الروابط الرئيسية:
الشروع في العمل
البيئات المعتمدة حاليًا
المتطلبات الأساسية
- اشتراك 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");
راجع دليل استكشاف الأخطاء وإصلاحها للحصول على تفاصيل حول كيفية تشخيص سيناريوهات الفشل المختلفة.
الخطوات التالية
يمكنك العثور على المزيد من نماذج التعليمات البرمجية من خلال الارتباطات التالية:
- نماذج شهادات Key Vault (JavaScript)
- نماذج شهادات Key Vault (TypeScript)
- Key Vault حالات اختبار الشهادات
المساهمة
إذا كنت ترغب في المساهمة في هذه المكتبة، يرجى قراءة دليل المساهمة لمعرفة المزيد حول كيفية إنشاء التعليمات البرمجية واختبارها.
Azure SDK for JavaScript