إنشاء رمز SAS المميز لتفويض المستخدمين باستخدام Azure Blob Storage وJavaScript

توضح هذه المقالة كيفية إنشاء رمز SAS المميز لتفويض المستخدمين في مكتبة عميل Azure Blob Storage v12 لـ JavaScript. يتم تأمين SAS لتفويض المستخدم، الذي تم تقديمه مع الإصدار 2018-11-09، باستخدام بيانات اعتماد Microsoft Entra ويتم دعمه لخدمة Blob فقط من أجل:

• منح حق الوصول إلى حاوية موجودة.
• منح حق الوصول لإنشاء الكائنات الثنائية كبيرة الحجم واستخدامها وحذفها.

لإنشاء رمز SAS المميز لتفويض المستخدمين، يجب أن يكون لدى العميل أذونات لاستدعاء عملية blobServiceClient.getUserDelegationKey. يتم استخدام المفتاح الذي تم إرجاعه بواسطة هذه العملية للتوقيع على رمز SAS المميز لتفويض المستخدمين. يجب تعيين دور التحكم في الوصول استناداً إلى الدور لمدير الأمان الذي يستدعي هذه العملية والذي يتضمن Microsoft.Storage/storageAccounts/blobServices/generateUserDelegationKey/action.

الأذونات الممنوحة للعميل الذي يمتلك رمز SAS المميز هي تقاطع الأذونات التي تم منحها لمدير الأمان الذي طلب مفتاح تفويض المستخدمين والأذونات التي تم منحها للمورد على رمز SAS المميز في حقل الأذوناتالموقعة (sp). إذا لم يتم أيضًا منح الإذن الممنوح لمدير الأمان عبر التحكم في الوصول استناداً إلى الدور على رمز SAS المميز، فلن يتم منح هذا الإذن للعميل الذي يحاول استخدام رمز SAS المميز للوصول إلى المورد.

تتوفر عينات قصاصات برمجية في GitHub في شكل ملفات Node.js قابلة للتشغيل.

حزمة (npm) | العينات | مرجع API | التعليمة البرمجية لمصدر المكتبة | تقديم الملاحظات

أفضل الممارسات لرموز SAS المميزة لتفويض المستخدمين

نظرًا لأنه يمكن لأي شخص لديه رمز SAS المميز استخدامه للوصول إلى الحاوية والكائنات الثنائية كبيرة الحجم، يجب عليك تعريف رمز SAS المميز مع الأذونات الأكثر تقييدًا التي لا تزال تسمح للرمز المميز بإكمال المهام المطلوبة.

أفضل الممارسات لرموز SAS المميزة

استخدام DefaultAzureCredential في سحابة Azure

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

لإعداد الهوية المُدارة لسحابة Azure:

• إنشاء هوية مدارة
• تعيين أدوار التخزين المناسبة للهوية
• تكوين بيئة Azure خاصتك للعمل مع هويتك المُدارة

عند اكتمال هاتين المهمتين، استخدم DefaultAzureCredential بدلًا من سلسلة الاتصال أو مفتاح الحساب. يسمح هذا لجميع بيئاتك باستخدام نفس التعليمات البرمجية المصدر بالضبط دون مشكلة استخدام البيانات السرية في التعليمات البرمجية المصدر.

استخدام DefaultAzureCredential في التطوير المحلي

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

الحاوية: إضافة التبعيات المطلوبة إلى تطبيقك

تضمين التبعيات المطلوبة لإنشاء رمز SAS المميز للحاوية.

const {
    DefaultAzureCredential
} = require('@azure/identity');
const {
    ContainerClient,
    BlobServiceClient,
    ContainerSASPermissions,
    generateBlobSASQueryParameters,
    SASProtocol
} = require('@azure/storage-blob');

// used for local environment variables
require('dotenv').config();

الحاوية: الحصول على متغيرات البيئة

اسم حساب Blob Storage واسم الحاوية هما الحد الأدنى من القيم المطلوبة لإنشاء رمز SAS المميز للحاوية:

// Get environment variables for DefaultAzureCredential
const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME;
const containerName = process.env.AZURE_STORAGE_BLOB_CONTAINER_NAME;

إنشاء رمز SAS المميز باستخدام DefaultAzureCredential

الخطوات المفاهيمية التالية مطلوبة لإنشاء رمز SAS المميز باستخدام DefaultAzureCredential:

• إعداد DefaultAzureCredential
  • التطوير المحلي - استخدام الهوية الشخصية وتعيين الأدوار للتخزين
  • سحابة Azure - إنشاء هوية مُدارة
• استخدام DefaultAzureCredential للحصول على مفتاح تفويض المستخدمين باستخدام UserDelegationKey
• استخدام مفتاح تفويض المستخدمين لإنشاء رمز SAS المميز مع الحقول المناسبة مع generateBlobSASQueryParameters

الحاوية: إنشاء رمز SAS المميز باستخدام DefaultAzureCredential

مع تكوين الهوية، استخدم التعليمات البرمجية التالية لإنشاء رمز SAS المميز لتفويض المستخدمين لحساب وحاوية موجودين:

// Server creates User Delegation SAS Token for container
async function createContainerSas() {

    // Get environment variables
    const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME;
    const containerName = process.env.AZURE_STORAGE_BLOB_CONTAINER_NAME;

    // Best practice: create time limits
    const TEN_MINUTES = 10 * 60 * 1000;
    const NOW = new Date();

    // Best practice: set start time a little before current time to 
    // make sure any clock issues are avoided
    const TEN_MINUTES_BEFORE_NOW = new Date(NOW.valueOf() - TEN_MINUTES);
    const TEN_MINUTES_AFTER_NOW = new Date(NOW.valueOf() + TEN_MINUTES);

    // Best practice: use managed identity - DefaultAzureCredential
    const blobServiceClient = new BlobServiceClient(
        `https://${accountName}.blob.core.windows.net`,
        new DefaultAzureCredential()
      );

    // Best practice: delegation key is time-limited  
    // When using a user delegation key, container must already exist 
    const userDelegationKey = await blobServiceClient.getUserDelegationKey(
        TEN_MINUTES_BEFORE_NOW, 
        TEN_MINUTES_AFTER_NOW
    );

    // Need only list permission to list blobs 
    const containerPermissionsForAnonymousUser = "l";

    // Best practice: SAS options are time-limited
    const sasOptions = {
        containerName,                                           
        permissions: ContainerSASPermissions.parse(containerPermissionsForAnonymousUser), 
        protocol: SASProtocol.HttpsAndHttp,
        startsOn: TEN_MINUTES_BEFORE_NOW,
        expiresOn: TEN_MINUTES_AFTER_NOW
    };
 
    const sasToken = generateBlobSASQueryParameters(
        sasOptions,
        userDelegationKey,
        accountName 
    ).toString();

    return sasToken;
}

تنشئ التعليمات البرمجية السابقة للخادم تدفقًا من القيم من أجل إنشاء رمز SAS المميز للحاوية:

• إنشاء BlobServiceClient باستخدام DefaultAzureCredential
• استخدام عملية blobServiceClient.getUserDelegationKey لإنشاء UserDelegationKey
• استخدام المفتاح لإنشاء سلسلة رمز SAS المميز باستخدام generateBlobSASQueryParameters

بمجرد إنشاء رمز SAS المميز للحاوية، يمكنك توفيره للعميل الذي سيستهلك الرمز المميز. يمكن للعميل بعد ذلك استخدامه لسرد الكائنات الثنائية كبيرة الحجم في حاوية. يوضح مثال التعليمات البرمجية للعميل كيفية اختبار رمز SAS المميز كمستهلك.

الحاوية: استخدام رمز SAS المميز

بمجرد إنشاء رمز SAS المميز للحاوية، استخدم الرمز المميز. كمثال على استخدام رمز SAS المميز، يمكنك:

• إنشاء عنوان URL كامل بما في ذلك اسم الحاوية وسلسلة الاستعلام. سلسلة الاستعلام هي رمز SAS المميز.
• إنشاء ContainerClient باستخدام عنوان URL للحاوية.
• استخدام العميل: في هذا المثال، بادر بإدراج الكائنات الثنائية كبيرة الحجم في الحاوية مع listBlobsFlat.

// Client or another process uses SAS token to use container
async function listBlobs(sasToken){

    // Get environment variables
    const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME;
    const containerName = process.env.AZURE_STORAGE_BLOB_CONTAINER_NAME;
    
    // Create Url
    // SAS token is the query string with typical `?` delimiter
    const sasUrl = `https://${accountName}.blob.core.windows.net/${containerName}?${sasToken}`;
    console.log(`\nContainerUrl = ${sasUrl}\n`);

    // Create container client from SAS token url
    const containerClient = new ContainerClient(sasUrl);

    let i = 1;

    // List blobs in container
    for await (const blob of containerClient.listBlobsFlat()) {
        console.log(`Blob ${i++}: ${blob.name}`);
    }    
}

الكائن الثنائي كبير الحجم: إضافة التبعيات المطلوبة إلى تطبيقك

تضمين التبعيات المطلوبة لإنشاء رمز SAS المميز للكائن الثنائي كبير الحجم.

const {
    DefaultAzureCredential
} = require('@azure/identity');
const {
    BlockBlobClient,
    BlobServiceClient,
    BlobSASPermissions,
    generateBlobSASQueryParameters,
    SASProtocol
} = require('@azure/storage-blob');

// used for local environment variables
require('dotenv').config();

الكائن الثنائي كبير الحجم: الحصول على متغيرات البيئة

اسم حساب Blob Storage واسم الحاوية هما الحد الأدنى من القيم المطلوبة لإنشاء رمز SAS المميز للكائن الثنائي كبير الحجم:

const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME;
const containerName = process.env.AZURE_STORAGE_BLOB_CONTAINER_NAME;

