Configure Functions host key storage on Azure Container Apps

مفاتيح الوصول إلى الوظائف هي رموز مصادقة تستخدمها وقت تشغيل الدوال لتأمين نقاط النهاية التي تفعل بواسطة HTTP. عندما يستدعي المتصل دالة HTTP، فإنه يتضمن مفتاحا كمعامل ?code= استعلام أو x-functions-key رأس رئيس. يقوم وقت التشغيل بالتحقق من صحة المفتاح ويفوض أو يرفض الطلب.

مفاتيح الوصول ليست مثل الأسرار على مستوى التطبيق. مفاتيح الوصول تحمي من يمكنه استدعاء وظائفك، بينما تحفظ أسرار التطبيق ما تتصل به وظائفك.

متى تستخدم مفاتيح الوصول

Scenario	لماذا تتناسب مفاتيح الوصول
خطافات الويب الخاصة من طرف ثالث	مزودون مثل GitHub وStripe أو Twilio يستدعون وظيفتك عبر رابط URL وسر. مفاتيح الوصول تدخل مباشرة في النمط الذي ?code= يتوقعونه.
مكالمات خدمة إلى خدمة	خدمة الخلفية A تستدعي الوظيفة B عبر HTTP. المفتاح المشترك أبسط من إعداد تسجيلات تطبيقات Microsoft Entra للمكالمات الداخلية فقط.
اشتراكات شبكة الفعاليات	تقوم شبكة الأحداث بالتحقق من صحة واستدعاء نقطة نهاية الوظيفة الخاصة بك باستخدام مفتاح نظام تديره المنصة تلقائيا.
المطور/المصادقة التجريبية	أثناء التطوير تحتاج إلى مصادقة أساسية دون تكوين OAuth/OIDC بالكامل. توفر مفاتيح الوصول بوابة مصادقة منخفضة الاحتكاك بدون إعدادات هوية.
توافق الترحيل	تطبيقات دالات Azure الحالية تستخدم بالفعل مفاتيح الوصول. عند الانتقال إلى تطبيقات الحاويات، تحتاج إلى نفس المصادقة المعتمدة على المفاتيح لتجنب تعطيل المتصلين.

ملحوظة

بالنسبة لواجهات برمجة التطبيقات التي تواجه المستخدم، أو أحمال عمل الثقة الصفرية، أو سيناريوهات التفويض لكل مستخدم، استخدم Microsoft Entra ID / OAuth 2.0 بدلا من مفاتيح الوصول. مفاتيح الوصول هي أسرار مشتركة بدون أثر تدقيق على مستوى الهوية.

Prerequisites

• حساب Azure مع اشتراك نشط. أنشئ حساباً مجاناً.
• Azure CLI الإصدار 2.40.0 أو أعلى.
• تطبيق دالات Azure موجود في تطبيقات الحاويات أو أذونات لإنشاء واحد.

أنواع مفاتيح الوصول

يدير وقت تشغيل الدوال أربعة أنواع من المفاتيح:

