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

مقالة
11/02/2024

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

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

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

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

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

اشتراك Azure - إنشاء اشتراك مجاناً.
Node.js LTS الحالي.
Azure CLI

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

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

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

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

استخدم الأمر az group create لإنشاء مجموعة موارد:
```
az group create --name myResourceGroup --location eastus
```
يمكنك تغيير "إيستوس" إلى موقع قريب منك، إذا كنت تفضل ذلك.
استخدم az keyvault create لإنشاء خزنة المفاتيح:
```
az keyvault create --name <your-unique-keyvault-name> --resource-group myResourceGroup
```
استبدل <your-unique-keyvault-name> باسم فريد عبر Azure بالكامل. عادة ما تستخدم اسمك الشخصي أو اسم الشركة مع أرقام ومعرفات أخرى.

استخدم الأمر New-AzResourceGroup لإنشاء مجموعة موارد:
```
New-AzResourceGroup -Name myResourceGroup -Location eastus
```
يمكنك تغيير "إيستوس" إلى موقع قريب منك، إذا كنت تفضل ذلك.
استخدم New-AzKeyVault لإنشاء خزنة المفاتيح:
```
New-AzKeyVault -Name <your-unique-keyvault-name> -ResourceGroupName myResourceGroup -Location eastus
```
استبدل <your-unique-keyvault-name> باسم فريد عبر Azure بالكامل. عادة ما تستخدم اسمك الشخصي أو اسم الشركة مع أرقام ومعرفات أخرى.

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

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

az role assignment create --role "Key Vault Secrets 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).

قم بإنشاء تطبيق 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-secrets Node.js.
```
npm install @azure/keyvault-secrets
```
قم بتثبيت مكتبة عميل Azure Identity، @azure/حزمة الهوية للمصادقة على Key Vault.
```
npm install @azure/identity
```

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

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

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

يستخدم هذا التطبيق نقطة نهاية 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 { SecretClient } = require("@azure/keyvault-secrets");
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 keyVaultUrl = process.env["KEY_VAULT_URL"];
  if(!keyVaultUrl) throw new Error("KEY_VAULT_URL is empty");

  const client = new SecretClient(keyVaultUrl, credential);

  // Create a secret
  // The secret can be a string of any kind. For example,
  // a multiline text block such as an RSA private key with newline characters,
  // or a stringified JSON object, like `JSON.stringify({ mySecret: 'MySecretValue'})`.
  const uniqueString = new Date().getTime();
  const secretName = `secret${uniqueString}`;
  const result = await client.setSecret(secretName, "MySecretValue");
  console.log("result: ", result);

  // Read the secret we created
  const secret = await client.getSecret(secretName);
  console.log("secret: ", secret);

  // Update the secret with different attributes
  const updatedSecret = await client.updateSecretProperties(secretName, result.properties.version, {
    enabled: false
  });
  console.log("updated secret: ", updatedSecret);

  // Delete the secret immediately without ability to restore or purge.
  await client.beginDeleteSecret(secretName);
}

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

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

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

تقوم أساليب الإنشاء والحصول بإرجاع عنصر JSON كامل للبيان السري:

{
    "value": "MySecretValue",
    "name": "secret1637692472606",
    "properties": {
        "createdOn": "2021-11-23T18:34:33.000Z",
        "updatedOn": "2021-11-23T18:34:33.000Z",
        "enabled": true,
        "recoverableDays": 90,
        "recoveryLevel": "Recoverable+Purgeable",
        "id": "https: //YOUR-KEYVAULT-ENDPOINT.vault.azure.net/secrets/secret1637692472606/YOUR-VERSION",
        "vaultUrl": "https: //YOUR-KEYVAULT-ENDPOINT.vault.azure.net",
        "version": "YOUR-VERSION",
        "name": "secret1637692472606"
    }
}

يُرجع أسلوب التحديث أزواج أسماء/قيم الخصائص:

"createdOn": "2021-11-23T18:34:33.000Z",
"updatedOn": "2021-11-23T18:34:33.000Z",
"enabled": true,
"recoverableDays": 90,
"recoveryLevel": "Recoverable+Purgeable",
"id": "https: //YOUR-KEYVAULT-ENDPOINT/secrets/secret1637692472606/YOUR-VERSION",
"vaultUrl": "https: //YOUR-KEYVAULT-ENDPOINT",
"version": "YOUR-VERSION",
"name": "secret1637692472606"

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

import {
  SecretClient,
  KeyVaultSecret,
  SecretProperties,
} from "@azure/keyvault-secrets";
import { DefaultAzureCredential } from "@azure/identity";
import "dotenv/config";

// Passwordless credential
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 printSecret(secret: KeyVaultSecret): void {
  const { name, value, properties } = secret;
  const { enabled, expiresOn, createdOn } = properties;
  console.log("Secret: ", { name, value, enabled, expiresOn, createdOn });
}
function printSecretProperties(secret: SecretProperties): void {
  const { name, enabled, expiresOn, createdOn } = secret;
  console.log("Secret: ", { name, enabled, expiresOn, createdOn });
}

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

  // Create a unique secret name
  const uniqueString = new Date().getTime().toString();
  const secretName = `secret${uniqueString}`;

  // Create a secret
  const createSecretResult = await client.setSecret(
    secretName,
    "MySecretValue"
  );
  printSecret(createSecretResult);

  // Get the secret by name
  const getSecretResult = await client.getSecret(secretName);
  printSecret(getSecretResult);

  // Update properties
  const updatedSecret = await client.updateSecretProperties(
    secretName,
    getSecretResult.properties.version,
    {
      enabled: false,
    }
  );
  printSecretProperties(updatedSecret);

  // Delete secret (without immediate purge)
  const deletePoller = await client.beginDeleteSecret(secretName);
  await deletePoller.pollUntilDone();
}

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

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

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

تقوم أساليب الإنشاء والحصول بإرجاع عنصر JSON كامل للبيان السري:

{
    "value": "MySecretValue",
    "name": "secret1637692472606",
    "properties": {
        "createdOn": "2021-11-23T18:34:33.000Z",
        "updatedOn": "2021-11-23T18:34:33.000Z",
        "enabled": true,
        "recoverableDays": 90,
        "recoveryLevel": "Recoverable+Purgeable",
        "id": "https: //YOUR-KEYVAULT-ENDPOINT.vault.azure.net/secrets/secret1637692472606/YOUR-VERSION",
        "vaultUrl": "https: //YOUR-KEYVAULT-ENDPOINT.vault.azure.net",
        "version": "YOUR-VERSION",
        "name": "secret1637692472606"
    }
}

يُرجع أسلوب التحديث أزواج أسماء/قيم الخصائص:

"createdOn": "2021-11-23T18:34:33.000Z",
"updatedOn": "2021-11-23T18:34:33.000Z",
"enabled": true,
"recoverableDays": 90,
"recoveryLevel": "Recoverable+Purgeable",
"id": "https: //YOUR-KEYVAULT-ENDPOINT/secrets/secret1637692472606/YOUR-VERSION",
"vaultUrl": "https: //YOUR-KEYVAULT-ENDPOINT",
"version": "YOUR-VERSION",
"name": "secret1637692472606"

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

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

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

في هذا التشغيل السريع، قمت بإنشاء خزانة مفتاح، وتخزين سر، واسترجاع هذا السر. لمعرفة المزيد حول 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

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

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

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

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

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

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

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

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

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

الملاحظات

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