使用 Microsoft Defender for Endpoint APIs

適用於:

想要體驗適用於端點的 Microsoft Defender 嗎? 注册免費試用版。

注意

如果您是美國政府客戶,請使用 Microsoft Defender FOR Us 政府客戶的端點中所列的 URIs。

提示

為了提高效能,您可以使用伺服器以接近地理位置:

  • api-us.securitycenter.microsoft.com
  • api-eu.securitycenter.microsoft.com
  • api-uk.securitycenter.microsoft.com

此頁面說明如何建立應用程式,以在代表使用者對 Defender for Endpoint 的程式設計中取得存取權。

如果您需要以程式設計方式存取 Microsoft Defender for Endpoint,但沒有使用者,請參閱 Access Microsoft defender For endpoint with application coNtext

如果您不確定需要哪一種存取權,請閱讀 [簡介] 頁面

Microsoft Defender for Endpoint 會透過一組程式設計 APIs 公開其資料和動作。 這些 APIs 可讓您根據 Microsoft Defender for Endpoint 功能來自動化工作流程及創新。 API 存取需要 OAuth 2.0 驗證。 如需詳細資訊,請參閱OAuth 2.0 授權碼 Flow

一般來講,您必須採取下列步驟,才能使用 APIs:

  • 建立 AAD 應用程式
  • 使用此應用程式取得存取 token
  • 使用權杖來存取適用于 Endpoint API 的 Defender

此頁面說明如何建立 AAD 的應用程式、取得對 Microsoft Defender for Endpoint 的存取權杖,以及驗證權杖。

注意

當代表使用者存取 Microsoft Defender for Endpoint API 時,您將需要正確的應用程式許可權和使用者許可權。 如果您不熟悉 Microsoft Defender for Endpoint 的使用者權限,請參閱 使用以角色為基礎的存取控制管理入口網站存取

提示

如果您有許可權執行入口網站中的動作,您就具有在 API 中執行該動作的許可權。

建立應用程式

  1. 使用具有 全域系統管理員 角色的使用者帳戶,登入 Azure

  2. 流覽至 Azure Active Directory > App 註冊 > 新註冊

    Microsoft Azure 及流覽至應用程式註冊的影像。

  3. 當出現 [ 註冊應用程式 ] 頁面時,請輸入您的應用程式的註冊資訊:

    • Name -輸入將向應用程式使用者顯示的有意義應用程式名稱。
    • 支援的帳戶類型 -選取您要讓應用程式支援的帳戶。


支援的帳戶類型 描述
僅限此組織目錄中的帳戶 如果您要建立企業營運 (LOB) 應用程式,請選取此選項。 如果您不是在目錄中註冊應用程式,則無法使用此選項。

此選項會對應至僅 Azure AD 單一承租人。

除非您是在目錄外註冊應用程式,否則此為預設選項。 當應用程式在目錄外註冊時,預設值為 Azure AD 多承租人和個人 Microsoft 帳戶。

任何組織目錄中的帳戶 如果您想要將所有商務及教育客戶都瞄準,請選取此選項。

此選項對應于僅限多租使用者的 Azure AD。

如果您將應用程式註冊為只 Azure AD 單一租使用者,您可以將它更新為 Azure AD 多租使用者,並透過 驗證 刀片式伺服器傳回單一租使用者。

任何組織目錄和個人 Microsoft 帳戶中的帳戶 選取此選項以針對最廣泛的一組客戶。

此選項會對應至 Azure AD 多承租人和個人 Microsoft 帳戶。

如果您將應用程式註冊為 Azure AD 多承租人和個人 Microsoft 帳戶,您就無法在 UI 中變更此方式。 相反地,您必須使用應用程式資訊清單編輯器來變更支援的帳戶類型。

  • 重新 導向 URI (選用) -選取您要建立的應用程式類型、網頁公用用戶端 (行動 & 桌面),然後輸入應用程式的重新導向 URI (或回復 URL) 。

    • 針對 web 應用程式,提供應用程式的基底 URL。 例如, http://localhost:31544 可能是在本機電腦上執行之 web 應用程式的 URL。 使用者會使用此 URL 登入 web 用戶端應用程式。
    • 若為公用用戶端應用程式,請提供 Azure AD 所使用的 URI,以傳回權杖回應。 輸入應用程式的特定值,例如 myapp://auth

    若要查看 web 應用程式或原生應用程式的特定範例,請查看我們的 快速入門

    完成時,請選取 [ 註冊]。

  1. 允許您的應用程式存取 Microsoft Defender for Endpoint,並指派「讀取警示」許可權:

    • 在 [應用程式] 頁面上,選取 [ API 許可權 > 新增許可權 > APIs 我的組織使用 > 類型 WindowsDefenderATP ],然後選取 [ WindowsDefenderATP]。

    • 附注WindowsDefenderATP 不會出現在原始清單中。 開始在文字方塊中寫入其名稱,以查看顯示。

      新增許可權。

    • 選擇 [委派許可權] > 警示。讀取> 選取 [新增許可權]

      應用程式許可權。

    • 重要事項:請選取相關的許可權。 讀取警示只是一個範例。

      例如,

      • 若要 執行高級查詢,請選取「執行高級查詢」許可權
      • 若要 隔離裝置,請選取「隔離電腦」許可權
      • 若要決定您需要的許可權,請在您想要呼叫的 API 中查看 [ 許可權 ] 區段。
    • 選取 [授與同意]

      附注:每次您新增許可權時,您必須選取 [授與同意 才能讓新許可權同意]。

      授與許可權的影像。

  2. 記下來記錄應用程式識別碼和您的租使用者 ID:

    • 在 [應用程式] 頁面上,移至 [簡介 ],然後複製下列資訊:

    已建立之應用程式識別碼的影像。

取得存取權杖

如需 AAD 權杖的詳細資訊,請參閱Azure AD 教學課程

使用 C#

  • 在您的應用程式中複製/貼上下列類別。

  • 使用 AcquireUserTokenAsync 方法搭配您的應用程式識別碼、租使用者識別碼、使用者名稱和密碼來取得權杖。

    namespace WindowsDefenderATP
    {
        using System.Net.Http;
        using System.Text;
        using System.Threading.Tasks;
        using Newtonsoft.Json.Linq;
    
        public static class WindowsDefenderATPUtils
        {
            private const string Authority = "https://login.microsoftonline.com";
    
            private const string WdatpResourceId = "https://api.securitycenter.microsoft.com";
    
            public static async Task<string> AcquireUserTokenAsync(string username, string password, string appId, string tenantId)
            {
                using (var httpClient = new HttpClient())
                {
                    var urlEncodedBody = $"resource={WdatpResourceId}&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>();
                    }
                }
            }
        }
    }
    

驗證 token

請確認您獲得正確的權杖:

  • 複製/貼上您在上一個步驟中所 掌握的權杖 ,以進行解碼。
  • 驗證您取得「scp」宣告所需的應用程式許可權
  • 在下列螢幕擷取畫面中,您可以看到在教學課程中從應用程式取得的解碼權杖:

權杖驗證的影像。

使用權杖來存取 Microsoft Defender for Endpoint API

  • 選擇您要使用的 API- 支援的 Microsoft Defender For Endpoint APIs

  • 在您傳送至 "載荷 {token}" 的 HTTP 要求中設定授權標頭 (載荷是授權配置)

  • 權杖的到期時間是1小時 (您可以使用相同的權杖傳送一個以上的要求)

  • 使用 c # 傳送要求以取得警示清單的範例

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

另請參閱