استخدام واجهات برمجة تطبيقات Microsoft Defender لنقطة النهاية

هام

لا يتم تضمين قدرات التتبع المتقدمة في Defender for Business.

ملاحظة

إذا كنت أحد عملاء حكومة الولايات المتحدة، فاستخدم معرفات URI المدرجة في Microsoft Defender لنقطة النهاية لعملاء حكومة الولايات المتحدة.

تلميح

للحصول على أداء أفضل، بدلا من استخدام api.security.microsoft.com، استخدم خادما أقرب إلى الموقع الجغرافي الخاص بك:

• us.api.security.microsoft.com
• eu.api.security.microsoft.com
• uk.api.security.microsoft.com
• au.api.security.microsoft.com
• swa.api.security.microsoft.com
• ina.api.security.microsoft.com
• aea.api.security.microsoft.com

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

إذا كنت بحاجة إلى الوصول البرمجي Microsoft Defender لنقطة النهاية بدون مستخدم، فراجع Access Microsoft Defender لنقطة النهاية مع سياق التطبيق.

إذا لم تكن متأكدا من الوصول الذي تحتاجه، فاقرأ صفحة المقدمة.

يعرض Microsoft Defender لنقطة النهاية الكثير من بياناته وإجراءاته من خلال مجموعة من واجهات برمجة التطبيقات البرمجية. تمكنك واجهات برمجة التطبيقات هذه من أتمتة تدفقات العمل والابتكار استنادا إلى قدرات Microsoft Defender لنقطة النهاية. يتطلب الوصول إلى واجهة برمجة التطبيقات مصادقة OAuth2.0. لمزيد من المعلومات، راجع تدفق رمز التخويل OAuth 2.0.

بشكل عام، تحتاج إلى اتخاذ الخطوات التالية لاستخدام واجهات برمجة التطبيقات:

• إنشاء تطبيق Microsoft Entra
• الحصول على رمز مميز للوصول باستخدام هذا التطبيق
• استخدم الرمز المميز للوصول إلى Defender لواجهة برمجة تطبيقات نقطة النهاية

تشرح هذه الصفحة كيفية إنشاء تطبيق Microsoft Entra، والحصول على رمز مميز للوصول إلى Microsoft Defender لنقطة النهاية والتحقق من صحة الرمز المميز.

ملاحظة

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

تلميح

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

إنشاء تطبيق

1. سجّل الدخول إلى مدخل Azure.

2. انتقل إلى تسجيلات>Microsoft Entra ID> Appتسجيل جديد.

   

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

   • الاسم - أدخل اسم تطبيق ذي معنى يتم عرضه لمستخدمي التطبيق.

   • أنواع الحسابات المدعومة - حدد الحسابات التي تريد أن يدعمها تطبيقك.

     
     

     أنواع الحسابات المدعومة	الوصف
     الحسابات في هذا الدليل التنظيمي فقط	حدد هذا الخيار إذا كنت تقوم بإنشاء تطبيق خط عمل (LOB). لا يتوفر هذا الخيار إذا كنت لا تسجل التطبيق في دليل. يعين هذا الخيار إلى مستأجر واحد Microsoft Entra فقط. هذا الخيار هو الخيار الافتراضي ما لم تكن تقوم بتسجيل التطبيق خارج الدليل. في الحالات التي يتم فيها تسجيل التطبيق خارج دليل، يكون الافتراضي هو Microsoft Entra حسابات Microsoft متعددة المستأجرين والشخصية.
     الحسابات في أي دليل تنظيمي	حدد هذا الخيار إذا كنت ترغب في استهداف جميع عملاء الأعمال والتعليم. يتم تعيين هذا الخيار إلى Microsoft Entra متعدد المستأجرين فقط. إذا قمت بتسجيل التطبيق كمستأجر واحد Microsoft Entra فقط، يمكنك تحديثه ليكون Microsoft Entra متعدد المستأجرين والعودة إلى مستأجر واحد من خلال شفرة المصادقة.
     الحسابات في أي دليل تنظيمي وحسابات Microsoft الشخصية	حدد هذا الخيار لاستهداف أوسع مجموعة من العملاء. يعين هذا الخيار Microsoft Entra حسابات Microsoft متعددة المستأجرين والشخصية. إذا قمت بتسجيل التطبيق كحسابات Microsoft متعددة المستأجرين وشخصية Microsoft Entra، فلا يمكنك تغيير ذلك في واجهة المستخدم. بدلا من ذلك، يجب استخدام محرر بيان التطبيق لتغيير أنواع الحسابات المدعومة.

   • إعادة توجيه URI (اختياري) - حدد نوع التطبيق الذي تقوم ببناءه، عميل ويب أو عميل عام (& المحمول لسطح المكتب)، ثم أدخل عنوان URI لإعادة التوجيه (أو عنوان URL للرد) لتطبيقك.

     • بالنسبة لتطبيقات الويب، قم بتوفير عنوان URL الأساسي لتطبيقك. على سبيل المثال، http://localhost:31544 قد يكون عنوان URL لتطبيق ويب يعمل على جهازك المحلي. سيستخدم المستخدمون عنوان URL هذا لتسجيل الدخول إلى تطبيق عميل ويب.

     • بالنسبة لتطبيقات العميل العامة، قم بتوفير URI المستخدم من قبل Microsoft Entra ID لإرجاع استجابات الرمز المميز. أدخل قيمة خاصة بتطبيقك، مثل myapp://auth.

     للاطلاع على أمثلة محددة لتطبيقات الويب أو التطبيقات الأصلية، راجع عمليات التشغيل السريع الخاصة بنا.

     عند الانتهاء، حدد Register.

