Azure Workload Identity Federation

نظرة عامة

يُكوِّن هذا الدليل Azure Key Vault كمزود أسرار باستخدام Microsoft Entra Workload Identity Federation: تُصدر CrewAI Platform رموز OIDC قصيرة الأمد، وتُبادلها للحصول على رمز وصول Entra عبر منصة هوية Microsoft، وتقرأ أسرارك — دون تخزين أي سر عميل في أي مكان.

كيف يعمل وقت التشغيل

يطلب عامل النشر JWT OIDC طازج من CrewAI Platform.
يُقدّم العامل الـ JWT إلى Microsoft Entra على https://login.microsoftonline.com/<tenant>/oauth2/v2.0/token كـ client_assertion (urn:ietf:params:oauth:client-assertion-type:jwt-bearer)، مع الإشارة إلى App Registration الذي يطابق Federated Identity Credential الخاص به مُصدر الـ JWT وموضوعه.
تتحقق Entra من الـ JWT مقابل وثيقة اكتشاف OIDC و JWKS لمنصتك، ثم تُعيد رمز وصول قصير الأمد محصور بـ https://vault.azure.net/.default.
يستدعي العامل Azure Key Vault لقراءة السر.
تُحقن القيمة المجلوبة كقيمة لمتغير البيئة لإطلاق الأتمتة ذاك.

تُخزَّن رموز موضوع OIDC مؤقتاً لنحو ساعة لتفادي إعادة الإصدار في كل إطلاق. تُجلب قيم الأسرار طازجة في كل إطلاق بغض النظر عن حالة ذاكرة OIDC المؤقتة، وهذا ما يجعل هذا المسار مراعياً للتدوير.

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

Note

قبل البدء، تأكد من امتلاكك:

يجب أن تتضمن صورة حاوية الأتمتة إصدار CrewAI runtime رقم 1.14.5 أو أحدث.
اشتراك Azure ومستأجر Microsoft Entra يمكنك إدارته.
إذن في المستأجر لإنشاء App Registrations وإضافة Federated Identity Credentials.
Key Vault يستخدم Azure RBAC للترخيص (وليس النموذج القديم لسياسة الوصول).
مؤسسة على CrewAI Platform يمتلك مستخدمك فيها إذني workload_identity_configs: manage و secret_providers: manage. راجع الأذونات (RBAC).
يجب أن يكون تنصيب CrewAI Platform قابلاً للوصول من Microsoft Entra عبر HTTPS ليتمكّن Entra من جلب وثيقة اكتشاف OIDC و JWKS أثناء التحقق من الرمز. تأكد مع مسؤول المنصة من أن المضيف متاح عبر الإنترنت.

الخطوة 1 — العثور على عنوان مُصدر OIDC لـ CrewAI Platform

ينشر تنصيب CrewAI Platform وثيقة اكتشاف OpenID Connect على https://<your-platform-host>/.well-known/openid-configuration. الحقل issuer هناك هو الرابط الذي ستُسجِّله Microsoft Entra كمُصدر اتحاد موثوق.

افتح الرابط في المتصفح:

https://<your-platform-host>/.well-known/openid-configuration

ينبغي أن ترى JSON يحتوي على:

{
  "issuer": "https://<your-platform-host>",
  "jwks_uri": "https://<your-platform-host>/oauth2/jwks",
  ...
}

سجّل القيمة الدقيقة لـ issuer — ستستخدمها في الخطوة 3.

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

في بوابة 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 في لوحة نظرة عامة التطبيق — ستستخدمها في الخطوة 6.

الخطوة 3 — إضافة Federated Identity Credential

يُخبر Federated Identity Credential Microsoft Entra: ثِق برموز JWT المُصدَرة من هذا المُصدر، بهذا الموضوع، عندما تُقدَّم كتأكيد عميل لهذا App Registration.

في App Registration، انتقل إلى Certificates & secrets ← Federated credentials ← Add credential.

Federated credential scenario: Other issuer.
Issuer: رابط مُصدر CrewAI Platform من الخطوة 1، مثلاً https://<your-platform-host>.
Subject identifier: organization:<YOUR_CREWAI_ORG_UUID> — قيمة ادّعاء sub في JWT بالضبط. اعثر على UUID مؤسستك في إعدادات مؤسسة CrewAI Platform. يقصر هذا الاتحاد على مؤسسة CrewAI محددة — تُقبل فقط الرموز المُصدَرة لأتمتات تلك المؤسسة.
Name: أي تسمية وصفية، مثلاً crewai-org-prod.
Audience: api://AzureADTokenExchange. هذا هو الجمهور الثابت الذي تتطلبه Microsoft Entra للبيانات الموحَّدة، وهو ما تُعيّنه CrewAI Platform في ادّعاء aud في JWT.

انقر على Add.

للتفاصيل الكاملة، راجع وثائق Microsoft: Configure a federated identity credential on an app.

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

