مشاركة عبر

مكتبة عميل Azure Key Vault السرية لجافا سكريبت - الإصدار 4.10.0

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

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

استخدم مكتبة العميل ل Azure Key Vault Secrets في تطبيق Node.js الخاص بك من أجل:

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

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

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

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

الشروع في العمل

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

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

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

تثبيت الحزمة

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

npm install @azure/keyvault-secrets

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

يصادق عملاء Key Vault باستخدام مكتبة هوية Azure. قم بتثبيته أيضا باستخدام npm

npm install @azure/identity

تكوين TypeScript

يحتاج مستخدمو TypeScript إلى تثبيت تعريفات نوع العقدة:

npm install @types/node

تحتاج أيضا إلى تمكين compilerOptions.allowSyntheticDefaultImports في tsconfig.json. لاحظ أنه إذا قمت بتمكين compilerOptions.esModuleInterop، يتم تمكين allowSyntheticDefaultImports بشكل افتراضي. راجع دليل خيارات المحول البرمجي TypeScript للحصول على مزيد من المعلومات.

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

  • عميل Secret هو الواجهة الأساسية للتفاعل مع أساليب واجهة برمجة التطبيقات المتعلقة بالبيانات السرية في Azure Key Vault API من تطبيق JavaScript. بمجرد تهيئتها، فإنها توفر مجموعة أساسية من الأساليب التي يمكن استخدامها لإنشاء الأسرار وقراءتها وتحديثها وحذفها.
  • إصدار Secret هو إصدار من سر في Key Vault. في كل مرة يعين فيها المستخدم قيمة لاسم سري فريد، يتم إنشاء إصدار جديد من هذا السر. سيؤدي استرداد سر باسم دائما إلى إرجاع أحدث قيمة تم تعيينها، ما لم يتم توفير إصدار معين للاستعلام.
  • يسمح الحذف المبدئي ل Key Vaults بدعم الحذف والإزالة كخطوتين منفصلتين، لذلك لا يتم فقدان الأسرار المحذوفة على الفور. يحدث هذا فقط إذا قام Key Vault تمكين الحذف المبدئي.
  • يمكن إنشاء النسخ الاحتياطي السري من أي بيانات سرية تم إنشاؤها. تأتي هذه النسخ الاحتياطية كبيانات ثنائية، ولا يمكن استخدامها إلا لإعادة إنشاء سر تم حذفه مسبقا.

المصادقة باستخدام Azure Active Directory

تعتمد خدمة Key Vault على Azure Active Directory لمصادقة الطلبات على واجهات برمجة التطبيقات الخاصة بها. توفر حزمة @azure/identity مجموعة متنوعة من أنواع بيانات الاعتماد التي يمكن للتطبيق الخاص بك استخدامها للقيام بذلك. يوفر README ل @azure/identity المزيد من التفاصيل والعينات لمساعدتك على البدء.

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

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

فيما يلي مثال سريع. أولا، استيراد DefaultAzureCredentialSecretClient. بمجرد استيرادها، يمكننا الاتصال بخدمة Key Vault بعد ذلك:

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

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 keys client and connect to the service
const client = new SecretClient(url, credential);

تحديد إصدار واجهة برمجة تطبيقات خدمة Azure Key Vault

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

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

const credential = new DefaultAzureCredential();

// Build the URL to reach your key vault
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 SecretClient(url, credential, {
  serviceVersion: "7.0", // Or 7.1
});

أمثلة

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

إنشاء سر وتعيينه

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

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

const credential = new DefaultAzureCredential();

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

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

const result = await client.setSecret(secretName, "MySecretValue");
console.log("result: ", result);

الحصول على سر

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

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

const credential = new DefaultAzureCredential();

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

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

const latestSecret = await client.getSecret(secretName);
console.log(`Latest version of the secret ${secretName}: `, latestSecret);

const specificSecret = await client.getSecret(secretName, {
  version: latestSecret.properties.version!,
});
console.log(
  `The secret ${secretName} at the version ${latestSecret.properties.version!}: `,
  specificSecret,
);

إنشاء الأسرار وتحديثها باستخدام السمات

