الإنشاء تطبيقا مع وصول الشريك إلى واجهات برمجة التطبيقات Microsoft Defender XDR

ينطبق على:

• Microsoft Defender XDR

هام

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

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

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

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

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

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

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

توضح هذه المقالة كيفية:

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

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

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

• الإنشاء تطبيق Microsoft Entra متعدد المستأجرين.
• احصل على إذن (موافقة) من مسؤول المستخدم لتطبيقك للوصول إلى الموارد Microsoft Defender XDR التي يحتاجها.
• احصل على رمز مميز للوصول باستخدام هذا التطبيق.
• استخدم الرمز المميز للوصول إلى Microsoft Defender XDR API.

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

الإنشاء التطبيق متعدد المستأجرين

1. سجل الدخول إلى Azure كمستخدم مع دور المسؤول العام .

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

   

3. في نموذج التسجيل:

   • اختر اسما للتطبيق الخاص بك.
   • من أنواع الحسابات المدعومة، حدد الحسابات في أي دليل تنظيمي (أي دليل Microsoft Entra) - متعدد المستأجرين.
   • املأ قسم Redirect URI . حدد نوع ويب وامنح عنوان URI لإعادة التوجيه ك https://portal.azure.com.

   بعد الانتهاء من ملء النموذج، حدد Register.

   

4. في صفحة التطبيق الخاص بك، حدد أذونات واجهة برمجة التطبيقات إضافة واجهات> برمجة تطبيقاتالأذونات>التي تستخدمها> مؤسستي، واكتب الحماية من التهديدات من Microsoft، وحدد الحماية من التهديدات من Microsoft. يمكن لتطبيقك الآن الوصول إلى Microsoft Defender XDR.

   تلميح

   الحماية من التهديدات من Microsoft هو اسم سابق Microsoft Defender XDR، ولن يظهر في القائمة الأصلية. تحتاج إلى البدء في كتابة اسمه في مربع النص لمشاهدته يظهر.

   

5. حدد Application permissions. اختر الأذونات ذات الصلة للسيناريو الخاص بك (على سبيل المثال، Incident.Read.All)، ثم حدد Add permissions.

   

   ملاحظة

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

   على سبيل المثال، لتشغيل الاستعلامات المتقدمة، حدد إذن "تشغيل الاستعلامات المتقدمة"؛ لعزل جهاز، حدد إذن "عزل الجهاز".

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

   

7. لإضافة سر إلى التطبيق، حدد Certificates & secrets، وأضف وصفا إلى السر، ثم حدد Add.

   تلميح

   بعد تحديد إضافة، حدد نسخ القيمة السرية التي تم إنشاؤها. لن تتمكن من استرداد القيمة السرية بعد المغادرة.

   

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

   

9. أضف التطبيق إلى مستأجر المستخدم الخاص بك.

   نظرا لأن تطبيقك يتفاعل مع Microsoft Defender XDR نيابة عن المستخدمين، يجب الموافقة عليه لكل مستأجر تنوي استخدامه عليه.

   يحتاج المسؤول العام من مستأجر المستخدم إلى عرض ارتباط الموافقة والموافقة على التطبيق الخاص بك.

   رابط الموافقة هو من النموذج:

   https://login.microsoftonline.com/common/oauth2/authorize?prompt=consent&client_id=00000000-0000-0000-0000-000000000000&response_type=code&sso_reload=true
   

   يجب استبدال الأرقام 00000000-0000-0000-0000-000000000000 بمعرف التطبيق الخاص بك.

   بعد النقر فوق ارتباط الموافقة، قم بتسجيل الدخول باستخدام المسؤول العام لمستأجر المستخدم والموافقة على التطبيق.

   

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

• القيام به! لقد سجلت تطبيقا بنجاح!
• راجع الأمثلة أدناه للحصول على الرمز المميز والتحقق من صحته.

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

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

هام

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

تلميح

في الأمثلة التالية، استخدم معرف مستأجر المستخدم لاختبار أن البرنامج النصي يعمل.

الحصول على رمز مميز للوصول باستخدام PowerShell

# This code gets the application context token and saves it to a file named "Latest-token.txt" under the current directory.

$tenantId = '' # Paste your directory (tenant) ID here
$clientId = '' # Paste your application (client) ID here
$appSecret = '' # Paste your own app secret here to test, then store it in a safe place!

$resourceAppIdUri = 'https://api.security.microsoft.com'
$oAuthUri = "https://login.windows.net/$tenantId/oauth2/token"

$authBody = [Ordered] @{
    resource = $resourceAppIdUri
    client_id = $clientId
    client_secret = $appSecret
    grant_type = 'client_credentials'
}

$authResponse = Invoke-RestMethod -Method Post -Uri $oAuthUri -Body $authBody -ErrorAction Stop
$token = $authResponse.access_token

Out-File -FilePath "./Latest-token.txt" -InputObject $token

return $token

الحصول على رمز مميز للوصول باستخدام C#‎

ملاحظة

تم اختبار التعليمات البرمجية التالية مع Nuget Microsoft.Identity.Client 3.19.8.

هام

تم إهمال حزمة Microsoft.IdentityModel.Clients.ActiveDirectory NuGet ومكتبة مصادقة Azure AD (ADAL). لم تتم إضافة ميزات جديدة منذ 30 يونيو 2020. نحن نشجعك بشدة على الترقية، راجع دليل الترحيل لمزيد من التفاصيل.

1. الإنشاء تطبيق وحدة تحكم جديد.

2. تثبيت NuGet Microsoft.Identity.Client.

3. أضف السطر التالي:

   using Microsoft.Identity.Client;
   

