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

يستخدم Agent 365 CLI تطبيق مؤسسي Agent 365 CLI المؤسسي المدار من Microsoft بشكل افتراضي عندما يكون متاحا في المستأجر الخاص بك. تشرح هذه المقالة كيفية إكمال تسجيل تطبيق عميل مخصص ل Agent 365 CLI حتى تتمكن من مصادقة وتكوين الأداءات لتطبيق مملوك للمستأجر.

استخدم تطبيقا مخصصا مملوكا للمستأجر عندما:

  • لم يصل الطرح المرحلي لتطبيق المؤسسات المدار من Microsoft إلى المستأجر الخاص بك.
  • مؤسستك تتطلب تسجيل تطبيق مخصص للعميل.
  • يحدد تكوين Agent 365 الحالي تعيين مخصص clientAppId.

مهم

تنطبق هذه المادة فقط على تسجيل طلب مملوك للمستأجر. لا تطبق هذه الخطوات على تطبيق واجهة المستخدم Agent 365 المدارة من Microsoft (f54280f4-395e-4ea8-9e48-bf2d4952aa14). تتحقق واجهة سطر الأوامر (CLI) من صحة التطبيق المُدار من Microsoft دون تغيير تسجيله أو معرّفات URI لإعادة التوجيه أو الأذونات أو المطالبات الاختيارية أو منح الأذونات.

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

  1. طلب التسجيل
  2. تعيين رابط إعادة التوجيه
  3. انسخ معرف التطبيق (العميل)
  4. تكوين أذونات واجهة برمجة التطبيقاتيتطلب امتيازات المسؤول
  5. إضافة مطالبة دور الـ WIDS

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

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

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

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

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

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

نصيحة

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

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

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

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

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

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

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

  4. أدخل

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

      نصيحة

      لاستخدام هذا التطبيق كخيار احتياطي لا يتطلب إعدادًا لـ a365 setup all --agent-name، سمِّه بالضبط Agent 365 CLI. يستخدم مؤشر التحكم هذا الاسم بعد التحقق من تطبيق المؤسسات المدارة من Microsoft، لذا لا تحتاج إلى نسخ معرف العميل إلى ملف إعداد.

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

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

  5. حدد تسجيل.

تتطلب واجهة سطر الأوامر ثلاثة معرّفات URI لإعادة التوجيه في تطبيق مخصص يملكه المستأجر. عند تشغيلك لواجهة سطر الأوامر a365 setup requirements، يضيف تلقائيا أي عنصر مفقود.

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

راجع ما يهيئه CLI تلقائيا لتطبيق مخصص لمزيد من التفاصيل.

2. تعيين رابط إعادة التوجيه

  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. تكوين صلاحيات واجهة برمجة التطبيقات

مهم

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

ملحوظة

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

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

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

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

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

  1. في تسجيل التطبيق، اذهب إلى صلاحيات API.

  2. حدد إضافة إذن>Microsoft Graph>أذونات تم تفويضها.

    مهم

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

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

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

    ملحوظة

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

    لكل إذن:

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

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

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

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

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

الخيار ب: واجهة برمجة تطبيقات Microsoft Graph API (للحصول على صلاحيات النسخة التجريبية)

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

التحذير

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

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

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

  3. منح موافقة المسؤول باستخدام Graph API. لإكمال هذه الخطوة، تحتاج:

    • معرف الوحدة الخدمية تحتاج إلى SP_OBJECT_ID قيمة متغيرة.
    • معرف موارد الرسم البياني. تحتاج إلى GRAPH_RESOURCE_ID قيمة متغيرة.
    • إنشاء (أو تحديث) الأذونات المفوضة باستخدام نوع مورد oAuth2PermissionGrant مع قيم المتغيرات SP_OBJECT_IDGRAPH_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 الخاصة بك.

احصل على معرف موارد الرسم البياني الخاص بك

  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.

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

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

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

    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 على رؤية أذونات البيتا ويستبدل الموافقة الممنوحة من واجهة برمجة التطبيقات بالأذونات المرئية فقط.

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

عندما تظهر 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. قم بتعيين طريقة مستكشف الرسوم البيانية على PATCH واستخدم هذا الرابط مع 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 تطبيقك المخصص، فإنها تقرأ تعيينات الأدوار في دليل Entra الخاص بك مباشرةً من رمز الوصول لتحديد ما إذا كانت لديك امتيازات المسؤول. يتطلب هذا إضافة المطالبة wids إلى رموز الوصول المميزة الصادرة لتسجيل التطبيق الخاص بك.

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

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

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

  3. بالنسبة إلى نوع الرمز المميز، حدد الوصول.

  4. في قائمة المطالبات، حدد المربع بجوار wids.

  5. حدد إضافة.

    إذا تمت مطالبتك بتشغيل إذن Microsoft Graph profile لتمكين المطالبة، فحدد Yes، وأضف.

ملحوظة

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

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

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

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

من المستحسن القيام بما يلي:

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

لا:

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

ما الذي يهيئه مؤشر التحكم تلقائيا لتطبيق مخصص

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

عند اختيار تطبيق مخصص مملوك للمستأجر، a365 setup requirements يتم التحقق من تسجيل التطبيق وقد يحتاج إلى إجراء تغييرات. قبل تطبيق أي تغييرات، يعرض لك 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:

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

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

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

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

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

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

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

نصيحة

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

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

عَرَض: تشغيل a365 setup أو a365 setup requirements فشل مع أخطاء التحقق من الصحة حول تطبيق العميل المخصص.

الحل: استخدم هذه القائمة للتحقق من صحة تسجيل طلبك:

# Run requirements validation to see validation messages
a365 setup requirements

النتيجة المتوقعة: يعرض Custom client app validation successfulمؤشر التحكم (CLI) .

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

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

الصلاحيات المفوضة المطلوبة:

  • AgentIdentityBlueprint.ReadWrite.All [بيتا]
  • AgentIdentityBlueprintPrincipal.Create [بيتا]
  • AgentIdentity.Read.All [بيتا]
  • AgentIdentity.DeleteRestore.All [بيتا]
  • AgentRegistration.ReadWrite.All
  • Application.Read.All
  • User.Read

عَرَض: فشل التحقق من الصحة على الرغم من أنك أضفت أذونات.

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

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

الأعراض: 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>

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

الحل:

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

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

بعد أن يمنح المدير الموافقة، قم بتشغيل a365 setup all --agent-name <name> مرة أخرى.

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

نوع الإذن خاطئ

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

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

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

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

لماذا تم تفويضه؟

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

الحل:

  1. انتقل إلى مركز مسؤولي Microsoft Entra>App registrations> أذونات تطبيقك >API
  2. قم بإزالة أي صلاحيات تطبيق. تظهر هذه الأذونات ك Application في عمود النوع .
  3. أضف نفس الأذونات كالأذونات المفوضة.
  4. امنح موافقة الإدارة مرة أخرى.

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

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

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

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

الحل:

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

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

عَرَض: تقارير CLI تحتوي على Application not found أو Invalid client ID أخطاء.

الحل:

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

    • انتقل إلى مركز مسؤولي Microsoft Entra>App registrations> تطبيقك >Overview
    • انسخ القيمة تحت معرف التطبيق (العميل)
    • يجب أن يكون الصيغة: 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