يمكن أن يكون للبيانات السرية معلومات أكثر من اسمها وقيمتها. كما يمكن أن تتضمن السمات التالية:

  • tags: أي مجموعة من قيم المفاتيح التي يمكن استخدامها للبحث عن الأسرار وتصفيتها.
  • contentType: أي سلسلة يمكن استخدامها لمساعدة متلقي البيانات السرية على فهم كيفية استخدام القيمة السرية.
  • enabled: قيمة منطقية تحدد ما إذا كان يمكن قراءة القيمة السرية أم لا.
  • notBefore: تاريخ معين يمكن بعده استرداد القيمة السرية.
  • expiresOn: تاريخ معين لا يمكن بعده استرداد القيمة السرية.

يمكن إرسال كائن بهذه السمات كمعلمة ثالثة setSecret، مباشرة بعد اسم السر وقيمته، كما يلي:

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

const credential = new DefaultAzureCredential();

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

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

const result = await client.setSecret(secretName, "MySecretValue", {
  enabled: false,
});

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

يمكن أيضا تحديث السمات إلى إصدار سري موجود مع updateSecretProperties، كما يلي:

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

const credential = new DefaultAzureCredential();

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

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

const result = await client.getSecret(secretName);
await client.updateSecretProperties(secretName, result.properties.version, { enabled: false });

حذف سر

يبدأ أسلوب beginDeleteSecret في حذف البيانات السرية. ستحدث هذه العملية في الخلفية بمجرد توفر الموارد الضرورية.

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

const credential = new DefaultAzureCredential();

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

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

await client.beginDeleteSecret(secretName);

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

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

const credential = new DefaultAzureCredential();

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

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

const poller = await client.beginDeleteSecret(secretName);

// You can use the deleted secret immediately:
const deletedSecret = poller.getResult();

// The secret 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 secret this way:
await client.getDeletedSecret(secretName);

// Deleted secrets can also be recovered or purged.

// recoverDeletedSecret returns a poller, just like beginDeleteSecret.
const recoverPoller = await client.beginRecoverDeletedSecret(secretName);
await recoverPoller.pollUntilDone();

// And then, to purge the deleted secret:
await client.purgeDeletedSecret(secretName);

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

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

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

const credential = new DefaultAzureCredential();

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

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

const poller = await client.beginDeleteSecret(secretName);

// You can use the deleted secret immediately:
let deletedSecret = poller.getResult();

// Or you can wait until the secret finishes being deleted:
deletedSecret = await poller.pollUntilDone();
console.log(deletedSecret);

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

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

const credential = new DefaultAzureCredential();

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

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

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

const poller = await client.beginDeleteSecret(secretName);
while (!poller.isDone()) {
  await poller.poll();
  await delay(5000);
}

console.log(`The secret ${secretName} is fully deleted`);

تكرار قوائم الأسرار

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

  • سيقوم listPropertiesOfSecrets بإدراج جميع أسرارك غير المحذوفة حسب أسمائهم، فقط في أحدث إصداراتها.
  • سيقوم listDeletedSecrets بإدراج جميع أسرارك المحذوفة حسب أسمائهم، فقط في أحدث إصداراتها.
  • سيقوم listPropertiesOfSecretVersions بإدراج جميع إصدارات البيانات السرية استنادا إلى اسم سري.

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

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

const credential = new DefaultAzureCredential();

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

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

for await (const secretProperties of client.listPropertiesOfSecrets()) {
  console.log("Secret properties: ", secretProperties);
}

for await (const deletedSecret of client.listDeletedSecrets()) {
  console.log("Deleted secret: ", deletedSecret);
}

for await (const versionProperties of client.listPropertiesOfSecretVersions(secretName)) {
  console.log("Version properties: ", versionProperties);
}

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

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

const credential = new DefaultAzureCredential();

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

const client = new SecretClient(url, credential);

const secretName = "MySecretName";

for await (const page of client.listPropertiesOfSecrets().byPage()) {
  for (const secretProperties of page) {
    console.log("Secret properties: ", secretProperties);
  }
}
for await (const page of client.listDeletedSecrets().byPage()) {
  for (const deletedSecret of page) {
    console.log("Deleted secret: ", deletedSecret);
  }
}
for await (const page of client.listPropertiesOfSecretVersions(secretName).byPage()) {
  for (const versionProperties of page) {
    console.log("Version properties: ", versionProperties);
  }
}

استكشاف الأخطاء وإصلاحها

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

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

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

setLogLevel("info");

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

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

المساهمه

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

  • Last updated on