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

مقالة
10/05/2024

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

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

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

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

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

اشتراك Azure - إنشاء اشتراك مجاناً.
Node.js LTS الحالي.
Azure CLI
Key Vault موجود - يمكنك إنشاء واحد باستخدام:

اشتراك Azure - إنشاء اشتراك مجاناً.
Node.js LTS الحالي.
TypeScript 5+
Azure CLI.
Key Vault موجود - يمكنك إنشاء واحد باستخدام:

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

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

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

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

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

في terminal، أنشئ مجلد باسم key-vault-node-app، وقم بتغييره إلى ذلك المجلد:
```
mkdir key-vault-node-app && cd key-vault-node-app
```
تهيئة مشروع Node.js:
```
npm init -y
```

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

باستخدام المحطة الطرفية، قم بتثبيت مكتبة عميل أسرار Azure Key Vault، @azure/keyvault-keys ل Node.js.
```
npm install @azure/keyvault-keys
```
قم بتثبيت مكتبة عميل Azure Identity، @azure/حزمة الهوية للمصادقة على Key Vault.
```
npm install @azure/identity
```

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

للحصول على أذونات إلى مخزن المفاتيح الخاص بك من خلال التحكم في الوصول المستند إلى الدور (RBAC)، قم بتعيين دور إلى "اسم المستخدم الأساسي" (UPN) باستخدام الأمر Azure CLI az role assignment create.

az role assignment create --role "Key Vault Crypto Officer" --assignee "<upn>" --scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.KeyVault/vaults/<your-unique-keyvault-name>"

استبدل <upn>، <subscription-id>، <resource-group-name> و <your-unique-keyvault-name> بقيمك الفعلية. سيكون UPN الخاص بك عادة بتنسيق عنوان بريد إلكتروني (على سبيل المثال، username@domain.com).

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

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

set KEY_VAULT_URL=<your-key-vault-endpoint>

Windows PowerShell

$Env:KEY_VAULT_URL="<your-key-vault-endpoint>"

export KEY_VAULT_URL=<your-key-vault-endpoint>

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

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

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

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

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

سوف تُظهر لك نماذج التعليمات البرمجية أدناه كيفية إنشاء عميل وتعيين سر واسترداد سر وحذف سر.

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

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

قم بإنشاء ملف نصي جديد والصق التعليمة البرمجية التالية في ملف index.js.

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

async function main() {

    // 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 keyVaultUrl = process.env["KEY_VAULT_URL"];
    if(!keyVaultUrl) throw new Error("KEY_VAULT_URL is empty");

    const client = new KeyClient(keyVaultUrl, credential);

    const uniqueString = Date.now();
    const keyName = `sample-key-${uniqueString}`;
    const ecKeyName = `sample-ec-key-${uniqueString}`;
    const rsaKeyName = `sample-rsa-key-${uniqueString}`;

    // Create key using the general method
    const result = await client.createKey(keyName, "EC");
    console.log("key: ", result);

    // Create key using specialized key creation methods
    const ecResult = await client.createEcKey(ecKeyName, { curve: "P-256" });
    const rsaResult = await client.createRsaKey(rsaKeyName, { keySize: 2048 });
    console.log("Elliptic curve key: ", ecResult);
    console.log("RSA Key: ", rsaResult);

    // Get a specific key
    const key = await client.getKey(keyName);
    console.log("key: ", key);

    // Or list the keys we have
    for await (const keyProperties of client.listPropertiesOfKeys()) {
    const key = await client.getKey(keyProperties.name);
    console.log("key: ", key);
    }

    // Update the key
    const updatedKey = await client.updateKeyProperties(keyName, result.properties.version, {
    enabled: false
    });
    console.log("updated key: ", updatedKey);

    // Delete the key - the key is soft-deleted but not yet purged
    const deletePoller = await client.beginDeleteKey(keyName);
    await deletePoller.pollUntilDone();

    const deletedKey = await client.getDeletedKey(keyName);
    console.log("deleted key: ", deletedKey);

    // Purge the key - the key is permanently deleted
    // This operation could take some time to complete
    console.time("purge a single key");
    await client.purgeDeletedKey(keyName);
    console.timeEnd("purge a single key");
}

main().catch((error) => {
  console.error("An error occurred:", error);
  process.exit(1);
});

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

تشغيل التطبيق:
```
node index.js
```

يقوم أسلوبا create وget بإرجاع كائن JSON كامل للمفتاح:

"key":  {
  "key": {
    "kid": "https://YOUR-KEY-VAULT-ENDPOINT/keys/YOUR-KEY-NAME/YOUR-KEY-VERSION",
    "kty": "YOUR-KEY-TYPE",
    "keyOps": [ ARRAY-OF-VALID-OPERATIONS ],
    ... other properties based on key type
  },
  "id": "https://YOUR-KEY-VAULT-ENDPOINT/keys/YOUR-KEY-NAME/YOUR-KEY-VERSION",
  "name": "YOUR-KEY-NAME",
  "keyOperations": [ ARRAY-OF-VALID-OPERATIONS ],
  "keyType": "YOUR-KEY-TYPE",
  "properties": {
    "tags": undefined,
    "enabled": true,
    "notBefore": undefined,
    "expiresOn": undefined,
    "createdOn": 2021-11-29T18:29:11.000Z,
    "updatedOn": 2021-11-29T18:29:11.000Z,
    "recoverableDays": 90,
    "recoveryLevel": "Recoverable+Purgeable",
    "exportable": undefined,
    "releasePolicy": undefined,
    "vaultUrl": "https://YOUR-KEY-VAULT-ENDPOINT",
    "version": "YOUR-KEY-VERSION",
    "name": "YOUR-KEY-VAULT-NAME",
    "managed": undefined,
    "id": "https://YOUR-KEY-VAULT-ENDPOINT/keys/YOUR-KEY-NAME/YOUR-KEY-VERSION"
  }
}