نوع المفتاح	النطاق	الغرض
المفتاح الرئيسي (_master)	تطبيق الوظيفة بالكامل	الوصول على مستوى الإدارة إلى جميع الوظائف ونقاط /admin/* النهاية الإدارية. لا يمكن إلغاؤه، فقط يمكن التدوير.
مفاتيح المضيف (default + مخصص)	تطبيق الوظيفة بالكامل	تفوض المكالمات لأي وظيفة يتم تفعيلها عبر HTTP في التطبيق.
مفاتيح الوظائف (default + مخصصة)	وظيفة واحدة	تفويض المكالمات إلى وظيفة محددة واحدة. يوفر تحكما أكثر تفصيلا من مفاتيح المضيف.
مفاتيح النظام	نقاط الامتداد	تستخدم من قبل امتدادات المنصات مثل اشتراكات Event Grid webhook وDurable Functions. يتم التحكم تلقائيا.

اختر خلفية تخزين

قم بتعيين AzureWebJobsSecretStorageType متغير البيئة للتحكم في مكان استمرار وقت التشغيل في مفاتيح الوصول. يدعم Azure Container Apps ثلاث خلفيات إنتاجية من الطراز الأول.

الخلفية	إعداد القيمة	المفاتيح التي تولد تلقائيا	التبعية الخارجية	الأفضل ل
المخزن السري لتطبيقات الحاوية	containerapps	لا - أنت توفر المفاتيح كأسرار تطبيقات الحاويات	‏‫بلا	معظم أعباء العمل (موصى بها)
Azure Key Vault	keyvault	لا - إنشاء الزناد يدويا	نسخة Key Vault	الحوكمة المركزية، تدقيق الامتثال
مساحة تخزين Azure Blob	blob	‏‏نعم‬	حساب التخزين	التطبيقات القديمة أو الحساب الحالي AzureWebJobsStorage

ضع هذه الاعتبارات الخلفية في اعتبارك:

• وقت التشغيل لا يختار تلقائيا التخزين السري لتطبيقات الحاويات. إذا لم تقم بتعيينها AzureWebJobsSecretStorageType أو ضبطها على قيمة غير معروفة، فإن مضيف الوظائف يستخدم مخزن البيانات الثنائية الكبيرة عندما AzureWebJobsStorage يكون متاحا.
• احتفظ AzureWebJobsStorage بالتكوين لفحص صحة التخزين والميزات المعتمدة على التخزين.
• لا تضبط AzureWebJobsSecretStorageType على files. نظام ملفات تطبيقات الحاويات مؤقت، لذا تفقد المفاتيح المخزنة في هذا القسم الخلفي عندما يتدرج التطبيق إلى الصفر، أو يعيد التشغيل، أو ينشر نسخة جديدة.

أنماط الأسماء السرية

تعتمد قاعدة التسمية للمفاتيح المخزنة على خلفية التخزين.

المخزن السري لتطبيقات الحاوية

يستخدم المتجر السري لتطبيقات الحاويات نظاما مختلفا. يقرأ مضيف الدوال المفاتيح من الملفات المركبة على مستوى الصوت عند /run/secrets/functions-keys/. يستخدم كل ملف اسما منقطا (على سبيل المثال، host.master)، لكن الأسماء السرية في تطبيقات الحاويات تسمح فقط بالأحرف الأبجدية الصغيرة والشرطات. عند تركيب وحدة تخزين سرية، يجب عليك تحديد path الحقل بشكل صريح ليكون باسم الملف المنقط الذي يتوقعه مضيف الوظائف (على سبيل المثال، secretRef: host-master → path: host.master). المنصة لا تقوم بأي ترجمة تلقائية للأسماء.

نوع المفتاح	اسم Container Apps السري (شرطات)	حامل path الصوت (نقاط)
المفتاح الرئيسي	host-master	host.master
مفتاح المضيف الافتراضي	host-function-default	host.function.default
مفتاح المضيف المخصص	host-function-<name>	host.function.<name>
مفتاح الدالة الافتراضي لدالة معينة	functions-<functionname>-default	functions.<functionName>.default
مفتاح الدوال المخصص لوظيفة معينة	functions-<functionname>-<keyname>	functions.<functionName>.<keyName>
مفتاح النظام	host-systemkey-<extension>	host.systemKey.<extension>

خزنة المفاتيح

يخزن Key Vault الخلفية كل مفتاح كسر Key Vault فردي باستخدام اتفاقية الشرطين (--):

نوع المفتاح	نمط الاسم السري	مثال
المفتاح الرئيسي	host--masterKey--master	host--masterKey--master
مفتاح الوظيفة (الافتراضي)	host--functionKey--default	host--functionKey--default
مفتاح الوظيفة (مخصص)	host--functionKey--<name>	host--functionKey--MyApiClient
مفتاح النظام	host--systemKey--<extension>	host--systemKey--eventgrid_extension
مفتاح لكل وظيفة	function--<functionName>--<keyName>	function--myhttpfunc--default

تخزين كائن ثنائي كبير الحجم

يخزن الخلفية مخزن البيانات الثنائية الكبيرة المفاتيح كملفات JSON في حاوية blob azure-webjobs-secrets. جميع مفاتيح مستوى المضيف (رئيسي، مفاتيح الوظائف، ومفاتيح النظام) مخزنة معا في كتلة واحدة host.json . يتم تخزين مفاتيح كل وظيفة في كتل منفصلة تحمل اسم كل وظيفة.

مسار الكتلة	المحتويات
<SITE_SLOT_NAME>/host.json	ملف JSON يحتوي على masterKey، functionKeys، و systemKeys
<SITE_SLOT_NAME>/<FUNCTION_NAME>.json	ملف JSON يحتوي على مفاتيح لوظيفة محددة

Tip

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

تكوين المخزن السري لتطبيقات الحاويات

المخزن السري لتطبيقات الحاويات هو القسم الخلفي الموصى به. تبقى المفاتيح ضمن منصة تطبيقات الحاويات ولا تتطلب تخزينا خارجيا أو Key Vault. سجلات نشاط Azure Resource Manager تتبع التغييرات في الأسرار ومتغيرات البيئة.

مع هذا الخلفية، يقرأ مضيف الوظائف المفاتيح من الملفات المركبة على حجم التخزين عند /run/secrets/functions-keys/. المضيف لا يولد المفاتيح تلقائيا. يجب عليك إنشاء كل مفتاح كسر لتطبيقات الحاويات، وتقوم المنصة بتثبيته كملفات ليقرأها المضيف.

Important

المتجر السري لتطبيقات الحاويات هو للقراءة فقط من منظور المضيف. المضيف يقرأ ملفات المفاتيح المثبتة لكنه لا يكتب إليها أبدا. إذا كان المفتاح المطلوب مفقودا، لا يقوم المضيف بتوليده تلقائيا.

الخطوة 1: حدد نوع التخزين

بوابة

1. اذهب إلى تطبيق حاوية الوظائف الخاص بك في بوابة Azure.

2. في الإعدادات، اختر متغيرات البيئة.

3. اختر الإضافة، وأدخل القيم التالية:

   الخاصية	القيمة
   Name	AzureWebJobsSecretStorageType
   قيمه	containerapps

4. اختر حفظ، ثم اختر تطبيق لتأكيد التغييرات.

az containerapp update \
  --resource-group "<RESOURCE_GROUP>" \
  --name "<FUNCTIONS_APP_NAME>" \
  --set-env-vars "AzureWebJobsSecretStorageType=containerapps"

الخطوة 2: توليد وتخزين أسرار مفاتيح الوصول

قم بتوليد قيم رئيسية وتخزينها كأسرار لتطبيقات الحاويات. على الأقل، تحتاج إلى المفتاح الرئيسيومفتاح المضيف الافتراضي.

بوابة

1. في تطبيق حاوية الوظائف الخاص بك، تحت الإعدادات، اختر الأسرار.

2. اختر الإضافة وأدخل القيم التالية:

   الخاصية	القيمة
   Name	host-master
   النوع	سر تطبيقات الحاويات
   قيمه	قيمة مفتاح مولدة عشوائيا.

3. حدد إضافة.

4. كرر ل host-function-default مع قيمة أخرى مولدة عشوائيا.

5. لإضافة مفتاح لكل دالة، أضف سريا يسمى functions-<functionname>-default (كلها بحروف صغيرة).

# Generate random key values
MASTER_KEY=$(openssl rand -hex 32)
HOST_DEFAULT_KEY=$(openssl rand -hex 32)

# Store as Container Apps secrets
az containerapp secret set \
  --resource-group "<RESOURCE_GROUP>" \
  --name "<FUNCTIONS_APP_NAME>" \
  --secrets "host-master=$MASTER_KEY" "host-function-default=$HOST_DEFAULT_KEY"

لإضافة مفتاح لكل دالة (على سبيل المثال، لدالة تحمل الاسم MyHttpFunc:

FUNC_KEY=$(openssl rand -hex 32)

az containerapp secret set \
  --resource-group "<RESOURCE_GROUP>" \
  --name "<FUNCTIONS_APP_NAME>" \
  --secrets "functions-myhttpfunc-default=$FUNC_KEY"

ملحوظة

تسمح أسماء السرية في تطبيقات الحاويات فقط بالأحرف الأبجدية الصغيرة والشرطات. يجب أن تضبط path الحقل في تكوين الحجم بشكل صريح على اسم الملف المنقط الذي يتوقعه مضيف الوظائف (على سبيل المثال، secretRef: host-master → path: host.master). بدون وجود pathصريح ، يحتفظ الملف على القرص بالاسم المتقطع ولن يجد مضيف الوظائف المفتاح.

الخطوة 3: قم بضبط حامل الصوت

قم بجمع الأسرار كملفات عند /run/secrets/functions-keys/.

بوابة

1. في تطبيق حاوية الوظائف الخاص بك، تحت قسم التطبيق، اختر المراجعات والنسخ المقلدة.

2. حدد إنشاء مراجعة جديدة.

3. في تبويب المقياس والأحجام ، تحت المقاس، اختر الإضافة.

4. أدخل القيم التالية:

   الخاصية	القيمة
   نوع المجلد	سري
   Name	functions-keys

5. لكل سر، قم بتعيين حقل المسار إلى اسم الملف المنقط الذي يتوقعه مضيف الوظائف (على سبيل المثال، تعيين host-master إلى مسار host.master، و host-function-default إلى مسار host.function.default).

6. حدد إضافة.

7. في تبويب الحاوية ، اختر الحاوية ثم اختر تعديل.

8. اختر تبويب تركيب الصوت واختر الإضافة.

9. أدخل القيم التالية:

   الخاصية	القيمة
   اسم وحدة التخزين	functions-keys
   مسار التحميل	/run/secrets/functions-keys

10. اختر حفظ، ثم اختر إنشاء لنشر النسخة الجديدة.

تصدير YAML الخاص بالتطبيق، أضف ملف الصوت وحامل الصوت، ثم طبق:

# Export current config
az containerapp show \
  --resource-group "<RESOURCE_GROUP>" \
  --name "<FUNCTIONS_APP_NAME>" \
  --output yaml > app.yaml

تعديل app.yaml لإضافة حامل الصوت والصوت تحت الأقسام المناسبة:

properties:
  template:
    volumes:
      - name: functions-keys
        storageType: Secret
        secrets:
          - secretRef: host-master
            path: host.master
          - secretRef: host-function-default
            path: host.function.default
    containers:
      - name: <CONTAINER_NAME>
        volumeMounts:
          - volumeName: functions-keys
            mountPath: /run/secrets/functions-keys

طبق الإعدادات المحدثة:

az containerapp update \
  --resource-group "<RESOURCE_GROUP>" \
  --name "<FUNCTIONS_APP_NAME>" \
  --yaml app.yaml

الخطوة 4: التحقق

بعد إعادة تشغيل التطبيق، تأكد من أن الأزرار تعمل:

az containerapp function keys list \
  --resource-group "<RESOURCE_GROUP>" \
  --name "<FUNCTIONS_APP_NAME>" \
  --key-type hostKey

يمكنك أيضا التحقق من سجلات التطبيقات للرسالة Resolved secret storage provider ContainerAppsSecretsRepositoryالتي تؤكد أن المضيف يستخدم المخزن السري لتطبيقات الحاويات.

تدوير المفاتيح

لتدوير مفتاح، قم بتحديث سر تطبيقات الحاويات وأعد تشغيل التطبيق:

NEW_KEY=$(openssl rand -hex 32)

az containerapp secret set \
  --resource-group "<RESOURCE_GROUP>" \
  --name "<FUNCTIONS_APP_NAME>" \
  --secrets "host-function-default=$NEW_KEY"

az containerapp revision restart \
  --resource-group "<RESOURCE_GROUP>" \
  --name "<FUNCTIONS_APP_NAME>" \
  --revision "<REVISION_NAME>"

ملحوظة

جميع النسخ تشترك في نفس الأسرار المركبة. بعد إعادة التشغيل، تلتقط كل نسخة النسخة القيم الرئيسية المحدثة.

تكوين Key Vault أو مخزن البيانات الثنائية الكبيرة كمخزن

Configure Key Vault

يخزن الجانب الخلفي من Key Vault مفاتيح الوصول كأسرار Key Vault، مما يوفر تدقيقا وتحكم في الوصول على مستوى المؤسسات.

1. أنشئ Key Vault (إذا لم يكن لديك واحد):

   az keyvault create \
     --name "<KEYVAULT_NAME>" \
     --resource-group "<RESOURCE_GROUP>" \
     --location "<LOCATION>"
   

2. تفعيل الهوية المدارة في تطبيق الحاوية (إذا لم تكن مفعلة بالفعل):

   az containerapp identity assign \
     --resource-group "<RESOURCE_GROUP>" \
     --name "<FUNCTIONS_APP_NAME>" \
     --system-assigned
   

3. امنح دور ضابط الأسرار Key Vault للهوية المدارة. يحتاج وقت التشغيل إلى وصول للقراءة والكتابة لإنشاء وإدارة المفاتيح:

   PRINCIPAL_ID=$(az containerapp show \
     --resource-group "<RESOURCE_GROUP>" \
     --name "<FUNCTIONS_APP_NAME>" \
     --query identity.principalId \
     --output tsv)
   
   KEYVAULT_ID=$(az keyvault show \
     --name "<KEYVAULT_NAME>" \
     --query id \
     --output tsv)
   
   az role assignment create \
     --role "Key Vault Secrets Officer" \
     --assignee "$PRINCIPAL_ID" \
     --scope "$KEYVAULT_ID"
   

4. حدد نوع التخزين ورابط رابط Key Vault:

   للهوية المعينة من قبل النظام:

   az containerapp update \
     --resource-group "<RESOURCE_GROUP>" \
     --name "<FUNCTIONS_APP_NAME>" \
     --set-env-vars \
       "AzureWebJobsSecretStorageType=keyvault" \
       "AzureWebJobsSecretStorageKeyVaultUri=https://<KEYVAULT_NAME>.vault.azure.net"
   

   بالنسبة للهوية المعينة من قبل المستخدم، قم أيضا بتعيين معرف العميل:

   az containerapp update \
     --resource-group "<RESOURCE_GROUP>" \
     --name "<FUNCTIONS_APP_NAME>" \
     --set-env-vars \
       "AzureWebJobsSecretStorageType=keyvault" \
       "AzureWebJobsSecretStorageKeyVaultUri=https://<KEYVAULT_NAME>.vault.azure.net" \
       "AzureWebJobsSecretStorageKeyVaultClientId=<USER_ASSIGNED_IDENTITY_CLIENT_ID>"
   

5. قم بتفعيل إنشاء المفاتيح عن طريق سرد المفاتيح:

   az containerapp function keys list \
     --resource-group "<RESOURCE_GROUP>" \
     --name "<FUNCTIONS_APP_NAME>" \
     --key-type hostKey
   

Configure مخزن البيانات الثنائية الكبيرة

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

1. تفعيل الهوية المدارة في تطبيق الحاوية (إذا لم تكن مفعلة بالفعل):

   az containerapp identity assign \
     --resource-group "<RESOURCE_GROUP>" \
     --name "<FUNCTIONS_APP_NAME>" \
     --system-assigned
   

2. امنح دور مساهم بيانات كتلة التخزين على حساب التخزين للهوية المدارة:

   PRINCIPAL_ID=$(az containerapp show \
     --resource-group "<RESOURCE_GROUP>" \
     --name "<FUNCTIONS_APP_NAME>" \
     --query identity.principalId \
     --output tsv)
   
   STORAGE_ID=$(az storage account show \
     --name "<STORAGE_ACCOUNT_NAME>" \
     --resource-group "<RESOURCE_GROUP>" \
     --query id \
     --output tsv)
   
   az role assignment create \
     --role "Storage Blob Data Contributor" \
     --assignee "$PRINCIPAL_ID" \
     --scope "$STORAGE_ID"
   

3. حدد نوع التخزين:

   az containerapp update \
     --resource-group "<RESOURCE_GROUP>" \
     --name "<FUNCTIONS_APP_NAME>" \
     --set-env-vars "AzureWebJobsSecretStorageType=blob"
   

4. يتم توليد المفاتيح تلقائيا في التشغيل البارد التالي. تثبت:

   az containerapp function keys list \
     --resource-group "<RESOURCE_GROUP>" \
     --name "<FUNCTIONS_APP_NAME>" \
     --key-type hostKey
   

إدارة مفاتيح الوصول

بغض النظر عن الخلفية، استخدم الأوامر التالية لإدراج وإنشاء وحذف مفاتيح الوصول:

ملحوظة

احتفظ بعمل نسخة واحدة على الأقل لتنفيذ عمليات إدارة المفاتيح هذه.

• سرد جميع مفاتيح المضيف:

  az containerapp function keys list \
    --resource-group "<RESOURCE_GROUP>" \
    --name "<FUNCTIONS_APP_NAME>" \
    --key-type hostKey
  

• اذكر المفتاح الرئيسي:

  az containerapp function keys list \
    --resource-group "<RESOURCE_GROUP>" \
    --name "<FUNCTIONS_APP_NAME>" \
    --key-type masterKey
  

• إنشاء أو استبدال مفتاح مضيف مخصص:

  az containerapp function keys set \
    --resource-group "<RESOURCE_GROUP>" \
    --name "<FUNCTIONS_APP_NAME>" \
    --key-name "MyCustomKey" \
    --key-value "<YOUR_KEY_VALUE>" \
    --key-type hostKey
  

• أظهر مفتاحا محددا:

  az containerapp function keys show \
    --resource-group "<RESOURCE_GROUP>" \
    --name "<FUNCTIONS_APP_NAME>" \
    --key-name "<KEY_NAME>" \
    --key-type hostKey
  

• حذف مفتاح المضيف:

  az containerapp function keys delete \
    --resource-group "<RESOURCE_GROUP>" \
    --name "<FUNCTIONS_APP_NAME>" \
    --key-name "MyCustomKey" \
    --key-type hostKey
  

استدعاء دالة باستخدام مفتاح وصول

مرر المفتاح كمعلمة استعلام أو رأس طلب.

# Query parameter
curl "https://<FUNCTIONS_APP_URL>/api/<FUNCTION_NAME>?code=<HOST_KEY>"

# Header
curl "https://<FUNCTIONS_APP_URL>/api/<FUNCTION_NAME>" \
  -H "x-functions-key: <HOST_KEY>"

المحتوى ذو الصلة

• نظرة عامة على أسرار الوظائف
• أسرار على مستوى تطبيق المتجر
• إدارة الأسرار في Azure Container Apps
• مفاتيح إدارة الوظائف
• الهويات المدارة في تطبيقات الحاويات
• دالات Azure في نظرة عامة Azure Container Apps