Create 可讓合作夥伴存取 Microsoft Defender 全面偵測回應 API 的應用程式

發行項
04/27/2024

適用於：

Microsoft Defender XDR

重要事項

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

此頁面描述如何建立 Microsoft Entra 應用程式，以程式設計方式代表多個租用戶的使用者存取 Microsoft Defender 全面偵測回應。多租使用者應用程式適用於為大型使用者群組提供服務。

如果您需要以程式設計方式代表單一使用者存取 Microsoft Defender 全面偵測回應，請參閱 Create 應用程式代表使用者存取 Microsoft Defender 全面偵測回應 API。例如，如果您不需要使用者明確定義 (的存取權，如果您要撰寫背景應用程式或精靈) ，請參閱 Create 應用程式存取沒有使用者的 Microsoft Defender 全面偵測回應。如果您不確定需要哪種存取，請參閱開始使用。

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

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

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

由於此應用程式是多租使用者，因此您也需要每個租使用者代表其用戶的系統管理員同意。

本文說明如何：

Create 多租使用者 Microsoft Entra 應用程式
取得使用者系統管理員的授權同意，讓您的應用程式存取所需的資源 Microsoft Defender 全面偵測回應。
取得存取令牌以 Microsoft Defender 全面偵測回應
驗證令牌

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

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

