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

適用於：

• Microsoft Defender XDR

重要事項

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

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

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

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

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

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

本文說明如何：

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

注意事項

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

提示

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

Create 應用程式

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

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

   

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

   

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

4. 在您的應用程式頁面上，選取 [API 許可權>][新增我的組織使用的>許可權 > API]，輸入 Microsoft 威脅防護，然後選取 [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
• Create『Hello world』 應用程式
• Create 應用程式存取不含使用者的 Microsoft Defender 全面偵測回應
• Create 具有多租用戶合作夥伴存取 Microsoft Defender 全面偵測回應 API 的應用程式
• 瞭解 API 限制和授權
• 瞭解錯誤碼
• 使用者登入和 API 存取的 OAuth 2.0 授權

提示

想要深入了解? Engage 技術社群中的 Microsoft 安全性社群：Microsoft Defender 全面偵測回應 技術社群。