تسجيل تطبيق العميل المخصص لـ Agent 365 CLI

يحتاج Agent 365 CLI إلى تسجيل تطبيق عميل مخصص في مستأجر Microsoft Entra ID الخاص بك لتوثيق وإدارة مخططات هوية العامل.

تقسم هذه المقالة العملية إلى أربع خطوات رئيسية:

  1. تسجيل التطبيق
  2. تعيين عنوان ‎URI لإعادة التوجيه‬‏
  3. نسخ معرف التطبيق (العميل).
  4. تكوين صلاحيات واجهة برمجة التطبيقاتيتطلب صلاحيات المسؤول
  5. إضافة المطالبة بدور wids

إذا واجهت مشاكل، راجع قسم استكشاف الأخطاء.

المتطلبات

قبل أن تبدأ، تأكد من أن لديك إمكانية الوصول إلى مركز مسؤولي Microsoft Entra وإذا لزم الأمر، أحد أدوار الإدارة المطلوبة لمنح الموافقة.

لتسجيل التطبيق

بشكل افتراضي، يمكن لأي مستخدم في المستأجر تسجيل التطبيقات في مركز مسؤولي Microsoft Entra ومع ذلك، يمكن لمسؤولي المستأجر تقييد هذه القدرة. إذا لم تتمكن من تسجيل تطبيقك، تواصل مع المسؤول الخاص بك.

تحتاج إلى أحد هذه الأدوار الإدارية لـ . تكوين أذونات API.

تلميح

ليس لديك حق الوصول إلى المسؤول؟ يمكنك إكمال الخطوات 1-3 بنفسك، ثم تطلب من مدير المستأجر إكمال الخطوة 4. زودهم بمعرف التطبيق (العميل) من الخطوة 3 ورابطا لقسم تكوين صلاحيات API .

تلميح

يمكن للمسؤولين العموميين تخطي التسجيل اليدوي. شغّل a365 setup requirements، وإذا لم يتم العثور على تطبيق Agent 365 CLI في مستأجر الخدمة لديك، ستطلب منك واجهة سطر الأوامر إنشاءه ومنح موافقة المسؤول تلقائيًا. اكتب C عند ظهور المؤشر لإنشاء التطبيق في خطوة واحدة. إذا استخدمت هذا المسار الآلي، يمكنك تخطي الخطوات في هذا القسم.

1. تسجيل التطبيق

تلخص هذه التعليمات التعليمات الكاملة لإنشاء تسجيل التطبيق .

  1. الانتقال إلى مركز مسؤولي Microsoft Entra

  2. حدد تسجيلات التطبيق

  3. حدد تسجيل جديد

  4. إدخَال:

    • الاسم: أدخل اسما ذا معنى لتطبيقك، مثل my-agent-app. يرى مستخدمو التطبيق هذا الاسم، ويمكنك تغييره في أي وقت. يمكنك أن تسجل عدة تطبيقات بنفس الاسم.

      تلميح

      إذا أردت استخدام تدفق بدون إعدادات a365 setup all --agent-name، سم التطبيق بالضبط Agent 365 CLI. يقوم CLI (سطر الأوامر) تلقائيًا بالبحث عن تطبيق العميل باستخدام هذا الاسم المعروض المعروف، لذا لن تحتاج إلى نسخ معرف العميل إلى ملف الإعدادات.

    • أنواع الحسابات المدعومة: الحسابات الموجودة فِي هذا الدليل التنظيمي فقط (مستأجر واحد).

    • معرّف URI لإعادة التوجيه: اختر العميل العام/الأصلي (الجوال سطح المكتب) وأدخل http://localhost:8400/

  5. حدد تسجيل

يتطلب CLI ثلاثة معرّفات URI لإعادة التوجيه إجمالاً. تضيف CLI تلقائيا أي شيء مفقود عند تشغيل a365 setup requirements:

URI الغرض
http://localhost:8400/ مكتبة مصادقة Microsoft(MSAL) المصادقة التفاعلية عبر المتصفح
http://localhost Microsoft Graph PowerShell SDK Connect-MgGraph
ms-appx-web://Microsoft.AAD.BrokerPlugin/{client-id} استخدام مدير حسابات الويب (WAM)

راجع ما يقوم CLI بإعداده تلقائيًا لمزيد من التفاصيل.

