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

注意事項

想要體驗Microsoft Defender 全面偵測回應嗎? 深入瞭解如何評估和試驗Microsoft Defender 全面偵測回應

適用於:

  • Microsoft Defender 全面偵測回應

重要事項

部分資訊與發行前版本產品有關,在正式發行之前可能會實質上進行修改。 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應用程式。
  • 使用此應用程式取得存取權杖。
  • 使用權杖存取 API Microsoft Defender 全面偵測回應。

本文說明如何:

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

注意事項

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

提示

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

建立應用程式

  1. 以具有全域管理員角色的使用者身分登入Azure

  2. 流覽至Microsoft Entra標識>符應用程式註冊>新增註冊

    Azure 入口網站中 [管理] 窗格中的 [新增註冊] 選項

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

    Azure 入口網站中的應用程式註冊窗格

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

    提示

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

    Microsoft Defender入口網站中的組織 API 窗格

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

      Microsoft Defender入口網站中的 [委派的許可權] 窗格

    注意事項

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

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

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

    Microsoft Defender入口網站中的管理員同意授與窗格

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

    Microsoft Defender入口網站中的 [概觀] 窗格

取得存取權杖

如需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.AllAdvancedHunting.Read.All 許可權:

Microsoft Defender入口網站中 [已解碼的權杖] 窗格中的許可權區段

使用權杖來存取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 安全性社群互動:Microsoft Defender 全面偵測回應技術社群。