امنح App Registration دور Key Vault Secrets User على الخزنة المستهدفة — نفس الدور الذي تستخدمه لمسار بيانات الاعتماد الثابتة. استخدم إما على مستوى الخزنة (أبسط) أو لكل سر (أقل الامتيازات).

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

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

يمنح النطاق على مستوى الخزنة إذن secrets/list الذي يعتمد عليه الاقتراح التلقائي لاسم السر في نموذج متغير البيئة لـ 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)

تُعطّل الارتباطات لكل سر الاقتراح التلقائي لاسم السر في نموذج متغير البيئة لـ CrewAI Platform (يتطلب الاقتراح التلقائي secrets/list، وهو محصور بنطاق الخزنة فقط). اكتب اسم السر الكامل بدلاً من ذلك.

البوابة (UI)

لتعيين على مستوى الخزنة:

افتح Key Vault الخاص بك في بوابة Azure.
انقر على Access control (IAM) ← Add ← Add role assignment.
اختر الدور Key Vault Secrets User ← Next.
انقر على Select members، ابحث عن App Registration crewai-secrets-reader، انقر على Select.
انقر على Review + assign.

لتعيين لكل سر، استخدم نفس التدفق لكن ابدأ من Objects ← Secrets ← اختر السر ← لوحة Access control (IAM) الخاصة به. تُعطّل الارتباطات لكل سر الاقتراح التلقائي (راجع تبويبة لكل سر أعلاه).

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

إذا لم يكن لديك سر للاختبار، أنشئ واحداً عبر Azure CLI:

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

أو عبر بوابة Azure:

افتح Key Vault الخاص بك وانتقل إلى Objects ← Secrets.
انقر على Generate/Import.
Upload options: Manual. Name: اسم السر (مثلاً openai-api-key). Secret value: الصق القيمة.
انقر على Create.

الخطوة 6 — إضافة تكوين Workload Identity في CrewAI Platform

في CrewAI Platform، انتقل إلى Settings ← Workload Identity وانقر على Add Workload Identity Config.

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

Name: اسم وصفي، مثلاً azure-prod.
Cloud Provider: Azure.
Tenant ID: Directory (tenant) ID الخاص بـ Microsoft Entra من الخطوة 2.
Client ID: Application (client) ID الخاص بـ App Registration من الخطوة 2.
(اختياري) حدّد Set as default for Azure إذا كنت ترغب في أن يكون هذا هو تكوين WI الافتراضي المُحدَّد عند إنشاء بيانات اعتماد سر مدعومة بـ Azure.

Audience ثابت على api://AzureADTokenExchange — تتطلب Microsoft Entra هذا الجمهور بالضبط للبيانات الموحَّدة، لذا لا يظهر حقل Audience في النموذج.

انقر على Create.

الخطوة 7 — إضافة بيانات اعتماد مزود أسرار مرتبطة بتكوين WI

انتقل إلى Settings ← Secret Provider Credentials وانقر على Add Credential.

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

Name: اسم وصفي، مثلاً azure-prod-wi.
Provider: Azure Key Vault.
Authentication Method: Workload Identity.
Workload Identity Configuration: اختر التكوين الذي أنشأته في الخطوة 6.
Key Vault URL: اسم مضيف DNS للخزنة، مثلاً https://my-vault.vault.azure.net.
(اختياري) حدّد Set as default credential for this provider.

سيطلب النموذج فقط Key Vault URL ضمن Workload Identity — حقول بيانات الاعتماد الثابتة (Tenant ID و Client ID و Client Secret) مخفية عمداً لأنها لا تنطبق على هذا المسار؛ يأتي المستأجر والعميل من تكوين WI المرتبط.

انقر على Create.

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

بعد حفظ بيانات الاعتماد، انقر على Test Connection. لبيانات اعتماد workload-identity، يتحقق هذا من مصافحة OIDC: تُصدر CrewAI Platform JWT، وتُقدّمه إلى Microsoft Entra كـ client_assertion موحَّد، وتؤكد أن Entra تُعيد رمز وصول محصور بالخزنة. نتيجة خضراء تعني أن ارتباط الاتحاد سليم.

نجاح Test Connection يُثبت أن مُصدر Federated Identity Credential وموضوعه وجمهوره كلها متطابقة، وأن App Registration قابل للوصول. لا يُثبت ذلك أن RBAC لكل سر في Key Vault صحيح — يُمارَس getSecret على سر محدد بشكل منفصل عندما يُحَلّ متغير بيئة عند الإطلاق. راجع استكشاف الأخطاء لأنماط فشل المصافحة.

الخطوة 9 — الإشارة إلى السر في متغير بيئة

أَشِر إلى السر على أتمتة، تماماً كما تفعل مع أي متغير بيئة مدعوم بمدير أسرار. راجع استخدام مدير الأسرار لحقول النموذج والسلوك.

الخطوة 10 — التحقق من التدوير

بعد تشغيل عملية النشر، دوّر السر في Key Vault:

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

أطلق إطلاق أتمتة جديداً. ستكون بيئة الإطلاق ترى "rotated value" — بدون إعادة نشر ولا إعادة تشغيل عامل ولا انتظار TTL.