2. تعيين عنوان ‎URI لإعادة التوجيه‬‏

  1. انتقل إلى نظرة عامة وانسخ قيمة معرف التطبيق (العميل).
  2. انتقل إلى المصادقة (إصدار أولي) وحدد إضافة رابط إعادة التوجيه.
  3. اختر تطبيقات الأجهزة المحمولة وسطح المكتب واضبط القيمة على ms-appx-web://Microsoft.AAD.BrokerPlugin/{client-id}، حيث {client-id} هو معرف التطبيق (العميل) الذي نسخته.
  4. حدد تكوين لإضافة قيمة.

3. نسخ معرف التطبيق (العميل)

من صفحة نظرة عامة على التطبيق، انسخ معرف التطبيق (العميل) بتنسيق GUID. تستخدم هذه القيمة عند تشغيل a365 setup all أو عند إنشاء a365.config.json يدويًا.

تلميح

لا تخلط بين هذه القيمة مع معرف الكائن — فأنت بحاجة إلى معرف التطبيق (العميل).

إذا قمت بتسمية تطبيقك Agent 365 CLI في الخطوة 1، يمكنك تخطي هذه الخطوة عند استخدام a365 setup all --agent-name. يحدد سطر الأوامر معرف العميل تلقائيًا بناءً على اسم العرض.

4. تكوين أذونات API

مهم

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

إشعار

حتى ديسمبر 2025، يكون أذونات AgentIdentityBlueprint.* وAgentInstance.*و AgentIdentity.* هي واجهات برمجة تطبيقات تجريبية وقد لا تكون مرئية في مركز مسؤولي Microsoft Entra الخاص بها. إذا أصبحت هذه الأذونات متاحة بشكل عام في مستأجرك، يمكنك استخدام الخيار أ لجميع الأذونات.

اختر الطريقة المناسبة:

  • الخيار أ: استخدم مركز مسؤولي Microsoft Entra لجميع الأذونات (إذا كانت أذونات البيتا مرئية)
  • الخيار ب: استخدام واجهة برمجة تطبيقات Microsoft Graph لإضافة جميع الأذونات (ينصح به إذا لم تكن صلاحيات النسخة التجريبية مرئية)

الخيار أ: مركز مسؤولي Microsoft Entra (الطريقة القياسية)

استخدم هذه الطريقة إذا كانت أذونات البيتا مرئية في مستأجرك.

  1. على تسجيل التطبيق، انتقل إلى أذونات واجهة API.

  2. حدد إضافة إذن>Microsoft Graph>الأذونات المفوضة‬‏‫.

    مهم

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

  3. أضف هذه الأذونات السبعة واحدة تلو الأخرى:

    إذن الغرض
    AgentIdentityBlueprint.ReadWrite.All إنشاء Blueprint، إدارة أسرار العميل، الأذونات الوراثية، بيانات الهوية الموحدة، والحذف (واجهة برمجة التطبيقات التجريبية)
    AgentIdentityBlueprintPrincipal.Create إنشاء مبدأ خدمة Agent Blueprint (API التجريبي)
    AgentIdentity.Read.All التحقق من خاصية التكرار والبحث عن كيان خدمة هوية العامل (واجهة API التجريبية)
    AgentIdentity.DeleteRestore.All حذف كيانات خدمة كيان العامل أثناء عملية التنظيف (واجهة API التجريبية)
    AgentRegistration.ReadWrite.All قراءة وكتابة جميع تسجيلات العاملين
    Application.Read.All البحث عن أصل الخدمة حسب معرف التطبيق (بديل أضيق لـ Directory.Read.All)
    User.Read قراءة ملف تعريف المستخدم الذي سجل الدخول لمالك المخطط وتعيين الراعي

    إشعار

    AgentRegistration.ReadWrite.All مطلوب لإعداد عامل. يقوم مدقق CLI بالتحقق من هذا الإذن بشكل صريح. يجب أن تكون هذه الصلاحية موجودة في تسجيل التطبيق وأن يتم منح موافقة المسؤول عليها.

    لكل إذن:

    • في مربع البحث، اكتب اسم الإذن (على سبيل المثال، AgentIdentityBlueprint.ReadWrite.All).
    • ضع علامة على مربع الاختيار بجانب الإذن.
    • حدد إضافة أذونات.
    • كرر ذلك لجميع الأذونات السبعة.

  4. حدد منح موافقة المسؤول لـ [مستأجرك].

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

  5. تحقق من أن جميع الأذونات تظهر عليها علامات صحة خضراء تحت حالة.

