Azure Key Vault

نظرة عامة

يأخذك هذا الدليل عبر تكوين Azure Key Vault كمزود أسرار لمؤسستك على CrewAI Platform، باستخدام App Registration في Microsoft Entra مع سر عميل. بنهاية الدليل، ستتمكن CrewAI Platform من قراءة الأسرار المخزّنة في Azure Key Vault الخاص بك وحقنها كقيم متغيرات بيئة وقت التشغيل.

المتطلبات المسبقة

الخطوة 1 — إنشاء App Registration

App Registration هي الهوية من جانب Microsoft Entra التي ستُصادق بها CrewAI Platform.

في بوابة Microsoft Entra، انتقل إلى App registrations وانقر على New registration.

Name: crewai-secrets-reader
Supported account types: Accounts in this organizational directory only (Single tenant).
اترك Redirect URI فارغاً.

انقر على Register. سجّل Application (client) ID و Directory (tenant) ID في لوحة نظرة عامة التطبيق — ستلصق كليهما في CrewAI Platform في الخطوة 4.

للتفاصيل الكاملة، راجع وثائق Microsoft: Register an application with the Microsoft identity platform.

الخطوة 2 — إنشاء سر عميل

في App Registration، انتقل إلى Certificates & secrets ← Client secrets ← New client secret.

Description: crewai-platform
Expires: اختر مدة تتطابق مع سياسة التدوير لديك (تحدّد Microsoft هذا بـ 24 شهراً كحد أقصى).

انقر على Add. انسخ عمود Value فوراً — لا يمكن إعادة عرضه أبداً بمجرد مغادرة الصفحة.

الخطوة 3 — منح App Registration وصولاً إلى Key Vault

تحتاج CrewAI Platform إلى وصول قراءة للأسرار في Key Vault الخاص بك. استخدم أحد نطاقين — على مستوى الخزنة للبساطة، أو لكل سر لأقل الامتيازات.

على مستوى الخزنة (أبسط)

في وحدة تحكم Key Vault، افتح الخزنة الهدف، ثم انتقل إلى Access control (IAM) ← Add ← Add role assignment.

Role: Key Vault Secrets User
Assign access to: User, group, or service principal
Members: ابحث عن App Registration الخاص بك (crewai-secrets-reader) واختره.

انقر على Review + assign.

أو عبر Azure CLI:

az role assignment create \
  --assignee <APPLICATION_CLIENT_ID> \
  --role "Key Vault Secrets User" \
  --scope $(az keyvault show --name <VAULT_NAME> --query id -o tsv)

لكل سر (أقل الامتيازات)

امنح الدور على مستوى سر فردي. كرّر لكل سر ينبغي أن تصل إليه CrewAI Platform:

az role assignment create \
  --assignee <APPLICATION_CLIENT_ID> \
  --role "Key Vault Secrets User" \
  --scope $(az keyvault secret show --vault-name <VAULT_NAME> --name <SECRET_NAME> --query id -o tsv)

الخطوة 4 — إضافة بيانات الاعتماد في CrewAI Platform

في CrewAI Platform، انتقل إلى Settings ← Secret Provider Credentials وانقر على Add Credential.

املأ النموذج:

Name: اسم وصفي، مثلاً azure-prod.
Provider: Azure Key Vault.
Key Vault URL: اسم مضيف DNS للخزنة، مثلاً https://my-vault.vault.azure.net.
Tenant ID: Directory (tenant) ID الخاص بـ Microsoft Entra من الخطوة 1.
Client ID: Application (client) ID الخاص بـ App Registration من الخطوة 1.
Client Secret: Value الذي نسخته في الخطوة 2.
(اختياري) حدّد Set as default credential for this provider. تُستخدم بيانات الاعتماد الافتراضية بواسطة متغيرات البيئة التي تشير إلى أسرار Azure بدون تحديد بيانات اعتماد صراحةً.

انقر على Create.

الخطوة 5 — إنشاء سر واحد على الأقل في Azure Key Vault

