透過適用於端點Microsoft Defender 的合作夥伴存取 API

適用於：

• 適用於端點的 Microsoft Defender 方案 1
• 適用於端點的 Microsoft Defender 方案 2
• 適用於企業的 Microsoft Defender

重要事項

商務用Defender不包含進階搜捕功能。

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

注意事項

如果您是美國政府客戶，請使用 適用於美國政府客戶的 Microsoft Defender 中所列的 URI。

提示

為了獲得更好的效能，您可以使用更接近您地理位置的伺服器：

• us.api.security.microsoft.com
• eu.api.security.microsoft.com
• uk.api.security.microsoft.com
• au.api.security.microsoft.com
• swa.api.security.microsoft.com

此頁面說明如何建立 Microsoft Entra 應用程式，以程式設計方式代表您的客戶存取適用於端點的 Microsoft Defender。

Microsoft適用於端點的 Defender 會透過一組程式設計 API 公開其大部分的數據和動作。 這些 API 可協助您根據適用於端點Microsoft Defender 功能，將工作流程自動化並進行創新。 API 存取需要 OAuth2.0 驗證。 如需詳細資訊，請參閱 OAuth 2.0 授權碼流程。

一般而言，您需要採取下列步驟來使用 API：

1. 建立多租使用者Microsoft Entra 應用程式。