إذا لم تكن أذونات البيتا (AgentIdentityBlueprint.*) ظاهرة، انتقل إلى الخيار ب.

الخيار ب: واجهة برمجة تطبيقات Microsoft Graph (لأذونات بيتا)

استخدم هذه الطريقة إذا لم يُظهر مركز مسؤولي Microsoft Entra AgentIdentityBlueprint.* الأذونات.

تحذير

إذا استخدمت هذه الطريقة من واجهة برمجة التطبيقات، لا تستخدم زر "منح موافقة المسؤول" في مركز مسؤولي Microsoft Entra بعد ذلك. طريقة API تمنح موافقة المسؤول تلقائيا، وباستخدام زر مركز مسؤولي Microsoft Entra يحذف أذونات البيتا الخاصة بك. لمزيد من المعلومات، راجع اختفاء أذونات البيتا.

  1. افتح مستكشف الرسومات البيانية.

  2. سجّل الدخول بحساب المسؤول الخاص بك (مسؤول التطبيق أو مسؤول التطبيقات السحابية).

  3. امنح الموافقة الإدارية باستخدام واجهة Microsoft Graph البرمجية. لإكمال هذا البرنامج، تحتاج إلى ما يلي:

    • معرف كيان الخدمة. تحتاج إلى قيمة المتغير SP_OBJECT_ID.
    • معرّف مورد Graph تحتاج إلى قيمة المتغير GRAPH_RESOURCE_ID.
    • إنشاء (أو تحديث) الأذونات المفوضة باستخدام نوع مورد oAuth2PermissionGrantمع SP_OBJECT_IDقيم المتغيراتGRAPH_RESOURCE_ID.

استخدم المعلومات الواردة في الأقسام التالية لإكمال هذه الخطوات.

احصل على معرف الخدمة الرئيسي

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

  1. اضبط طريقة مستكشف الرسوم البيانية على GET واستخدم هذا الرابط. استبدل <YOUR_CLIENT_APP_ID> بمعرف تطبيق العميل الفعلي الخاص بك من الخطوة 3: نسخ معرف تطبيق (العميل) :

    https://graph.microsoft.com/v1.0/servicePrincipals?$filter=appId eq '<YOUR_CLIENT_APP_ID>'&$select=id

  2. حدد تشغيل الاستعلام.

    • إذا نجح الاستعلام، فإن القيمة التي تم إرجاعها هي SP_OBJECT_ID الخاصة بك.

    • إذا فشل الاستعلام بسبب خطأ في الأذونات، فحدد علامة التبويب تعديل الأذونات، ووافق على الأذونات المطلوبة، ثم حدد تشغيل الاستعلام مرة أخرى. القيمة المرتجعة هي SP_OBJECT_ID.

    • إذا أعاد الاستعلام نتائج فارغة ("value": [])، أنشئ مبدأ الخدمة باستخدام الخطوات التالية:

      1. قم بتعيين الطريقة إلى POST واستخدم هذا العنوان:

        https://graph.microsoft.com/v1.0/servicePrincipals

        جسم الطلب (استبدل YOUR_CLIENT_APP_ID بمعرف العميل الفعلي الخاص بك):

        {
   "appId": "YOUR_CLIENT_APP_ID"
}

      2. حدد تشغيل الاستعلام. يجب أن تحصل على 201 Created رد. idالقيمة المرتجعة هي SP_OBJECT_ID.

احصل على معرف موارد Microsoft Graph الخاص بك

  1. اضبط طريقة مستكشف الرسوم البيانية على GET واستخدم هذا الرابط.

    https://graph.microsoft.com/v1.0/servicePrincipals?$filter=appId eq '00000003-0000-0000-c000-000000000000'&$select=id

  2. حدد تشغيل الاستعلام.

    • إذا نجح الاستعلام، انسخ القيمة id. هذه القيمة هي GRAPH_RESOURCE_ID.
    • إذا فشل الاستعلام بسبب خطأ في الأذونات، فحدد علامة التبويب تعديل الأذونات، ووافق على الأذونات المطلوبة، ثم حدد تشغيل الاستعلام مرة أخرى. انسخ القيمة id. هذه القيمة هي GRAPH_RESOURCE_ID.

