יצירת אפליקציה עם גישת שותף Microsoft Defender XDR API

חשוב

חלק מהמידע מתייחס למוצר שהופץ מראש, אשר עשוי להיות שונה באופן משמעותי לפני ההפצה המסחרית שלו. Microsoft אינה מבטיחה דבר, באופן מפורש או משתמע, באשר למידע המסופק כאן.

דף זה מתאר כיצד ליצור יישום Microsoft Entra בעל גישה תוכניתית ל- Microsoft Defender XDR, בשם משתמשים על-פני דיירים מרובים. אפליקציות מרובות דיירים שימושיות להגשת קבוצות גדולות של משתמשים.

אם אתה זקוק לגישה תוכניתית Microsoft Defender XDR משתמש אחד, ראה יצירת יישום כדי לגשת Microsoft Defender XDR API בשם משתמש. אם אתה זקוק לגישה ללא הגדרה מפורשת של משתמש (לדוגמה, אם אתה כותב יישום רקע או Daemon), ראה יצירת יישום כדי לגשת Microsoft Defender XDR ללא משתמש. אם אינך בטוח איזה סוג של גישה דרושה לך, ראה תחילת העבודה.

Microsoft Defender XDR לחשוף חלק גדול מהנתונים והפעולות שלו באמצעות קבוצה של ממשקי API תיכנותיים. ממשקי API אלה עוזרים לך להפוך זרימות עבודה לאוטומטיות ולהשתמש Microsoft Defender XDR היכולות של המשתמשים. גישה זו ל- API מחייבת אימות OAuth2.0. לקבלת מידע נוסף, ראה זרימת קוד הרשאה של OAuth 2.0.

באופן כללי, יהיה עליך לבצע את השלבים הבאים כדי להשתמש בממשקי API אלה:

• צור יישום Microsoft Entra חדש.
• קבל אסימון גישה באמצעות יישום זה.
• השתמש לאסימון כדי לגשת אל Microsoft Defender XDR API.

מאחר שתישום זה הוא מרובה דיירים, תזדקק גם להסכמת מנהל מערכת מכל דייר בשם המשתמשים שלו.

מאמר זה מסביר כיצד לבצע את האופן בו:

• יצירת יישום מרובה דיירים Microsoft Entra זה
• קבל הסכמה מורשית ממנהל המשתמש שלך עבור היישום שלך כדי לגשת Microsoft Defender XDR למשאבים הדרושים לו.
• קבל אסימון גישה Microsoft Defender XDR
• אימות האסימון

Microsoft Defender XDR לחשוף חלק גדול מהנתונים והפעולות שלו באמצעות קבוצה של ממשקי API תיכנותיים. ממשקי API אלה יסייעו לך להפוך זרימות עבודה וחדשות לאוטומטיות בהתבסס על Microsoft Defender XDR שלך. גישת ה- API מחייבת אימות OAuth2.0. לקבלת מידע נוסף, ראה זרימת קוד הרשאה של OAuth 2.0.

באופן כללי, יהיה עליך לבצע את השלבים הבאים כדי להשתמש בממשקי ה- API:

• צור יישום מרובה דיירים Microsoft Entra זה.
• קבל הרשאה (הסכמה) על-ידי מנהל המשתמש שלך כדי שהיישום שלך Microsoft Defender XDR למשאבים הדרושים לו.
• קבל אסימון גישה באמצעות יישום זה.
• השתמש לאסימון כדי לגשת אל Microsoft Defender XDR API.

השלבים הבאים עם מדריך אותך כיצד ליצור יישום מרובה דיירים Microsoft Entra, לקבל אסימון גישה Microsoft Defender XDR ולאמת את האסימון.

יצירת היישום מרובה הדיירים

1. היכנס ל- Azure.

2. נווט אל מזהה Microsoft Entra>רישום ליישומים>רישום חדש.

   

3. בטופס הרישום:

   • בחר שם עבור היישום שלך.
   • מתוך סוגי חשבונות נתמכים, בחר חשבונות בכל מדריך כתובות ארגוני (מדריך Microsoft Entra) - מרובה.
   • מלא את המקטע URI של ניתוב מחדש. בחר הקלד אינטרנט והעבר את ה- URI של ניתוב מחדש כ- https://portal.azure.com.

   לאחר שתסיים למלא את הטופס, בחר הירשם.

   

