Access יישומי ענן של Microsoft Defender API עם הקשר משתמש

דף זה מתאר כיצד ליצור יישום כדי לקבל גישה תוכניתית יישומי ענן של Defender בשם משתמש.

אם אתה זקוק לגישה יישומי ענן של Microsoft Defender ללא משתמש, עיין במאמר גישה יישומי ענן של Microsoft Defender עם הקשר יישום.

אם אינך בטוח איזו גישה דרושה לך, קרא את הדף מבוא.

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

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

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

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

הערה

בעת גישה יישומי ענן של Microsoft Defender API בשם משתמש, תזדקק להרשאות היישום ולהרשאות המשתמש הנכונות. אם אינך מכיר את הרשאות המשתמש ב- יישומי ענן של Microsoft Defender, ראה ניהול גישת מנהל מערכת.

עצה

אם יש לך הרשאה לבצע פעולה בפורטל, יש לך הרשאה לבצע את הפעולה ב- API.

יצירת יישום

1. בתיבת מרכז הניהול של Microsoft Entra, רשום יישום חדש. לקבלת מידע נוסף, ראה התחלה מהירה: רישום יישום באמצעות מרכז הניהול של Microsoft Entra.

2. כאשר מופיע הדף רישום יישום , הזן את פרטי הרישום של היישום שלך:

   • Name - הזן שם יישום בעל משמעות המוצג למשתמשים של היישום.

   • סוגי חשבונות נתמכים - בחר בא סוגי החשבונות שברצונך שהיישום שלך יתמוך בהם.

     סוגי חשבונות נתמכים	תיאור
     חשבונות במדריך כתובות ארגוני זה בלבד	בחר באפשרות זו אם אתה בונה יישום קו פעולה עסקי (LOB). אפשרות זו אינה זמינה אם אינך רשם את היישום במדריך כתובות. אפשרות זו ממופה לדייר Microsoft Entra יחיד בלבד. זוהי אפשרות ברירת המחדל אלא אם אתה רשום את היישום מחוץ למדריך כתובות. במקרים שבהם האפליקציה רשומה מחוץ למדריך כתובות, ברירת המחדל היא Microsoft Entra חשבונות Microsoft מרובים ואישי.
     חשבונות בכל מדריך כתובות ארגוני	בחר באפשרות זו אם ברצונך לייעד את כל הלקוחות העסקיים וה החינוכיים. אפשרות זו ממופה לריבוי Microsoft Entra בלבד. אם רשמת את היישום Microsoft Entra לדייר יחיד בלבד, באפשרותך לעדכן אותו כך Microsoft Entra מרובה פריטים ובחזור לדייר יחיד באמצעות החלונית אימות.
     חשבונות בכל מדריך כתובות ארגוני וחשבונות Microsoft אישיים	בחר באפשרות זו כדי לייעד את קבוצת הלקוחות רחבה ביותר. אפשרות זו ממופה Microsoft Entra חשבונות Microsoft מרובים ואישיים. אם רשמת את האפליקציה Microsoft Entra Microsoft רב-משתמשים ואישי, לא תוכל לשנות זאת בממשק המשתמש. במקום זאת, עליך להשתמש בעורך מניפסט היישום כדי לשנות את סוגי החשבונות הנתמכים.

   • URI של ניתוב מחדש (אופציונלי) - בחר את סוג היישום שאתה בונה, **אינטרנט או לקוח ציבורי (מכשירים ניידים & לשולחן העבודה) ולאחר מכן הזן את ה- URI של ניתוב מחדש (או כתובת URL של תשובה) עבור היישום שלך.

     • עבור יישומי אינטרנט, ספק את כתובת ה- URL הבסיסית של היישום שלך. לדוגמה, http://localhost:31544 ייתכן שכתובת ה- URL של יישום אינטרנט הפועלת במחשב המקומי שלך. המשתמשים ישתמשו בכתובת URL זו כדי להיכנס ליישום לקוח אינטרנט.
     • עבור יישומי לקוח ציבוריים, ספק את ה- URI המשמש את מזהה Microsoft Entra כדי להחזיר תגובות אסימון. הזן ערך ספציפי ליישום שלך, כגון myapp://auth.

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

     כשתסיים, בחר הירשם.

3. אפשר ליישום שלך לגשת יישומי ענן של Microsoft Defender ולהקצות לו הרשאת 'קריאת התראות':

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

   הערה

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

   

5. בחר 'חקירה של הרשאות מוקצות>'.קרא>את בחר 'הוסף הרשאות'

   

   הערה

   בחר את ההרשאות הרלוונטיות. Investigation.Read הוא רק דוגמה. לקבלת טווחי הרשאות אחרים, ראה טווחי הרשאות נתמכים

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