إنشاء الأذونات المفوضة

تمنح عملية استدعاء API هذه موافقة المسؤول على مستوى المستأجر لجميع الأذونات السبعة، بما في ذلك أذونات الإصدار التجريبي (Beta) التي لا تظهر في مركز مسؤولي Microsoft Entra.

  1. عيّن الطريقة في مستكشف Graph إلى POST واستخدم عنوان URL ونص الطلب التاليين:

    https://graph.microsoft.com/v1.0/oauth2PermissionGrants

    نص الطلب:

    {
"clientId": "<SP_OBJECT_ID>",
"consentType": "AllPrincipals",
"principalId": null,
"resourceId": "<GRAPH_RESOURCE_ID>",
"scope": "AgentIdentityBlueprint.ReadWrite.All AgentIdentityBlueprintPrincipal.Create AgentIdentity.Read.All AgentIdentity.DeleteRestore.All AgentRegistration.ReadWrite.All Application.Read.All User.Read"
}

  2. حدد تشغيل الاستعلام.

    • إذا تلقيت 201 Created ردا: نجاح! يعرض حقل scope في الرد جميع أسماء الأذونات السبعة. لقد انتهيت.
    • إذا فشل الاستعلام بسبب خطأ في الأذونات، انتقل إلى تبويب "تعديل الأذونات"، وامنح الموافقة على الأذونات المطلوبة، ثم اختر "تشغيل الاستعلام" مرة أخرى.
    • Request_MultipleObjectsWithSameKeyValue إذا حصلت على خطأ: تم منح الإذن مسبقًا. قد يكون شخص ما قد أضاف الأذونات مسبقًا. راجع التحديث التالي للأذونات المفوضة.

تحذير

يشير consentType: "AllPrincipals" في POSTالطلب إلى منح موافقة المسؤول على مستوى المستأجر بالفعل. لا تقم باختيار "منح موافقة المسؤول" في مركز إدارة Microsoft Entra بعد استخدام هذه الطريقة - فهذا يحذف صلاحيات البيتا لأن مركز إدارة Microsoft Entra لا يستطيع رؤية صلاحيات البيتا ويكتب فوق موافقتك الممنوحة من API باستخدام الأذونات الظاهرة فقط.

تحديث الأذونات المفوضة

في حال ظهور Request_MultipleObjectsWithSameKeyValue خطأ عند اتباع خطوات إنشاء الأذونات المفوضة، استخدم هذه الخطوات لتحديث الأذونات المفوضة.

  1. اضبط طريقة مستكشف الرسوم البيانية على GET واستخدم هذا الرابط.

    https://graph.microsoft.com/v1.0/oauth2PermissionGrants?$filter=clientId eq 'SP_OBJECT_ID_FROM_ABOVE'

  2. حدد تشغيل الاستعلام. انسخ قيمة id من الرد. هذه القيمة هي YOUR_GRANT_ID.

  3. قم بتعيين طريقة Graph Explorer إلى PATCH واستخدم هذا العنوان URL مع YOUR_GRANT_ID.

    https://graph.microsoft.com/v1.0/oauth2PermissionGrants/<YOUR_GRANT_ID>

    نص الطلب:

    {
   "scope": "AgentIdentityBlueprint.ReadWrite.All AgentIdentityBlueprintPrincipal.Create AgentIdentity.Read.All AgentIdentity.DeleteRestore.All AgentRegistration.ReadWrite.All Application.Read.All User.Read"
}

  4. حدد تشغيل الاستعلام. يجب أن تحصل على 200 OK رد يحتوي على جميع الأذونات السبعة في scope الحقل.

5. إضافة المطالبة بدور wids

تقرأ Agent 365 CLI تعيينات أدوار دليل Entra مباشرةً من رمز الوصول لتحديد ما إذا كانت لديك امتيازات المسؤول. يتطلب ذلك إضافة مطالبة wids إلى رموز الوصول المميزة الصادرة لتسجيل تطبيقك.