للتأكد في سجلات العامل، ابحث عن:

Workload identity config '<id>' (azure): N secret(s) resolved

يظهر هذا السطر لكل إطلاق ويُشير إلى استدعاء getSecret طازج مقابل Azure Key Vault.

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

استكشاف الأخطاء

العَرَض	السبب المحتمل
يفشل Test Connection بخطأ مصافحة	رفضت Microsoft Entra `client_assertion` الموحَّد. تحقق من أن Issuer في Federated Identity Credential يطابق قيمة `issuer` للمنصة بالضبط، وأن Subject هو `organization:<your-org-uuid>` (يطابق ادّعاء `sub` في JWT)، وأن Audience هو `api://AzureADTokenExchange`، وأن رابط اكتشاف OIDC للمنصة قابل للوصول من Entra عبر الإنترنت العام.
`AADSTS70021: No matching federated identity record found for presented assertion`	لا يتطابق Issuer + Subject + Audience في Federated Identity Credential مع الـ JWT بالضبط. تحقق من الخطوة 3 من جديد: يجب أن يكون الموضوع `organization:<your-org-uuid>` (يطابق ادّعاء `sub` في JWT)، ويجب أن يكون الجمهور `api://AzureADTokenExchange`.
`AADSTS700024: Client assertion is not within its valid time range`	ساعة مضيف CrewAI Platform منحرفة بشكل كبير عن الوقت الحقيقي. تحقق من NTP على المضيف.
`AADSTS50013: Assertion failed signature validation`	لم تستطع Microsoft Entra التحقق من توقيع الـ JWT. تأكد من أن `https://<your-platform-host>/oauth2/jwks` قابل للوصول من الإنترنت العام ويُقدّم JWKS صالحاً.
يُظهر الاقتراح التلقائي لاسم السر `Forbidden — does not have permission to perform action 'Microsoft.KeyVault/vaults/secrets/.../list'`	دور Key Vault Secrets User الخاص بـ App Registration محصور بسر واحد. امنح الدور على نطاق الخزنة ليُسمح بإجراء `list` في مستوى البيانات. راجع الخطوة 4.
يفشل الإطلاق في حلّ سر رغم نجاح Test Connection	ارتباط WI سليم، لكن RBAC لكل سر في Key Vault مفقود على السر الفاشل. راجع Key Vault Secrets User على ذلك السر تحديداً (أو وسّع تعيين الدور إلى نطاق الخزنة).
`Forbidden — request was not authorized` (الخزنة تستخدم سياسات الوصول القديمة)	لم يتم تحويل الخزنة إلى Azure RBAC. ضمن Access configuration للخزنة، عيّن نموذج الإذن إلى Azure role-based access control وأعد منح الدور من الخطوة 4.
`azure_vault_url is required for Azure secret resolution` (سجلات العامل)	تفتقد بيانات اعتماد مزود الأسرار إلى Key Vault URL. تحقق من الخطوة 7 من جديد.
لا تُلتقط القيمة المُدوَّرة في الإطلاق التالي	تأكد من أن متغير البيئة على الأتمتة يشير إلى بيانات اعتماد مدعومة بـ Workload Identity (وليس بيانات اعتماد بمفاتيح ثابتة). يدمج المسار الثابت القيم في صورة النشر.

روابط مرجعية

Microsoft: Microsoft Entra Workload Identity Federation overview
Microsoft: Configure a federated identity credential on an app
Microsoft: Azure Key Vault RBAC guide

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

استخدام الأسرار في متغيرات البيئة وإدارة الأذونات
للتنوع متعدد السحاب، إعداد ما يعادله لـ AWS موجود في AWS Workload Identity (اتحاد OIDC) وما يعادله لـ GCP في GCP Workload Identity Federation.

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

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

01-register-app.png — نموذج “Register an application” في بوابة Azure مع crewai-secrets-reader.
02-add-federated-credential.png — App Registration ← Certificates & secrets ← Federated credentials ← Add credential، مع Other issuer، رابط مُصدر المنصة، الموضوع organization:<uuid>، الجمهور api://AzureADTokenExchange.
03-grant-vault-rbac.png — Key Vault ← Access control (IAM) ← Add role assignment، مع Key Vault Secrets User و App Registration المختار.
04-per-secret-rbac.png — نفس النموذج لكن في نطاق IAM سر واحد (مسار أقل الامتيازات البديل).
05-amp-add-wi-config-azure.png — نموذج “Add Workload Identity Config” في CrewAI Platform مع Cloud Provider = Azure و Tenant ID و Client ID مأهولين.
06-amp-wi-list-with-azure.png — صفحة قائمة Workload Identity بعد الإنشاء، تُظهر صفوفاً لـ AWS و GCP وتكوين Azure الجديد.
07-amp-add-credential-azure-wi.png — نموذج “Add Secret Provider Credential” مع Provider = Azure Key Vault، Auth = Workload Identity، تكوين WI المختار، و Key Vault URL مأهول.