Azure Key Vault Secret client library for JavaScript - version 4.11.2

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

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

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

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

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

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

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

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

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

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

تثبيت الحزمة

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

npm install @azure/keyvault-secrets

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

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

npm install @azure/identity

تكوين TypeScript

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

npm install @types/node

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

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

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

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

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

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

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

فيما يلي مثال سريع. أولا، استيراد 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 secrets client and connect to the service
const client = new SecretClient(url, credential);

بالنسبة لبيئات المستعرض، استخدم InteractiveBrowserCredential من حزمة @azure/identity للمصادقة.

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

const credential = new InteractiveBrowserCredential({
  tenantId: "<YOUR_TENANT_ID>",
  clientId: "<YOUR_CLIENT_ID>",
});
const vaultName = "<YOUR KEYVAULT NAME>";
const url = `https://${vaultName}.vault.azure.net`;
const client = new SecretClient(url, credential);

Specifying the Azure Key Vault service API version

افتراضيا، تستخدم هذه الحزمة أحدث إصدار خدمة 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 Secrets. تتكون السيناريوهات التي يتم تناولها هنا من:

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

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);

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

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");

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

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

المساهمه

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

  • Last updated on