7. בחר הענק הסכמת מנהל מערכת

   הערה

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

   

8. רשום לעצמך את מזהה היישום ואת מזהה הדייר שלך.

9. בדף היישום שלך, עבור אל מבט כולל והעתק את המידע הבא:

   

טווחי הרשאות נתמכים

שם הרשאה	תיאור	פעולות נתמכות
חקירה.קריאה	בצע את כל הפעולות הנתמכות בפעילויות ובהתראות למעט סגירת התראות. הצג טווחי IP אך לא הוסף, עדכן או מחק. בצע את כל פעולות הישויות.	רשימת פעילויות, הבאת משוב רשימת התראות, הבאת הודעות, סימון כפריטים שנקראו/לא נקראו רשימת ישויות, הבאת עץ רשימת רשת משנה
Investigation.manage	בצע את כל פעולות investigation.read בנוסף לניהול התראות וטווחי IP.	רשימת פעילויות, הבאת משוב רשימת התראות, הבאת הודעות, סימון כפריטים שנקראו/לא נקראו, סגירה רשימת ישויות, הבאת עץ רשימת רשת משנה, יצירה/עדכון/מחיקה
Discovery.read	בצע את כל הפעולות הנתמכות בפעילויות ובהתראות למעט סגירת התראות. רשימת דוחות וקטגוריות של גילוי.	רשימת התראות, הבאת הודעות, סימון כפריטים שנקראו/לא נקראו דוחות רשימת גילוי, קטגוריות של דוחות רשימה
Discovery.manage	הרשאות Discovery.read סגור התראות, העלה קבצי גילוי וצור קבצי Script של חסימה	רשימת התראות, הבאת הודעות, סימון כפריטים שנקראו/לא נקראו, סגירה דוחות רשימת גילוי, קטגוריות של דוחות רשימה העלאת קובץ גילוי, יצירת קובץ Script של בלוק
הגדרות.קריאה	רשימת טווחי IP.	רשימת רשת משנה
Settings.manage	רשימת טווחי IP וניהולם.	רשימת רשת משנה, יצירה/עדכון/מחיקה

קבל אסימון גישה

לקבלת מידע נוסף על Microsoft Entra, ראה Microsoft Entra שלך

שימוש ב- C#‎

• העתק/הדבק את הכיתה הבאה ביישום שלך.
• השתמש בפעולת שירות AcquireUserTokenAsync עם מזהה היישום, מזהה הדייר ואימות שלך משיגים אסימון.

הערה

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

namespace MDA
{
    using System.Net.Http;
    using System.Text;
    using System.Threading.Tasks;
    using Newtonsoft.Json.Linq;

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

        private const string MDAId = "05a65629-4c1b-48c1-a78b-804c4abdd4af";
        private const string Scope = "Investigation.read";

        public static async Task<string> AcquireUserTokenAsync(string username, string password, string appId, string tenantId)
        {
            using (var httpClient = new HttpClient())
            {
                var urlEncodedBody = $"scope={MDAId}/{Scope}&client_id={appId}&grant_type=password&username={username}&password={password}";

                var stringContent = new StringContent(urlEncodedBody, Encoding.UTF8, "application/x-www-form-urlencoded");

                using (var response = await httpClient.PostAsync($"{Authority}/{tenantId}/oauth2/token", stringContent).ConfigureAwait(false))
                {
                    response.EnsureSuccessStatusCode();

                    var json = await response.Content.ReadAsStringAsync().ConfigureAwait(false);

                    var jObject = JObject.Parse(json);

                    return jObject["access_token"].Value<string>();
                }
            }
        }
    }
} 

אימות האסימון

ודא כדי לוודא שיש לך אסימון נכון:

• העתק/הדבק לתוך JWT את האסימון שהכנסת בשלב הקודם כדי לפענח אותו.

• ודא שאתה מקבל דרישת 'scp' עם הרשאות האפליקציה הרצויות.

• בצילום המסך שלהלן תוכל לראות אסימון פענוח שנרכש מהיישום בערכת הלימוד:

  

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

• בחר את ה- API שבו ברצונך להשתמש. לקבלת מידע נוסף, ראה יישומי ענן של Defender API.

• הגדר את כותרת ההרשאה בבקשה HTTP שאתה שולח אל "נושא {token}" (הנושא הוא סכימת ההרשאה).

• מועד התפוגה של האסימון הוא שעה (באפשרותך לשלוח יותר מבקשה אחת עם אותו אסימון).

• דוגמה לשליחת בקשה לקבלת רשימה של התראות באמצעות C#‎:

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

למידע נוסף

• ניהול אסימוני API
• פלטפורמת הזהויות של Microsoft קוד הרשאה של פלטפורמת הזהויות של Microsoft ו- OAuth 2.0