بدون هذه المطالبة، لا يمكن لـ CLI اكتشاف دورك ويعود إلى عرض تعليمات PowerShell لكل خطوة تتطلب امتيازات المسؤول — حتى عندما تكون أنت المسؤول. أكمل هذه الخطوة للحصول على السلوك الصحيح.

  1. في تسجيل تطبيقك، انتقل إلى تكوين الرمز المميز.

  2. حدد إضافة مطالبة اختيارية.

  3. بالنسبة لـ نوع الرمز المميز، اختر الوصول.

  4. في قائمة المطالبات، ضع علامة على المربع بجانب wids.

  5. حدد إضافة.

    إذا طُلب منك تفعيل إذن Microsoft Graphprofile لتمكين المطالبة، اختر "نعم، أضف".

إشعار

يحتوي مطالبة wids على معرّفات GUID لقوالب الأدوار الخاصة بأدوار دليل Entra المعينة مباشرة للمستخدم الذي قام بتسجيل الدخول. يستخدم CLI الـ GUIDs لاكتشاف أدوار مسؤول المسؤول العمومي ومسؤول معرف العامل دون الحاجة إلى استدعاء Graph API إضافي.

القيد:wids يعكس فقط الأدوار المعينة مباشرة. إذا كان المستأجر لديك يعيّن أدوار الدليل من خلال مجموعات أمان قابلة لتعيين الأدوار، فقد لا تكتشف واجهة سطر الأوامر تلك التعيينات القائمة على المجموعات. التعيين المباشر للأدوار هو النمط القياسي لكل من مطوّر معرف الوكيل والمسؤولين.

أفضل ممارسات الأمان

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

المسموح:

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

الممنوع:

  • امنح أذونات التطبيق. استخدم فقط التفويض.
  • شارك معرّف العميل علنا.
  • امنح أذونات أخرى غير ضرورية.
  • استخدم التطبيق لأغراض أخرى.

ما الذي يهيئه نظام CLI تلقائيا

عند تشغيل a365 setup requirements، يقوم CLI بالتحقق من تسجيل التطبيق وقد يحتاج إلى إجراء تغييرات. قبل تطبيق أي تغييرات، يعرض لك CLI ملخصًا ويطلب منك التأكيد:

WARNING: The CLI needs to make the following changes to your app registration (<app-id>):

  - Add redirect URI(s): http://localhost
  - Enable 'Allow public client flows' (isFallbackPublicClient = true)

Do you want to proceed? (y/N):

لتجاوز طلب التأكيد (على سبيل المثال، في بيئة CI)، استخدم العلامة --yes :

a365 setup requirements --yes

الجدول التالي يصف كل تغيير قد يقوم به مؤشر التحكم (CLI):

تغيير السبب
إضَافة عنوان URL لإعَادة التوجيهhttp://localhost تتطلب مجموعة تطوير البرمجيات Microsoft Graph PowerShell معرّف إعادة التوجيه هذا للمصادقة عبر المتصفح. بدونه، تعود عمليات منح OAuth2 إلى رمز يفتقر إلى الأذونات المفوضة المطلوبة وتفشل مع رمز الخطأ 403.
إضَافة عنوان URL لإعَادة التوجيهhttp://localhost:8400/ تتطلب مكتبة MSAL معرّف إعادة التوجيه هذا للمصادقة التفاعلية عبر المتصفح.
إضَافة عنوان URL لإعَادة التوجيهms-appx-web://Microsoft.AAD.BrokerPlugin/{id} مطلوب لمدير حساب الويب (WAM)، وهو وسيط مصادقة لنظام التشغيل Windows. تعرف على المزيد حول الحصول على الرموز المرتبطة بالأجهزة.
تفعيل "السماح بتدفقات العملاء العامة" مطلوب لمصادقة رمز احتياطية على macOS وLinux ونظام Windows الفرعي لـ Linux ‏(WSL) والبيئات بدون رأس وكبديل في نهج الوصول المشروط على Windows.
أضف الأذونات في تسجيل التطبيق يحافظ على تزامن تسجيل التطبيق مع الأذونات المطلوبة الجديدة بعد تحديث CLI.
توسيع منح موافقة المسؤول يوسع نطاق منح الإذن الحالي لـ OAuth2 ليشمل أي أذونات جديدة تم توفيرها.

إذا رفضت الإشعار، فإن CLI لن يعدل تسجيل تطبيقك. إذا كانت هناك تغييرات مطلوبة لعمل واجهة سطر الأوامر، يمكنك تكوينها يدويًا في مركز مسؤولي Microsoft Entra أو إعادة التنفيذ باستخدام --yes.

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