إنشاء ملف نصي جديد ولصق التعليمات البرمجية التالية في ملف index.ts .

import {
  KeyClient,
  KeyVaultKey,
  KeyProperties,
  DeletedKey,
} from "@azure/keyvault-keys";
import { DefaultAzureCredential } from "@azure/identity";
import "dotenv/config";

const credential = new DefaultAzureCredential();

// Get Key Vault name from environment variables
// such as `https://${keyVaultName}.vault.azure.net`
const keyVaultUrl = process.env.KEY_VAULT_URL;
if (!keyVaultUrl) throw new Error("KEY_VAULT_URL is empty");

function printKey(keyVaultKey: KeyVaultKey): void {
  const { name, key, id, keyType, keyOperations, properties } = keyVaultKey;
  console.log("Key: ", { name, key, id, keyType });

  const { vaultUrl, version, enabled, expiresOn }: KeyProperties = properties;
  console.log("Key Properties: ", { vaultUrl, version, enabled, expiresOn });

  console.log("Key Operations: ", keyOperations.join(", "));
}

async function main(): Promise<void> {
  // Create a new KeyClient
  const client = new KeyClient(keyVaultUrl, credential);

  // Create unique key names
  const uniqueString = Date.now().toString();
  const keyName = `sample-key-${uniqueString}`;
  const ecKeyName = `sample-ec-key-${uniqueString}`;
  const rsaKeyName = `sample-rsa-key-${uniqueString}`;

  // Create a EC key
  const ecKey = await client.createKey(keyName, "EC");
  printKey(ecKey);

  // Elliptic curve key
  const ec256Key = await client.createEcKey(ecKeyName, {
    curve: "P-256",
  });
  printKey(ec256Key);

  // RSA key
  const rsa2048Key = await client.createRsaKey(rsaKeyName, {
    keySize: 2048,
  });
  printKey(rsa2048Key);

  // Get a key
  const key = await client.getKey(keyName);
  printKey(key);

  // Get properties of all keys
  for await (const keyProperties of client.listPropertiesOfKeys()) {
    const iteratedKey = await client.getKey(keyProperties.name);
    printKey(iteratedKey);
  }

  // Update key properties - disable key
  const updatedKey = await client.updateKeyProperties(
    keyName,
    ecKey.properties.version,
    {
      enabled: false,
    }
  );
  printKey(updatedKey);

  // Delete key (without immediate purge)
  const deletePoller = await client.beginDeleteKey(keyName);
  await deletePoller.pollUntilDone();

  // Get a deleted key
  const deletedKey = await client.getDeletedKey(keyName);
  console.log("deleted key: ", deletedKey.name);

  // Purge a deleted key
  console.time("purge a single key");
  await client.purgeDeletedKey(keyName);
  console.timeEnd("purge a single key");
}

main().catch((error) => {
  console.error("An error occurred:", error);
  process.exit(1);
});

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

إنشاء تطبيق TypeScript:
```
tsc
```
تشغيل التطبيق:
```
node index.js
```

يقوم أسلوبا create وget بإرجاع كائن JSON كامل للمفتاح:

"key":  {
  "key": {
    "kid": "https://YOUR-KEY-VAULT-ENDPOINT/keys/YOUR-KEY-NAME/YOUR-KEY-VERSION",
    "kty": "YOUR-KEY-TYPE",
    "keyOps": [ ARRAY-OF-VALID-OPERATIONS ],
    ... other properties based on key type
  },
  "id": "https://YOUR-KEY-VAULT-ENDPOINT/keys/YOUR-KEY-NAME/YOUR-KEY-VERSION",
  "name": "YOUR-KEY-NAME",
  "keyOperations": [ ARRAY-OF-VALID-OPERATIONS ],
  "keyType": "YOUR-KEY-TYPE",
  "properties": {
    "tags": undefined,
    "enabled": true,
    "notBefore": undefined,
    "expiresOn": undefined,
    "createdOn": 2021-11-29T18:29:11.000Z,
    "updatedOn": 2021-11-29T18:29:11.000Z,
    "recoverableDays": 90,
    "recoveryLevel": "Recoverable+Purgeable",
    "exportable": undefined,
    "releasePolicy": undefined,
    "vaultUrl": "https://YOUR-KEY-VAULT-ENDPOINT",
    "version": "YOUR-KEY-VERSION",
    "name": "YOUR-KEY-VAULT-NAME",
    "managed": undefined,
    "id": "https://YOUR-KEY-VAULT-ENDPOINT/keys/YOUR-KEY-NAME/YOUR-KEY-VERSION"
  }
}

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

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

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

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

اقرأ نظرة عامة على Azure Key Vault
اقرأ نظرة عامة على مفاتيح Azure Key Vault
كيفية الوصول الآمن إلى مخزن البيانات السرية
مراجعة دليل مطور Azure Key Vault
راجع نظرة عامة على أمان Key Vault

مشاركة عبر

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

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

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

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

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

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

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

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

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

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

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

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

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

الملاحظات

الموارد الإضافية

مشاركة عبر

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

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

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

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

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

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

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

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

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

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

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

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

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

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

الملاحظات

الموارد الإضافية