الإنشاء تطبيق للوصول إلى Microsoft Defender XDR بدون مستخدم

  • مقالة

ينطبق على:

  • Microsoft Defender XDR

هام

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

توضح هذه الصفحة كيفية إنشاء تطبيق للحصول على وصول برمجي إلى 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
  • التحقق من صحة الرمز المميز.

الإنشاء تطبيق

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

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

    علامة التبويب تسجيل جديد في مدخل Microsoft Defender

  3. في النموذج، اختر اسما للتطبيق الخاص بك، ثم حدد تسجيل.

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

    تلميح

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

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

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

    جزء إذن التطبيق في مدخل Microsoft Defender

    ملاحظة

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

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

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

    الجزء المتعلق بمنح الموافقة في مدخل Microsoft Defender

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

    تلميح

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

    جزء إنشاء التطبيق في مدخل Microsoft Defender

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

    جزء نظرة عامة في مدخل Microsoft Defender

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

    • انتقل إلى المصادقة، وأضف https://portal.azure.com ك عنوان URI لإعادة التوجيه.

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

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

    يحتاج المسؤول العام ل Active Directory لكل مستأجر إلى تحديد ارتباط الموافقة والموافقة على تطبيقك.

    يحتوي ارتباط الموافقة على البنية التالية:

    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, such as the Azure Key Vault!

$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):

    csharp
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://api.security.microsoft.com/.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

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

  1. اختر واجهة برمجة التطبيقات التي تريد استخدامها (الحوادث أو التتبع المتقدم). لمزيد من المعلومات، راجع واجهات برمجة تطبيقات Microsoft Defender XDR المدعومة.

  2. في طلب http الذي على وشك إرساله، قم بتعيين عنوان التخويل إلى "Bearer" <token>، والحامل هو نظام التخويل، والرمز المميز الذي تم التحقق من صحته.

  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 في مجتمعنا التقني: Microsoft Defender XDR Tech Community.