بعد تسجيل تطبيق العميل المخصص الخاص بك، استخدمه مع Agent 365 CLI لإكمال إعداد Agent 365 الخاص بك:

بدء استخدام تطوير Agent 365

استكشاف الأخطاء وإصلاحها

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

تلميح

دليل استكشاف أخطاء Agent 365 يتضمن توصيات عالية المستوى لاستكشاف الأخطاء وحلها، وأفضل الممارسات، وروابط لمحتوى استكشاف الأخطاء لكل جزء من دورة تطوير Agent 365.

يفشل التحقق من صحة CLI أثناء التكوين.

الأعراض: تشغيل a365 setup أو a365 setup requirements يؤدي إلى ظهور أخطاء في التحقق من صحة تطبيق العميل المخصص الخاص بك.

الحل: استخدم قائمة التحقق التالية لمراجعة صحة تسجيل تطبيقك:

# Run requirements validation to see validation messages
a365 setup requirements

النتيجة المتوقعة: يعرض CLI Custom client app validation successful.

إذا لم تحصل على النتيجة المتوقعة، تحقق من كل من العناصر التالية:

فحص كيفية التحقق Fix
✅ تم استخدام المعرف الصحيح لقد نسخت معرف التطبيق (العميل) (وليس معرف الكائن) انتقل إلى التطبيق نظرة عامة في مركز مسؤولي Microsoft Entra
✅ أذونات مفوضة تُعرض الأذونات النوع: تفويض ضمن أذونات واجهة برمجة التطبيقات راجع نوع الإذن غير الصحيح
✅ تمت إضافة جميع الأذونات اطلع على جميع الأذونات المدرجة أدناه اتبع الخطوة 4 مرة أخرى
✅ منح موافقة المسؤول جميعها تظهر علامة صح خضراء تحت الحالة انظر موافقة المسؤول التي تم منحها بشكل خاطئ

الأذونات المفوضة المطلوبة:

  • AgentIdentityBlueprint.ReadWrite.All [Beta]
  • AgentIdentityBlueprintPrincipal.Create [Beta]
  • AgentIdentity.Read.All [Beta]
  • AgentIdentity.DeleteRestore.All [Beta]
  • AgentRegistration.ReadWrite.All
  • Application.Read.All
  • User.Read

العَرَض: التحقق لا ينجح رغم إضافة الأذونات.

السبب الجذري: لم يتم منح موافقة المسؤول، أو تم منحها بصورة غير صحيحة.

الحل: عند تسجيل التطبيق في مركز إدارة Microsoft Entra، اذهب إلى أمنيات API واختر منح موافقة المسؤول ل [Your Tenant]. تحقق من أن جميع الأذونات تظهر عليها علامات صحة خضراء تحت حالة.

العرض: a365 setup all يطبع "تم ضمان موافقة التطبيق المفوضة بنجاح" لكنه يفشل فورا أثناء إنشاء المخطط مع:

Admin consent has not been granted for this application.
Share this URL with an Application Administrator or Global Administrator to grant consent:
  https://login.microsoftonline.com/<tenant-id>/v2.0/adminconsent?client_id=<client-app-id>

السبب الجذري: يوجد بالفعل oauth2PermissionGrantسجل لتطبيق العميل المخصص الخاص بك في المستأجر لديك (من تشغيل إعداد جزئي سابق، أو من إجراء "منح موافقة المسؤول" في مركز مسؤولي Microsoft Entra لنطاقات أخرى)، ولكن هذا السجل لا يحتوي على النطاق المطلوب (AgentIdentityBlueprint.ReadWrite.All). يكتشف CLI النطاق المفقود ويُظهر رابط الموافقة لمسؤول لإكمال منح الموافقة.

الحل:

شارك رابط الموافقة المعروض في ناتج الخطأ مع مسؤول التطبيق أو المسؤول العام. يكون الرابط على الشكل التالي:

https://login.microsoftonline.com/<tenant-id>/v2.0/adminconsent?client_id=<client-app-id>

بعد أن يمنح المسؤول الموافقة، أعد تنفيذ a365 setup all --agent-name <name>.

إذا كانت لديك صلاحية المسؤول، يمكنك فتح الرابط مباشرة في المتصفح لمنح الموافقة دون انتظار.

نوع الإذن غير الصحيح

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

