إنشاء تطبيق مع وصول الشريك إلى واجهات برمجة التطبيقات 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 والتحقق من صحة الرمز المميز.
سجل الدخول إلى Azure.
انتقل إلى تسجيلات>Microsoft Entra ID> Appتسجيل جديد.
في نموذج التسجيل:
- اختر اسما للتطبيق الخاص بك.
- من أنواع الحسابات المدعومة، حدد الحسابات في أي دليل تنظيمي (أي دليل Microsoft Entra) - متعدد المستأجرين.
- املأ قسم Redirect URI . حدد نوع ويب وامنح عنوان URI لإعادة التوجيه ك https://portal.azure.com.
بعد الانتهاء من ملء النموذج، حدد Register.
في صفحة التطبيق الخاص بك، حدد أذونات واجهة برمجة التطبيقات إضافة واجهات> برمجة تطبيقاتالأذونات>التي تستخدمها> مؤسستي، واكتب الحماية من التهديدات من Microsoft، وحدد الحماية من التهديدات من Microsoft. يمكن لتطبيقك الآن الوصول إلى Microsoft Defender XDR.
تلميح
الحماية من التهديدات من Microsoft هو اسم سابق Microsoft Defender XDR، ولن يظهر في القائمة الأصلية. تحتاج إلى البدء في كتابة اسمه في مربع النص لمشاهدته يظهر.
حدد Application permissions. اختر الأذونات ذات الصلة للسيناريو الخاص بك (على سبيل المثال، Incident.Read.All)، ثم حدد Add permissions.
ملاحظة
تحتاج إلى تحديد الأذونات ذات الصلة للسيناريو الخاص بك. قراءة جميع الحوادث هو مجرد مثال. لتحديد الإذن الذي تحتاجه، يرجى إلقاء نظرة على قسم الأذونات في واجهة برمجة التطبيقات التي تريد الاتصال بها.
على سبيل المثال، لتشغيل الاستعلامات المتقدمة، حدد إذن "تشغيل الاستعلامات المتقدمة"؛ لعزل جهاز، حدد إذن "عزل الجهاز".
حدد منح موافقة المسؤول. في كل مرة تضيف فيها إذنا، يجب عليك تحديد منح موافقة المسؤول حتى يصبح ساري المفعول.
لإضافة سر إلى التطبيق، حدد Certificates & secrets، وأضف وصفا إلى السر، ثم حدد Add.
تلميح
بعد تحديد إضافة، حدد نسخ القيمة السرية التي تم إنشاؤها. لن تتمكن من استرداد القيمة السرية بعد المغادرة.
سجل معرف التطبيق ومعرف المستأجر في مكان آمن. يتم سردها ضمن نظرة عامة على صفحة التطبيق الخاص بك.
أضف التطبيق إلى مستأجر المستخدم الخاص بك.
نظرا لأن تطبيقك يتفاعل مع 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.
تلميح
في الأمثلة التالية، استخدم معرف مستأجر المستخدم لاختبار أن البرنامج النصي يعمل.
# 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
ملاحظة
تم اختبار التعليمات البرمجية التالية مع Nuget Microsoft.Identity.Client 3.19.8.
هام
تم إهمال حزمة Microsoft.IdentityModel.Clients.ActiveDirectory NuGet ومكتبة مصادقة Azure AD (ADAL). لم تتم إضافة ميزات جديدة منذ 30 يونيو 2020. نحن نشجعك بشدة على الترقية، راجع دليل الترحيل لمزيد من التفاصيل.
إنشاء تطبيق وحدة تحكم جديد.
تثبيت NuGet Microsoft.Identity.Client.
أضف السطر التالي:
using Microsoft.Identity.Client;
انسخ التعليمات البرمجية التالية والصقها في تطبيقك (لا تنس تحديث المتغيرات الثلاثة:
tenantId
، ،clientId
appSecret
):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;
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 مسبقا على Windows 10، الإصدارات 1803 والإصدارات الأحدث. بالنسبة للإصدارات الأخرى من Windows، قم بتنزيل الأداة وتثبيتها مباشرة من موقع curl الرسمي على الويب.
- افتح موجه الأوامر، وقم بتعيين CLIENT_ID إلى معرف تطبيق Azure.
- قم بتعيين CLIENT_SECRET إلى سر تطبيق Azure الخاص بك.
- قم بتعيين TENANT_ID إلى معرف مستأجر Azure للمستخدم الذي يريد استخدام تطبيقك للوصول إلى Microsoft Defender XDR.
- قم بتنفيذ الأمر التالي:
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"}
- انسخ الرمز المميز والصقه في موقع مدقق رمز ويب JSON، JWT، لفك ترميزه.
- تأكد من أن مطالبة الأدوار داخل الرمز المميز الذي تم فك ترميزه تحتوي على الأذونات المطلوبة.
في الصورة التالية، يمكنك مشاهدة رمز مميز تم فك ترميزه تم الحصول عليه من تطبيق، مع Incidents.Read.All
الأذونات Incidents.ReadWrite.All
و و AdvancedHunting.Read.All
:
- اختر واجهة برمجة التطبيقات التي تريد استخدامها (الحوادث أو التتبع المتقدم). لمزيد من المعلومات، راجع واجهات برمجة تطبيقات Microsoft Defender XDR المدعومة.
- في طلب http الذي أنت على وشك إرساله، قم بتعيين عنوان التخويل إلى
"Bearer" <token>
، و Bearer هو نظام التخويل، والرمز المميز الذي تم التحقق من صحته. - ستنتهي صلاحية الرمز المميز في غضون ساعة واحدة. يمكنك إرسال أكثر من طلب واحد خلال هذا الوقت بنفس الرمز المميز.
يوضح المثال التالي كيفية إرسال طلب للحصول على قائمة بالحوادث باستخدام 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 world"
- إنشاء تطبيق للوصول إلى Microsoft Defender XDR بدون مستخدم
- إنشاء تطبيق للوصول إلى واجهات برمجة التطبيقات Microsoft Defender XDR نيابة عن مستخدم
- تعرف على حدود واجهة برمجة التطبيقات والترخيص
- فهم رموز الخطأ
- إدارة الأسرار في تطبيقات الخادم باستخدام Azure Key Vault
- تخويل OAuth 2.0 لتسجيل دخول المستخدم والوصول إلى واجهة برمجة التطبيقات
تلميح
هل تريد معرفة المزيد؟ تفاعل مع مجتمع أمان Microsoft في مجتمعنا التقني: Microsoft Defender XDR Tech Community.