4. בדף היישום שלך, בחר הרשאות API>> הוסף ממשקי API של הרשאות שהארגון שלי משתמשבהם>, הקלד Microsoft Threat Protection ובחר Microsoft Threat Protection. האפליקציה שלך יכולה כעת לגשת Microsoft Defender XDR.

   עצה

   Microsoft Threat Protection הוא שם Microsoft Defender XDR עבור Microsoft, והוא לא יופיע ברשימה המקורית. עליך להתחיל לכתוב את שמו בתיבת הטקסט כדי לראות אותו מופיע.

   

5. בחר הרשאות יישום. בחר את ההרשאות הרלוונטיות עבור התרחיש שלך (לדוגמה, Incident.Read.All) ולאחר מכן בחר הוסף הרשאות.

   

   הערה

   עליך לבחור את ההרשאות הרלוונטיות עבור התרחיש שלך. קרא את כל האירועים הוא רק דוגמה. כדי לקבוע איזו הרשאה דרושה לך, עיין בסעיף הרשאות ב- API שאליו ברצונך להתקשר.

   לדוגמה, כדי להפעיל שאילתות מתקדמות, בחר את ההרשאה 'הפעל שאילתות מתקדמות'; כדי לבודד מכשיר, בחר את ההרשאה 'מחשב בודד'.

6. בחר הענק הסכמת מנהל מערכת. בכל פעם שאתה מוסיף הרשאה, עליך לבחור הענק הסכמת מנהל מערכת כדי שהיא תוכל להיכנס לתוקף.

   

7. כדי להוסיף סוד ליישום, בחר אישורים &, הוסף תיאור לסוד ולאחר מכן בחר הוסף.

   עצה

   לאחר שתבחר הוסף, בחר העתק את הערך הסודי שנוצר. לא תוכל לאחזר את הערך הסודי לאחר שתצא.

   

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.

עצה

בדוגמאות הבאות, השתמש במזהה דייר של משתמש כדי לבדוק שקובץ ה- Script פועל.

קבלת אסימון גישה באמצעות 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 Authentication Library (ADAL) בוהטו. לא נוספו תכונות חדשות מאז 30 ביוני 2020. אנו ממליצים מאוד לשדרג, עיין במדריך ההעברה לקבלת פרטים נוספים.

1. צור יישום מסוף חדש.

2. התקן את NuGet Microsoft.Identity.Client.

3. הוסף את השורה הבאה:

   using Microsoft.Identity.Client;
   

4. העתק והדבק את הקוד הבא ביישום שלך (אל תשכח לעדכן את שלושת המשתנים: 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;
   

קבל אסימון גישה באמצעות 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"]

קבל אסימון גישה באמצעות פיתל

הערה

התכרבל מותקן מראש ב- Windows 10, בגירסאות 1803 ואילך. עבור גירסאות אחרות של Windows, הורד והתקן את הכלי ישירות מאתר האינטרנט הרשמי של התלתלים.

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 :

השתמש לאסימון כדי לגשת ל- API Microsoft Defender XDR שלך

1. בחר את ה- API שבו ברצונך להשתמש (אירועים או ציד מתקדם). לקבלת מידע נוסף, ראה ממשקי API 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 Defender XDR כולל על ממשקי API
• גישה Microsoft Defender XDR API
• יצירת יישום 'Hello world'
• יצירת יישום כדי לגשת Microsoft Defender XDR ללא משתמש
• יצירת יישום לגישה Microsoft Defender XDR API בשם משתמש
• קבל מידע על מגבלות API ורישוי
• הכרת קודי שגיאה
• ניהול סודות באפליקציות השרת שלך באמצעות Azure Key Vault
• הרשאת OAuth 2.0 עבור כניסה למשתמש וגישת API

עצה

האם ברצונך לקבל מידע נוסף? צור קשר עם קהילת האבטחה של Microsoft בקהילת הטכנולוגיה שלנו: קהילת האבטחה של Microsoft Defender XDR.