Share via

التشغيل السريع: مكتبة عميل شهادة Azure Key Vault ل JavaScript

  • مقالة

ابدأ مع مكتبة عميل شهادة Azure Key Vault لـ JavaScript. Azure Key Vault عبارة عن خدمة سحابية توفر مخزناً آمناً للشهادات. يمكنك تخزين المفاتيح وكلمات المرور والشهادات والأسرار الأخرى بأمان. يمكن إنشاء مخازن مفاتيح Azure وإدارتها من خلال مدخل Microsoft Azure. في هذا التشغيل السريع، ستتعلم كيفية إنشاء الشهادات واستردادها، وحذفها من مخزن مفاتيح Azure باستخدام مكتبة عميل JavaScript

موارد مكتبة عميل Key Vault:

حزمة التعليمات البرمجية | المصدر لمكتبة الوثائق المرجعية | لواجهة برمجة التطبيقات (npm)

لمزيد من المعلومات حول Key Vault والشهادات، راجع:

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

يفترض هذا التشغيل السريع أنك تقوم بتشغيل Azure CLI.

تسجيل الدخول إلى Azure

  1. تشغيل الأمر login.

    az login

    في حال كان CLI يمكن فتح المستعرض الافتراضي الخاص بك، فإنه سيتم القيام بذلك وتحميل صفحة تسجيل الدخول Azure.

    بخلاف ذلك، افتح صفحة متصفح على https://aka.ms/devicelogin وأدخل رمز التفويض المعروض في جهازك.

  2. قم بتسجيل الدخول باستخدام بيانات اعتماد حسابك في المتصفح.

قم بإنشاء تطبيق Node.js جديد

أنشئ تطبيق Node.js يستخدم مخزن المفاتيح الخاص بك.

  1. في terminal، أنشئ مجلد باسم key-vault-node-app، وقم بتغييره إلى ذلك المجلد:

    mkdir key-vault-node-app && cd key-vault-node-app

  2. تهيئة مشروع Node.js:

    npm init -y

قم بتثبيت حزم Key Vault

  1. باستخدام الـ terminal، قم بتثبيت مكتبة البيانات السرية لـ Azure Key Vault،azure/keyvault-certificates لـ Node.js.

    npm install @azure/keyvault-certificates

  2. قم بتثبيت مكتبة عميل Azure Identity، @azure/الهوية، للمصادقة على Key Vault.

    npm install @azure/identity

امنح حق الوصول إلى خزنة المفاتيح الخاصة بك

لمنح أذونات التطبيق إلى مخزن المفاتيح الخاص بك من خلال التحكم في الوصول استنادا إلى الدور (RBAC)، قم بتعيين دور باستخدام الأمر Azure CLI 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>"

استبدل <app-id> و <subscription-id> و <resource-group-name> و <your-unique-keyvault-name> بقيمك الفعلية. <معرف> التطبيق هو معرف التطبيق (العميل) للتطبيق المسجل في Azure AD.

تعيين متغيرات البيئة

يستخدم هذا التطبيق اسم key vault كمتغير بيئة يُسمى KEY_VAULT_NAME.

set KEY_VAULT_NAME=<your-key-vault-name>

مصادقة عميل وإنشاؤه

يجب التصريح بطلبات التطبيق إلى معظم خدمات Azure. يعد استخدام الأسلوب DefaultAzureCredential الذي توفره مكتبة عميل Azure Identity هو الأسلوب الموصى به لتنفيذ اتصالات بدون كلمة مرور بخدمات Azure في التعليمات البرمجية الخاصة بك. DefaultAzureCredential يدعم أساليب مصادقة متعددة ويحدد الأسلوب الذي يجب استخدامه في وقت التشغيل. يمكن هذا النهج تطبيقك من استخدام أساليب مصادقة مختلفة في بيئات مختلفة (البيئة المحلية مقابل بيئة التشغيل) دون تنفيذ التعليمات البرمجية الخاصة بالبيئة.

في هذا التشغيل السريع، DefaultAzureCredential يصادق على key vault باستخدام بيانات اعتماد مستخدم التطوير المحلي الذي سجل الدخول إلى Azure CLI. عند نشر التطبيق إلى Azure، يمكن لنفس DefaultAzureCredential التعليمات البرمجية اكتشاف واستخدام هوية مدارة تلقائيا تم تعيينها إلى App Service أو Virtual Machine أو خدمات أخرى. لمزيد من المعلومات، راجع نظرة عامة على الهوية المُدارة.

في هذه التعليمة البرمجية، يتم استخدام اسم مخزن المفاتيح الخاص بك لإنشاء URI لمخزن المفاتيح، بالتنسيق https://<your-key-vault-name>.vault.azure.net. لمزيد من المعلومات حول المصادقة إلى مخزن المفاتيح، راجع دليل المطور.

مثال على التعليمات البرمجية

تستخدم هذه التعليمة البرمجية فئات وأساليب شهادة Key Vault التالية:

إعداد إطار عمل التطبيق

  1. قم بإنشاء ملف نصي جديد والصق التعليمة البرمجية التالية في ملف 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 keyVaultName = process.env["KEY_VAULT_NAME"];
  if(!keyVaultName) throw new Error("KEY_VAULT_NAME is empty");
  const url = "https://" + keyVaultName + ".vault.azure.net";

  const client = new CertificateClient(url, 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);
});

تشغيل نموذج التطبيق

  1. تشغيل التطبيق:

    node index.js

  2. تقوم أساليب الإنشاء والحصول بإرجاع كائن JSON كامل للشهادة:

    {
  "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.vault.azure.net/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.vault.azure.net",
    "version": "YOUR-CERTIFICATE-VERSION",
    "tags": undefined,
    "x509Thumbprint": undefined,
    "recoverableDays": 90
  }
}

التكامل مع تكوين التطبيق

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

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

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