2. 取得客戶系統管理員) 授權 (同意，讓您的應用程式能夠存取其所需的適用於端點的 Defender 資源。

3. 使用此應用程式取得存取令牌。

4. 使用令牌存取適用於端點Microsoft Defender API。

下列步驟會引導您建立 Microsoft Entra 應用程式、取得適用於端點的 Defender Microsoft存取令牌，以及驗證令牌。

重要事項

Microsoft建議您使用許可權最少的角色。 這有助於改善貴組織的安全性。 全域管理員是高度特殊許可權的角色，當您無法使用現有角色時，應該僅限於緊急案例。

建立多租用戶應用程式

1. 使用具有全域管理員角色的使用者登入您的 Azure 租使用者。

2. 流覽至 [Microsoft登錄][應用程式>註冊>][新增註冊]。

   

3. 在註冊表單中：

   • 選擇應用程式的名稱。

   • 支援的帳戶類型 - 任何組織目錄中的帳戶。

   • 重新導向 URI - 類型：Web、URI： https://portal.azure.com

     

4. 允許您的應用程式存取適用於端點Microsoft Defender，並以完成整合所需的最低許可權集指派它。

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

   • WindowsDefenderATP 不會出現在原始清單中。 開始在文字框中寫入其名稱，以查看其出現。

     

要求 API 許可權

若要判斷您需要的許可權，請檢閱您要呼叫之 API 中的許可權區段。 例如：

• 若 要執行進階查詢，請選取 [ 執行進階查詢] 權 限。
• 若 要隔離裝置，請選取 [隔離機器] 權 限。

在下列範例中，我們使用 [讀取所有警示] 權 限：

1. 選擇 [應用程式許可權>] [警示]。[讀取]。在 [新增許可權] 上選取 [全部>]

   

2. 選 取 [授與同意]

   • 每次新增許可權時，您都必須選取 [ 授與同意 ]，新許可權才會生效。

   

3. 將秘密新增至應用程式。

   • 選 取 [憑證 & 秘密]，將描述新增至秘密，然後選取 [ 新增]。

   選取 [ 新增] 之後，請務必複製產生的秘密值。 離開之後就無法擷取！

   

4. 記下您的應用程式識別碼：

   • 在您的應用程式頁面上，移至 [ 概觀 ] 並複製下列資訊：

     

5. 將應用程式新增至客戶的租使用者。

   您需要在您想要使用應用程式的每個客戶租使用者中核准您的應用程式。 此核准是必要的，因為您的應用程式會代表您的客戶與 Microsoft Defender for Endpoint 應用程式互動。

   具有客戶租使用者之 全域管理員 的用戶必須選取同意連結並核准您的應用程式。

   同意連結的形式如下：

   https://login.microsoftonline.com/common/oauth2/authorize?prompt=consent&client_id=00000000-0000-0000-0000-000000000000&response_type=code&sso_reload=true
   

   應將何處 00000000-0000-0000-0000-000000000000 取代為您的應用程式識別碼。

   選取同意連結之後，以客戶租使用者的全域管理員身分登入並同意應用程式。

   

   此外，您必須向客戶要求其租使用者標識碼，並將其儲存以供日後取得令牌時使用。

6. 完成！ 您已成功註冊應用程式！ 請參閱下列令牌擷取和驗證範例。

取得存取令牌範例

若要代表您的客戶取得存取令牌，請在下列令牌取得時使用客戶的租用戶識別碼。

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

使用 PowerShell

# That code gets the App Context Token and save it to a file named "Latest-token.txt" under the current directory
# Paste below your Tenant ID, App ID and App Secret (App key).

$tenantId = '' ### Paste your tenant ID here
$appId = '' ### Paste your Application ID here
$appSecret = '' ### Paste your Application key here

$resourceAppIdUri = 'https://api.securitycenter.microsoft.com'
$oAuthUri = "https://login.microsoftonline.com/$TenantId/oauth2/token"
$authBody = [Ordered] @{
    resource = "$resourceAppIdUri"
    client_id = "$appId"
    client_secret = "$appSecret"
    grant_type = 'client_credentials'
}
$authResponse = Invoke-RestMethod -Method Post -Uri $oAuthUri -Body $authBody -ErrorAction Stop
$token = $authResponse.access_token
Out-File -FilePath "./Latest-token.txt" -InputObject $token
return $token

使用 C#

重要事項

Microsoft.IdentityModel.Clients.ActiveDirectory NuGet 套件和 Azure AD 驗證連結庫 (ADAL) 已被取代。 自 2020 年 6 月 30 日起，尚未新增任何新功能。 若要升級，請參閱 移轉指南。

1. 建立新的主控台應用程式。

2. 安裝 NuGet Microsoft.Identity.Client。

3. 使用程式代碼新增下列專案：

    using Microsoft.Identity.Client;
   

   此程式代碼已使用 NuGet Microsoft.Identity.Client進行測試。

4. 在應用程式中複製/貼上下列程式代碼 (別忘了更新三個變數： tenantId、 appId和 appSecret) 。

   string tenantId = "00000000-0000-0000-0000-000000000000"; // Paste your own tenant ID here
   string appId = "11111111-1111-1111-1111-111111111111"; // Paste your own app ID here
   string appSecret = "22222222-2222-2222-2222-222222222222"; // Paste your own app secret here for a test, and then store it in a safe place! 
   const string authority = https://login.microsoftonline.com;
   const string audience = https://api.securitycenter.microsoft.com;
   
   IConfidentialClientApplication myApp = ConfidentialClientApplicationBuilder.Create(appId).WithClientSecret(appSecret).WithAuthority($"{authority}/{tenantId}").Build();
   
   List<string> scopes = new List<string>() { $"{audience}/.default" };
   
   AuthenticationResult authResult = myApp.AcquireTokenForClient(scopes).ExecuteAsync().GetAwaiter().GetResult();
   
   string token = authResult.AccessToken;
   

使用 Python

請參閱 使用 Python 取得令牌。

使用 Curl

注意事項

下列程序假設 Curl for Windows 已安裝在您的電腦上

1. 開啟命令視窗。

2. 設定 CLIENT_ID 為您的 Azure 應用程式識別碼。

3. 設定 CLIENT_SECRET 為您的 Azure 應用程式秘密。

4. 設定 TENANT_ID 為想要使用您的應用程式來存取適用於端點的Defender應用程式Microsoft客戶的 Azure 租使用者識別碼。

5. 執行下列命令：

   curl -i -X POST -H "Content-Type:application/x-www-form-urlencoded" -d "grant_type=client_credentials" -d "client_id=%CLIENT_ID%" -d "scope=https://securitycenter.onmicrosoft.com/windowsatpservice/.default" -d "client_secret=%CLIENT_SECRET%" "https://login.microsoftonline.com/%TENANT_ID%/oauth2/v2.0/token" -k
   

   您會得到類似下列代碼段的答案：

   {"token_type":"Bearer","expires_in":3599,"ext_expires_in":0,"access_token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIn <truncated> aWReH7P0s0tjTBX8wGWqJUdDA"}
   

驗證令牌

確認您已收到正確的令牌。

1. 將您在上一個步驟中取得的令牌複製/貼到 JWT 中，以便將它譯碼。

2. 確認您取得具有適當許可權的角色宣告。

   在下列螢幕快照中，您可以看到從具有多個許可權的應用程式取得的已譯碼令牌Microsoft適用於端點的 Defender：

   

   “tid” 宣告是令牌所屬的租用戶標識符。

使用令牌存取適用於端點Microsoft Defender API

1. 選擇您想要使用的 API。 如需詳細資訊，請 參閱支援Microsoft適用於端點的Defender API。

2. 在您傳送至 Bearer {token} 的 Http 要求中設定 Authorization 標頭， (持有人是授權配置) 。 令牌的到期時間是一小時， (您可以傳送多個具有相同令牌) 的要求。

   以下是使用 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
   

另請參閱

• 受支援的適用於端點的 Microsoft Defender API
• 代表使用者存取適用於端點的Defender Microsoft

提示

想要深入了解? 在我們的技術社群中與Microsoft安全性社群互動：Microsoft適用於端點的Defender技術社群。