إذا لم يكن لديك بالفعل أسرار في Key Vault، أنشئ واحداً الآن لتتمكن من التحقق من الاتصال في الخطوة 6.

في وحدة تحكم Key Vault، انتقل إلى Objects ← Secrets ← Generate/Import.

Upload options: Manual
Name: مثلاً openai-api-key
Secret value: الصق قيمة سرّك
اترك الباقي على القيم الافتراضية.

انقر على Create.

أو عبر Azure CLI:

az keyvault secret set \
  --vault-name <VAULT_NAME> \
  --name openai-api-key \
  --value "sk-your-actual-key"

للتفاصيل الكاملة، راجع وثائق Microsoft: Set and retrieve a secret.

الخطوة 6 — اختبار الاتصال

عُد إلى CrewAI Platform، في صفحة Secret Provider Credentials، اعثر على بيانات الاعتماد التي أنشأتها للتو وانقر على Test Connection.

تؤكد رسالة نجاح أن CrewAI Platform يمكنها المصادقة مع Microsoft Entra وقراءة الأسرار من خزنتك.

إذا فشل الاختبار، تحقق من الأسباب الأكثر شيوعاً:

العَرَض	السبب المحتمل
`AADSTS7000215: Invalid client secret provided`	Client Secret الملصوق خاطئ أو منتهي الصلاحية. أعد إنشاء السر (الخطوة 2) وحدّث بيانات الاعتماد.
`AADSTS700016: Application not found in the directory`	لا يطابق Tenant ID أو Client ID الـ App Registration. تحقق من الخطوة 4 من جديد.
`Forbidden — caller does not have permission`	يفتقد App Registration إلى دور Key Vault Secrets User على الخزنة (أو لكل سر). تحقق من الخطوة 3 من جديد.
`Vault not found` / أخطاء DNS	Key Vault URL خاطئ، أو أن خزنتك لديها نقاط نهاية خاصة تمنع الوصول العام. تأكد من أن المضيف يستجيب لـ `curl https://<vault-name>.vault.azure.net/secrets?api-version=7.4`.
`Forbidden — request was not authorized` (الخزنة تستخدم سياسات الوصول القديمة)	لم يتم تحويل الخزنة إلى Azure RBAC. ضمن Access configuration للخزنة، عيّن نموذج الإذن إلى Azure role-based access control وأعد منح الدور من الخطوة 3.

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

الآن وقد اتصل Azure Key Vault، توجّه إلى استخدام مدير الأسرار من أجل:

منح أعضاء المؤسسة الأذونات الصحيحة لاستخدام (أو إدارة) مدير الأسرار.
الإشارة إلى أسرار Azure الخاصة بك من متغيرات بيئة CrewAI Platform.

إذا كنت تريد أسراراً مراعية للتدوير تنتشر دون إعادة نشر، انتقل إلى Azure Workload Identity Federation — نفس الخزنة، بدون سر عميل للتدوير، وتُجلب الأسرار في كل إطلاق.

مرجع لقطات الشاشة

تُربط العناصر النائبة أعلاه بـ:

01-register-app.png — نموذج “Register an application” في بوابة Azure مع crewai-secrets-reader.
02-create-client-secret.png — App Registration ← Certificates & secrets ← Client secrets، مع صف السر المُنشأ حديثاً (عمود Value مُميَّز قبل تمويهه).
03-grant-vault-rbac.png — Key Vault ← Access control (IAM) ← Add role assignment، مع اختيار Key Vault Secrets User و App Registration كعضو.
04-per-secret-rbac.png — نفس اللوحة لكن بنطاق سر واحد (مسار أقل الامتيازات البديل).
05-amp-add-credential-form-azure.png — نموذج “Add Secret Provider Credential” في CrewAI Platform: Provider = Azure Key Vault، جميع الحقول الخمسة مأهولة.
06-create-secret.png — لوحة “Create a secret” في Azure Key Vault مع openai-api-key وقيمة ملصوقة.
07-test-connection-success.png — رسالة نجاح / حالة صف في CrewAI Platform بعد النقر على Test Connection على بيانات الاعتماد.