4. السماح للتطبيق الخاص بك بالوصول إلى Microsoft Defender لنقطة النهاية وتعيين إذن "قراءة التنبيهات":

   • في صفحة التطبيق الخاص بك، حدد API Permissions>Add permission>APIs my organization uses> type WindowsDefenderATP وحدد على WindowsDefenderATP.

     ملاحظة

     لا يظهر WindowsDefenderATP في القائمة الأصلية. ابدأ بكتابة اسمه في مربع النص لرؤيتها تظهر.

     

   • اختر تنبيه الأذونات المفوضة.اقرأ>> حدد إضافة أذونات.

     

   هام

   حدد الأذونات ذات الصلة. قراءة التنبيهات هي مثال فقط.

   على سبيل المثال:

   • لتشغيل الاستعلامات المتقدمة، حدد تشغيل إذن الاستعلامات المتقدمة.

   • لعزل جهاز، حدد عزل إذن الجهاز.

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

   • حدد منح الموافقة.

     ملاحظة

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

     

5. اكتب معرف التطبيق ومعرف المستأجر الخاص بك.

   في صفحة التطبيق، انتقل إلى نظرة عامة وانسخ المعلومات التالية:

   

الحصول على رمز مميز للوصول

لمزيد من المعلومات حول الرموز المميزة Microsoft Entra، راجع البرنامج التعليمي Microsoft Entra.

ملاحظة

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

استخدام C#‎

تلميح

تستمر بعض واجهات برمجة التطبيقات Microsoft Defender لنقطة النهاية في طلب رموز الوصول المميزة الصادرة للمورد https://api.securitycenter.microsoft.comالقديم . إذا لم يتطابق جمهور الرمز المميز مع المورد المتوقع من قبل واجهة برمجة التطبيقات، تفشل الطلبات مع 403 Forbidden، حتى إذا كانت نقطة نهاية واجهة برمجة التطبيقات تستخدم https://api.security.microsoft.com. استخدم https://api.securitycenter.microsoft.com كمورد أو نطاق عند الحصول على الرموز المميزة.

يستخدم هذا المثال Microsoft Authentication Library (MSAL) للحصول على رمز تفاعلي. قبل أن تشغل البرنامج:

• أضف Microsoft.Identity.Client حزمة NuGet إلى مشروعك.
• عند تسجيل تطبيقك، قم بتكوين منصة تطبيقات الجوال وسطح المكتب باستخدام http://localhost رابط التوجيه (RURI)، بحيث يمكن للتدفق التفاعلي إعادة الرمز.
• قم بنسخ/لصق الفئة التالية في تطبيقك، ثم استدعي AcquireUserTokenAsync باستخدام معرف التطبيق ومعرف المستأجر. يطلب من المستخدم تسجيل الدخول بشكل تفاعلي؛ كلمة المرور الخاصة بهم لا يتم التعامل معها أبدا من قبل تطبيقك.

    namespace WindowsDefenderATP
    {
        using System.Linq;
        using System.Threading.Tasks;
        using Microsoft.Identity.Client;

        public static class WindowsDefenderATPUtils
        {
            private const string Authority = "https://login.microsoftonline.com";

            // Microsoft Defender for Endpoint APIs expect tokens issued for this resource.
            private static readonly string[] Scopes = { "https://api.securitycenter.microsoft.com/.default" };

            public static async Task<string> AcquireUserTokenAsync(string appId, string tenantId)
            {
                // Public client application for a native (desktop) app.
                // No client secret or user password is stored or handled by the app.
                var app = PublicClientApplicationBuilder
                    .Create(appId)
                    .WithAuthority($"{Authority}/{tenantId}")
                    .WithDefaultRedirectUri() // http://localhost - register as a public client redirect URI
                    .Build();

                var account = (await app.GetAccountsAsync().ConfigureAwait(false)).FirstOrDefault();

                try
                {
                    // Reuse a cached token when one is available.
                    var silentResult = await app
                        .AcquireTokenSilent(Scopes, account)
                        .ExecuteAsync()
                        .ConfigureAwait(false);

                    return silentResult.AccessToken;
                }
                catch (MsalUiRequiredException)
                {
                    // First run or expired session: prompt the user to sign in.
                    // Uses the authorization code flow with PKCE and supports
                    // multifactor authentication and Conditional Access.
                    var interactiveResult = await app
                        .AcquireTokenInteractive(Scopes)
                        .ExecuteAsync()
                        .ConfigureAwait(false);

                    return interactiveResult.AccessToken;
                }
            }
        }
    }

تلميح

بالنسبة للبيئة التي لا تحتوي على رأس أو بدون متصفح، استخدم تدفق كود الجهاز (AcquireTokenWithDeviceCode) بدلا من AcquireTokenInteractive.

التحقق من صحة الرمز المميز

تحقق للتأكد من حصولك على رمز مميز صحيح:

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

• تحقق من صحة حصولك على مطالبة "scp" مع أذونات التطبيق المطلوبة.

• في لقطة الشاشة أدناه، يمكنك مشاهدة رمز مميز تم فك ترميزه تم الحصول عليه من التطبيق في البرنامج التعليمي:

  

استخدام الرمز المميز للوصول إلى Microsoft Defender لنقطة النهاية API

• اختر واجهة برمجة التطبيقات التي تريد استخدامها - واجهات برمجة التطبيقات Microsoft Defender لنقطة النهاية المدعومة.

• قم بتعيين عنوان التخويل في طلب HTTP الذي ترسله إلى "Bearer {token}" (Bearer هو نظام التخويل).

• وقت انتهاء صلاحية الرمز المميز هو ساعة واحدة (يمكنك إرسال أكثر من طلب واحد بنفس الرمز المميز).

• مثال على إرسال طلب للحصول على قائمة بالتنبيهات باستخدام C#‎:

  var httpClient = new HttpClient();
  
  var request = new HttpRequestMessage(HttpMethod.Get, "https://api.security.microsoft.com/api/alerts");
  
  request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);
  
  var response = httpClient.SendAsync(request).GetAwaiter().GetResult();
  
  // Do something useful with the response
  

راجع أيضًا

• واجهات برمجة التطبيقات Microsoft Defender لنقطة النهاية
• الوصول Microsoft Defender لنقطة النهاية مع سياق التطبيق

تلميح

هل تريد معرفة المزيد؟ تواصل مع مجتمع الأمان من Microsoft في مجتمعنا التقني: مجتمع Microsoft Defender لنقطة النهاية التقني.