عندما تحتاج إلى إنشاء رمز SAS مميز للكائن الثنائي كبير الحجم، تحتاج أن يكون لديك اسم الكائن الثنائي كبير الحجم لإنشاء رمز SAS المميز. سيتم تحديد ذلك مسبقًا مثل اسم كائن ثنائي كبير الحجم عشوائي أو اسم كائن ثنائي كبير الحجم مُقدَّم من المستخدمين أو اسم تم إنشاؤه من تطبيقك.

// Create random blob name for text file
const blobName = `${(0|Math.random()*9e6).toString(36)}.txt`;

الكائن الثنائي كبير الحجم: إنشاء رمز SAS المميز باستخدام DefaultAzureCredential

مع تكوين الهوية، استخدم التعليمات البرمجية التالية لإنشاء رمز SAS المميز لتفويض المستخدمين لحساب وحاوية موجودين:

// Server creates User Delegation SAS Token for blob
async function createBlobSas(blobName) {

    // Get environment variables
    const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME;
    const containerName = process.env.AZURE_STORAGE_BLOB_CONTAINER_NAME;

    // Best practice: create time limits
    const TEN_MINUTES = 10 * 60 * 1000;
    const NOW = new Date();

    // Best practice: set start time a little before current time to 
    // make sure any clock issues are avoided
    const TEN_MINUTES_BEFORE_NOW = new Date(NOW.valueOf() - TEN_MINUTES);
    const TEN_MINUTES_AFTER_NOW = new Date(NOW.valueOf() + TEN_MINUTES);

    // Best practice: use managed identity - DefaultAzureCredential
    const blobServiceClient = new BlobServiceClient(
        `https://${accountName}.blob.core.windows.net`,
        new DefaultAzureCredential()
      );

    // Best practice: delegation key is time-limited  
    // When using a user delegation key, container must already exist 
    const userDelegationKey = await blobServiceClient.getUserDelegationKey(
        TEN_MINUTES_BEFORE_NOW, 
        TEN_MINUTES_AFTER_NOW
    );

    // Need only create/write permission to upload file
    const blobPermissionsForAnonymousUser = "cw"

    // Best practice: SAS options are time-limited
    const sasOptions = {
        blobName,
        containerName,                                           
        permissions: BlobSASPermissions.parse(blobPermissionsForAnonymousUser), 
        protocol: SASProtocol.HttpsAndHttp,
        startsOn: TEN_MINUTES_BEFORE_NOW,
        expiresOn: TEN_MINUTES_AFTER_NOW
    };
 
    const sasToken = generateBlobSASQueryParameters(
        sasOptions,
        userDelegationKey,
        accountName 
    ).toString();

    return sasToken;
}

تنشئ التعليمات البرمجية السابقة تدفقًا من القيم من أجل إنشاء رمز SAS المميز للحاوية:

• إنشاء BlobServiceClient باستخدام DefaultAzureCredential
• استخدام عملية blobServiceClient.getUserDelegationKey لإنشاء UserDelegationKey
• استخدام المفتاح لإنشاء سلسلة رمز SAS المميز. إذا لم يتم تحديد اسم الكائن الثنائي كبير الحجم في الخيارات، فإن رمز SAS المميز هو رمز حاوية مميز.

بمجرد إنشاء رمز SAS المميز للكائن الثنائي كبير الحجم، يمكنك توفيره للعميل الذي سيستهلك الرمز المميز. يمكن للعميل بعد ذلك استخدامه لتحميل كائن ثنائي كبير الحجم. يوضح مثال التعليمات البرمجية للعميل كيفية اختبار رمز SAS المميز كمستهلك.

كائن ثنائي كبير الحجم: استخدام رمز SAS المميز

بمجرد إنشاء رمز SAS المميز للكائن الثنائي كبير الحجم، استخدم الرمز المميز. كمثال على استخدام رمز SAS المميز، يمكنك:

• إنشاء عنوان URL كامل بما في ذلك اسم الحاوية واسم الكائن الثنائي كبير الحجم وسلسلة الاستعلام. سلسلة الاستعلام هي رمز SAS المميز.
• إنشاء BlockBlobClient باستخدام عنوان URL للحاوية.
• استخدم العميل: في هذا المثال، بادر بتحميل كائن ثنائي كبير الحجم مع التحميل.

// Client or another process uses SAS token to upload content to blob
async function uploadStringToBlob(blobName, sasToken, textAsString){

    // Get environment variables
    const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME;
    const containerName = process.env.AZURE_STORAGE_BLOB_CONTAINER_NAME;

    // Create Url SAS token as query string with typical `?` delimiter
    const sasUrl = `https://${accountName}.blob.core.windows.net/${containerName}/${blobName}?${sasToken}`;
    console.log(`\nBlobUrl = ${sasUrl}\n`);

    // Create blob client from SAS token url
    const blockBlobClient = new BlockBlobClient(sasUrl);

    // Upload string
    await blockBlobClient.upload(textAsString, textAsString.length, undefined);    
}

(راجع أيضًا )

• أنواع رموز SAS المميزة
• مرجع واجهة برمجة التطبيقات
• التعليمات البرمجية لمصدر للمكتبة
• تقديم ملاحظات