4. انسخ التعليمات البرمجية التالية والصقها في تطبيقك (لا تنس تحديث المتغيرات الثلاثة: tenantId، ، clientIdappSecret):

   string tenantId = "00000000-0000-0000-0000-000000000000"; // Paste your own tenant ID here
   string appId = "11111111-1111-1111-1111-111111111111"; // Paste your own app ID here
   string appSecret = "22222222-2222-2222-2222-222222222222"; // Paste your own app secret here for a test, and then store it in a safe place! 
   const string authority = https://login.microsoftonline.com;
   const string audience = https://api.securitycenter.microsoft.com;
   
   IConfidentialClientApplication myApp = ConfidentialClientApplicationBuilder.Create(appId).WithClientSecret(appSecret).WithAuthority($"{authority}/{tenantId}").Build();
   
   List<string> scopes = new List<string>() { $"{audience}/.default" };
   
   AuthenticationResult authResult = myApp.AcquireTokenForClient(scopes).ExecuteAsync().GetAwaiter().GetResult();
   
   string token = authResult.AccessToken;
   

الحصول على رمز مميز للوصول باستخدام Python

import json
import urllib.request
import urllib.parse

tenantId = '' # Paste your directory (tenant) ID here
clientId = '' # Paste your application (client) ID here
appSecret = '' # Paste your own app secret here to test, then store it in a safe place, such as the Azure Key Vault!

url = "https://login.windows.net/%s/oauth2/token" % (tenantId)

resourceAppIdUri = 'https://api.security.microsoft.com'

body = {
    'resource' : resourceAppIdUri,
    'client_id' : clientId,
    'client_secret' : appSecret,
    'grant_type' : 'client_credentials'
}

data = urllib.parse.urlencode(body).encode("utf-8")

req = urllib.request.Request(url, data)
response = urllib.request.urlopen(req)
jsonResponse = json.loads(response.read())
aadToken = jsonResponse["access_token"]

الحصول على رمز مميز للوصول باستخدام curl

ملاحظة

تم تثبيت Curl مسبقا على Windows 10، الإصدارات 1803 والإصدارات الأحدث. بالنسبة للإصدارات الأخرى من Windows، قم بتنزيل الأداة وتثبيتها مباشرة من موقع curl الرسمي على الويب.

1. افتح موجه الأوامر، وقم بتعيين CLIENT_ID إلى معرف تطبيق Azure.
2. قم بتعيين CLIENT_SECRET إلى سر تطبيق Azure الخاص بك.
3. قم بتعيين TENANT_ID إلى معرف مستأجر Azure للمستخدم الذي يريد استخدام تطبيقك للوصول إلى Microsoft Defender XDR.
4. قم بتنفيذ الأمر التالي:

curl -i -X POST -H "Content-Type:application/x-www-form-urlencoded" -d "grant_type=client_credentials" -d "client_id=%CLIENT_ID%" -d "scope=https://securitycenter.onmicrosoft.com/windowsatpservice/.default" -d "client_secret=%CLIENT_SECRET%" "https://login.microsoftonline.com/%TENANT_ID%/oauth2/v2.0/token" -k

ستبدو الاستجابة الناجحة كما يلي:

{"token_type":"Bearer","expires_in":3599,"ext_expires_in":0,"access_token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIn <truncated> aWReH7P0s0tjTBX8wGWqJUdDA"}

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

1. انسخ الرمز المميز والصقه في موقع مدقق رمز ويب JSON، JWT، لفك ترميزه.
2. تأكد من أن مطالبة الأدوار داخل الرمز المميز الذي تم فك ترميزه تحتوي على الأذونات المطلوبة.

في الصورة التالية، يمكنك مشاهدة رمز مميز تم فك ترميزه تم الحصول عليه من تطبيق، مع Incidents.Read.Allالأذونات Incidents.ReadWrite.Allو و AdvancedHunting.Read.All :

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

1. اختر واجهة برمجة التطبيقات التي تريد استخدامها (الحوادث أو التتبع المتقدم). لمزيد من المعلومات، راجع واجهات برمجة تطبيقات Microsoft Defender XDR المدعومة.
2. في طلب http الذي أنت على وشك إرساله، قم بتعيين عنوان التخويل إلى "Bearer" <token>، و Bearer هو نظام التخويل، والرمز المميز الذي تم التحقق من صحته.
3. ستنتهي صلاحية الرمز المميز في غضون ساعة واحدة. يمكنك إرسال أكثر من طلب واحد خلال هذا الوقت بنفس الرمز المميز.

يوضح المثال التالي كيفية إرسال طلب للحصول على قائمة بالحوادث باستخدام C#‎.

   var httpClient = new HttpClient();
   var request = new HttpRequestMessage(HttpMethod.Get, "https://api.security.microsoft.com/api/incidents");

   request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);

   var response = httpClient.SendAsync(request).GetAwaiter().GetResult();

المقالات ذات الصلة

• نظرة عامة على واجهات برمجة التطبيقات Microsoft Defender XDR
• الوصول إلى واجهات برمجة التطبيقات Microsoft Defender XDR
• الإنشاء تطبيق "عالم Hello"
• الإنشاء تطبيق للوصول إلى Microsoft Defender XDR بدون مستخدم
• الإنشاء تطبيقا للوصول إلى واجهات برمجة التطبيقات Microsoft Defender XDR نيابة عن مستخدم
• تعرف على حدود واجهة برمجة التطبيقات والترخيص
• فهم رموز الخطأ
• إدارة الأسرار في تطبيقات الخادم باستخدام Azure Key Vault
• تخويل OAuth 2.0 لتسجيل دخول المستخدم والوصول إلى واجهة برمجة التطبيقات

تلميح

هل تريد معرفة المزيد؟ تفاعل مع مجتمع أمان Microsoft في مجتمعنا التقني: Microsoft Defender XDR Tech Community.