建立應用程式以代表使用者存取 Microsoft Defender 全面偵測回應 API

適用於：

• Microsoft Defender XDR

重要事項

部分資訊與發行前版本產品有關，在正式發行之前可能會實質上進行修改。 Microsoft 對此處提供的資訊，不提供任何明確或隱含的瑕疵擔保。

此頁面描述如何建立應用程式，以程式設計方式代表單一使用者存取 Microsoft Defender 全面偵測回應。

例如，如果您需要以程序設計方式存取 Microsoft Defender 全面偵測回應，而不需要定義的使用者 (，如果您要撰寫背景應用程式或精靈) ，請參閱建立應用程式來存取 Microsoft Defender 全面偵測回應 而不使用使用者。 如果您需要提供多個租使用者的存取權，例如，如果您要為大型組織或客戶群組提供服務，請參閱建立具有合作夥伴存取權的應用程式 Microsoft Defender 全面偵測回應 API。如果您不確定需要哪種存取，請參閱開始使用。

Microsoft Defender 全面偵測回應 透過一組程序設計 API 公開其大部分的數據和動作。 這些 API 可協助您將工作流程自動化，並利用 Microsoft Defender 全面偵測回應 功能。 此 API 存取需要 OAuth2.0 驗證。 如需詳細資訊，請參閱 OAuth 2.0 授權碼流程。

一般而言，您必須採取下列步驟來使用這些 API：

• 建立 Microsoft Entra 應用程式。
• 使用此應用程式取得存取令牌。
• 使用令牌來存取 Microsoft Defender 全面偵測回應 API。

本文說明如何：

• 建立 Microsoft Entra 應用程式
• 取得存取令牌以 Microsoft Defender 全面偵測回應
• 驗證令牌

注意事項

代表使用者存取 Microsoft Defender 全面偵測回應 API 時，您需要正確的應用程式許可權和用戶權力。

提示

如果您具有在入口網站中執行動作的許可權，您就有許可權可在 API 中執行動作。 如需角色和許可權的詳細資訊，請參閱使用 Microsoft Entra 全域角色管理 Microsoft Defender 全面偵測回應 的存取權。

建立應用程式

1. 登入 Azure。

2. 流覽至 Microsoft Entra ID>應用程式註冊>新增註冊。

   

3. 在表單中，選擇應用程式的名稱，然後輸入重新導向 URI 的下列資訊，然後選取 [ 註冊]。

   

   • 應用程式類型： 公用用戶端
   • 重新導向 URI：https://portal.azure.com

4. 在您的應用程式頁面上，選取 [API 權>限][新增>我的組織使用的>許可權 API]、輸入 Microsoft Threat Protection]，然後選取 [Microsoft威脅防護]。 您的應用程式現在可以存取 Microsoft Defender 全面偵測回應。

   提示

   Microsoft威脅防護是 Microsoft Defender 全面偵測回應 的先前名稱，不會出現在原始清單中。 您必須開始在文字框中寫入其名稱，才能看到它出現。

   

   • 選擇 [委派的許可權]。 選擇案例的相關許可權 (例如 Incident.Read) ，然後選取 [ 新增許可權]。

     

   注意事項

   您必須選取案例的相關許可權。 讀取所有事件 只是一個範例。 若要判斷您需要的許可權，請查看您要呼叫之 API 中的許可權一節。

   例如，若 要執行進階查詢，請選取 [執行進階查詢] 許可權;若 要隔離裝置，請選取 [隔離機器] 許可權。

5. 選 取 [授與系統管理員同意]。 每次新增許可權時，您都必須選取 [ 授與系統管理員同意 ] 使其生效。

   

6. 在安全的地方記錄您的應用程式識別碼和租用戶標識碼。 它們會列在應用程式頁面的 [ 概觀 ] 底下。

   

取得存取權杖

如需 Microsoft Entra 令牌的詳細資訊，請參閱 Microsoft Entra 教學課程。

使用 PowerShell 代表使用者取得存取令牌

使用 MSAL.PS 連結庫來取得具有委派許可權的存取令牌。 執行下列命令以代表使用者取得存取權杖：

Install-Module -Name MSAL.PS # Install the MSAL.PS module from PowerShell Gallery

$TenantId = " " # Paste your directory (tenant) ID here.
$AppClientId="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" # Paste your application (client) ID here.

$MsalParams = @{
   ClientId = $AppClientId
   TenantId = $TenantId
   Scopes   = 'https://graph.microsoft.com/User.Read.All','https://graph.microsoft.com/Files.ReadWrite','https://api.securitycenter.windows.com/AdvancedQuery.Read'
}

$MsalResponse = Get-MsalToken @MsalParams
$AccessToken  = $MsalResponse.AccessToken
 
$AccessToken # Display the token in PS console

驗證令牌

1. 將令牌複製並貼到 JWT 中以進行譯碼。
2. 請確定已譯碼令牌內 的角色 宣告包含所需的許可權。

在下圖中，您可以看到從應用程式取得的已譯碼令牌， Incidents.Read.All以及 、 Incidents.ReadWrite.All和 AdvancedHunting.Read.All 權限：

使用令牌來存取 Microsoft Defender 全面偵測回應 API

1. 選擇您想要使用 (事件或進階搜捕) 的 API。 如需詳細資訊，請參閱支援的 Microsoft Defender 全面偵測回應 API。
2. 在您即將傳送的 HTTP 要求中，將授權標頭設定為 "Bearer" <token>， 將 Bearer 設定為授權配置，並將 令牌 設定為已驗證的令牌。
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 全面偵測回應 API 概觀
• 存取 Microsoft Defender 全面偵測回應 API
• 建立 『Hello world』 應用程式
• 建立應用程式以存取沒有使用者的 Microsoft Defender 全面偵測回應
• 建立具有多租用戶合作夥伴存取 Microsoft Defender 全面偵測回應 API 的應用程式
• 瞭解 API 限制和授權
• 瞭解錯誤碼
• 使用者登入和 API 存取的 OAuth 2.0 授權

提示

想要深入了解? 請到我們的技術社群中與 Microsoft 安全性社群互動: Microsoft Defender 全面偵測回應技術社群。