السبب الجذري: أضفت أذونات التطبيق بدلاً من الأذونات المفوضة.

يشرح هذا الجدول أنواع الأذونات المختلفة.

نوع الإذن وقت الاستخدام كيف يستخدمه عامل Agent 365 CLI
تفويض ("النطاق") يسجل المستخدم الدخول بشكل تفاعلي Agent 365 CLI يستخدم هذا - أنت تسجل الدخول، وتعمل CLI نيابة عنك
التطبيق ("الدور") الخدمة تعمل بدون مستخدم لا تستخدم - فقط للخدمات الخلفية أو الشياطين

لماذا الإذن المفوض؟

  • تقوم بتسجيل الدخول بشكل تفاعلي (مصادقة المتصفح)
  • تنفذ CLI الإجراءات باسمك (سجلات التدقيق تظهر هويتك)
  • أكثر أمانًا: محدودة بصلاحياتك الفعلية
  • يضمن المساءلة والامتثال

الحل:

  1. انتقل إلى مركز مسؤولي Microsoft Entra> تسجيل التطبيقات> تطبيقك نظرة عامة>
  2. قم بإزالة أي أذونات تطبيق. تظهر هذه الأذونات كـ تطبيق في عمود النوع.
  3. أضف نفس الأذونات مثل الأذونات المفوضة.
  4. امنح موافقة المسؤول مجددا.

العرض: استخدمت الخيار ب: واجهة برمجة تطبيقات Microsoft Graph (لأذونات النسخة التجريبية) لإضافة أمنيات بيتا، لكنها تختفي بعد اختيار منح موافقة المدير في مركز إدارة Microsoft Entra.

السبب الجذري: مركز مسؤولي Microsoft Entra لا يعرض أذونات النسخة التجريبية في واجهة المستخدم. عند تحديد منح موافقة المسؤول، يمنح البوابة الموافقة فقط للأذونات المرئية وتستبدل الموافقة الممنوحة عبر واجهة برمجة التطبيقات.

لماذا يحدث هذا:

  1. تستخدم واجهة برمجة تطبيقات Microsoft Graph (الخيار ب) لإضافة جميع الأذونات السبعة، بما في ذلك الأذونات التجريبية.
  2. استدعاء واجهة برمجة التطبيقات مع consentType: "AllPrincipals"يمنح بالفعل موافقة المسؤول على النطاق الكامل للمستأجر.
  3. تذهب إلى مركز مسؤولي Microsoft Entra وترى فقط جزءًا من الأذونات لأن الأذونات التجريبية غير مرئية في البوابة.
  4. تحدد منح موافقة المسؤول أنك بحاجة لذلك.
  5. يقوم مركز إدارة Microsoft Entra بالكتابة فوق الموافقة الممنوحة من واجهة برمجة التطبيقات الخاصة بك بالأذونات المرئية فقط.
  6. تم حذف أذونات بيتا الخاصة بك.

الحل:

  • لا تستخدم موافقة مدير مركز مسولي Microsoft Entra بعد طريقة API: طريقة API تمنح موافقة المسؤول بالفعل.
  • إذا حذفت أذونات البيتا عن طريق الخطأ، أعد تشغيل الخيار B الخطوة 3 (منح موافقة المسؤول باستخدام واجهة Graph API) لاستعادتها. إذا ظهرت Request_MultipleObjectsWithSameKeyValue لك خطأ، اتبع الخطوات لتحديث الأذونات المفوضة .
  • للتحقق من إدراج الأذونات السبعة، تحقق من حقل scope في استجابة POST أو PATCH.

لم يتم العثور على التطبيق أثناء التحقق

العرض: تقارير CLIApplication not found أو أخطاء Invalid client ID.

الحل:

  1. تحقق من أنك نسخت معرف التطبيق (العميل) بصيغة GUID، وليس معرف الكائن:

    • انتقل إلى مركز مسؤولي Microsoft Entra>تسجيلات التطبيق> تطبيقك >نظرة عامة
    • انسخ القيمة ضمن معرف التطبيق (العميل)
    • يجب أن يكون التنسيق: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

  2. تحقق من وجود التطبيق في المستأجر الخاص بك:

    # Sign in to the correct tenant
az login

# List your app registrations
az ad app list --display-name "<The display name of your app>"

تعرف على كيفية تسجيل تطبيق في Microsoft Entra ID.

  • Last updated on