Create 多租使用者 Microsoft Entra 應用程式。
取得用戶系統管理員) 的授權 (同意，讓您的應用程式存取所需的 Microsoft Defender 全面偵測回應資源。
使用此應用程式取得存取令牌。
使用令牌來存取 Microsoft Defender 全面偵測回應 API。

下列步驟會引導您如何建立多租使用者 Microsoft Entra 應用程式、取得存取令牌以 Microsoft Defender 全面偵測回應並驗證令牌。

Create 多租用戶應用程式

以具有全域管理員角色的使用者身分登入 Azure。
流覽至 Microsoft Entra ID>應用程式註冊>新增註冊。
在註冊表單中：
- 選擇應用程式的名稱。
- 從 [支持的帳戶類型] 中，選取 [任何組織目錄中的帳戶] ([任何 Microsoft Entra 目錄) - 多租使用者]。
- 填寫 [ 重新導向 URI] 區 段。選取 [ Web ] 類型，並將重新導向 URI 指定為 https://portal.azure.com。
填寫完窗體之後，請選取 [ 註冊]。
在您的應用程式頁面上，選取 [API 許可權>][新增我的組織使用的>許可權 > API]，輸入 Microsoft 威脅防護，然後選取 [Microsoft 威脅防護]。您的應用程式現在可以存取 Microsoft Defender 全面偵測回應。

提示

Microsoft 威脅防護是 Microsoft Defender 全面偵測回應的先前名稱，不會出現在原始清單中。您必須開始在文字框中寫入其名稱，才能看到它出現。
選取 應用程式權限。選擇案例的相關許可權 (例如 Incident.Read.All) ，然後選取 [ 新增許可權]。

注意事項

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

例如，若要執行進階查詢，請選取 [執行進階查詢] 許可權;若要隔離裝置，請選取 [隔離機器] 許可權。
選 取 [授與系統管理員同意]。每次新增許可權時，您都必須選取 [ 授與系統管理員同意 ] 使其生效。
若要將秘密新增至應用程式，請選 取 [憑證 & 秘密]，將描述新增至秘密，然後選取 [ 新增]。

提示

選取 [ 新增] 之後，選取 [複製產生的秘密] 值。離開之後，您將無法擷取秘密值。
在安全的地方記錄您的應用程式識別碼和租用戶標識碼。它們會列在應用程式頁面的 [ 概觀 ] 底下。
將應用程式新增至使用者的租使用者。

由於您的應用程式會代表您的使用者與 Microsoft Defender 全面偵測回應互動，因此需要針對您想要使用的每個租使用者核准。

來自使用者租使用者的 全域管理員 必須檢視同意連結並核准您的應用程式。

同意連結的形式如下：
```
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 應該取代為您的應用程式識別碼。

按兩下同意連結之後，請使用使用者租使用者的全域管理員登入並同意應用程式。

您也必須向使用者要求其租用戶標識碼。租用戶標識碼是用來取得存取令牌的其中一個標識符。

完成！ 您已成功註冊應用程式！
請參閱下面的令牌取得和驗證範例。

取得存取權杖

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

重要事項

雖然本節中的範例鼓勵您貼入秘密值以供測試之用，但您絕對不應該將 秘密硬式編碼 成在生產環境中執行的應用程式。第三方可以使用您的秘密來存取資源。您可以使用 Azure 金鑰保存庫來協助保護應用程式的秘密。如需如何保護應用程式的實際範例，請參閱使用 Azure 金鑰保存庫管理伺服器應用程式中的秘密。

提示

在下列範例中，使用使用者的租使用者標識碼來測試腳本是否正常運作。

使用 PowerShell 取得存取令牌

# This code gets the application context token and saves it to a file named "Latest-token.txt" under the current directory.

$tenantId = '' # Paste your directory (tenant) ID here
$clientId = '' # Paste your application (client) ID here
$appSecret = '' # Paste your own app secret here to test, then store it in a safe place!

$resourceAppIdUri = 'https://api.security.microsoft.com'
$oAuthUri = "https://login.windows.net/$tenantId/oauth2/token"

$authBody = [Ordered] @{
    resource = $resourceAppIdUri
    client_id = $clientId
    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 取得存取令牌#

注意事項

下列程式代碼已使用 Nuget Microsoft.Identity.Client 3.19.8 進行測試。

重要事項

Microsoft.IdentityModel.Clients.ActiveDirectory NuGet 套件和 Azure AD 驗證 Library (ADAL) 已被取代。自 2020 年 6 月 30 日起，尚未新增任何新功能。強烈建議您升級，如需詳細資訊，請參閱移轉指南。

Create 新的主控台應用程式。
安裝 NuGet Microsoft.Identity.Client。
新增下列這一行：
```
using Microsoft.Identity.Client;
```

將下列程式代碼複製並貼到您的應用程式 (別忘了更新三個變數： tenantId、 clientId、 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 取得存取令牌

import json
import urllib.request
import urllib.parse

tenantId = '' # Paste your directory (tenant) ID here
clientId = '' # Paste your application (client) ID here
appSecret = '' # Paste your own app secret here to test, then store it in a safe place, such as the Azure Key Vault!

url = "https://login.windows.net/%s/oauth2/token" % (tenantId)

resourceAppIdUri = 'https://api.security.microsoft.com'

body = {
    'resource' : resourceAppIdUri,
    'client_id' : clientId,
    'client_secret' : appSecret,
    'grant_type' : 'client_credentials'
}

data = urllib.parse.urlencode(body).encode("utf-8")

req = urllib.request.Request(url, data)
response = urllib.request.urlopen(req)
jsonResponse = json.loads(response.read())
aadToken = jsonResponse["access_token"]

使用 curl 取得存取令牌

注意事項

Curl 已預安裝在 Windows 10 1803 版和更新版本上。針對其他版本的 Windows，請直接從官方 curl 網站下載並安裝工具。

開啟命令提示字元，並將CLIENT_ID設定為您的 Azure 應用程式識別碼。
將CLIENT_SECRET設定為您的 Azure 應用程式秘密。
將TENANT_ID設定為想要使用您的應用程式存取 Microsoft Defender 全面偵測回應之使用者的 Azure 租使用者識別碼。
執行下列命令：

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"}

驗證令牌

將令牌複製並貼到 JSON Web 令牌驗證程式網站 JWT，以將其譯碼。
請確定已譯碼令牌內 的角色 宣告包含所需的許可權。

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

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

選擇您想要使用 (事件或進階搜捕) 的 API。如需詳細資訊，請參閱支援的 Microsoft Defender 全面偵測回應 API。
在您即將傳送的 HTTP 要求中，將授權標頭設定為 "Bearer" <token>， 將 Bearer 設定為授權配置，並將令牌設定為已驗證的令牌。
令牌將在一小時內過期。在此期間，您可以使用相同的令牌傳送多個要求。

下列範例示範如何傳送要求，以 使用 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();

提示

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

Share via

Create 可讓合作夥伴存取 Microsoft Defender 全面偵測回應 API 的應用程式

Create 多租用戶應用程式

取得存取權杖

使用 PowerShell 取得存取令牌

使用 C 取得存取令牌#

使用 Python 取得存取令牌

使用 curl 取得存取令牌

驗證令牌

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

意見反應

意見反應

其他資源

Share via

Create 可讓合作夥伴存取 Microsoft Defender 全面偵測回應 API 的應用程式

Create 多租用戶應用程式

取得存取權杖

使用 PowerShell 取得存取令牌

使用 C 取得存取令牌#

使用 Python 取得存取令牌

使用 curl 取得存取令牌

驗證令牌

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

相關文章

意見反應

意見反應

其他資源