Create 應用程式存取沒有使用者的 Microsoft Defender 全面偵測回應

  • 發行項

適用於：

  • Microsoft Defender XDR

重要事項

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

此頁面描述如何建立應用程式，以程式設計方式存取沒有已定義使用者的 Microsoft Defender 全面偵測回應，例如，如果您要建立精靈或背景服務。

如果您需要以程式設計方式代表一或多個使用者存取 Microsoft Defender 全面偵測回應，請參閱 Create 應用程式代表使用者存取 Microsoft Defender 全面偵測回應 API，並 Create 具有合作夥伴存取權的應用程式Microsoft Defender 全面偵測回應 API。 如果您不確定需要哪種存取，請參閱 開始使用。

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

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

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

本文說明如何：

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

Create 應用程式

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

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

    Microsoft Defender 入口網站中的 [新增註冊] 索引標籤

  3. 在表單中，選擇應用程式的名稱，然後選取 [ 註冊]。

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

    提示

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

    Microsoft Defender 入口網站中的組織 API 使用量索引標籤

  5. 選取 應用程式權限。 選擇案例的相關許可權 (例如 Incident.Read.All) ，然後選取 [ 新增許可權]。

    Microsoft Defender 入口網站中的應用程式許可權窗格

    注意事項

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

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

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

    Microsoft Defender 入口網站中的同意授與相關窗格

  7. 若要將秘密新增至應用程式，請選 取 [憑證 & 秘密]，將描述新增至秘密，然後選取 [ 新增]。

    提示

    選取 [ 新增] 之後，選取 [複製產生的秘密] 值。 離開之後，您將無法擷取秘密值。

    Microsoft Defender 入口網站中的 [建立應用程式] 窗格

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

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

  9. 僅限 Microsoft Defender 全面偵測回應 合作夥伴：請遵循這些指示，透過 Microsoft Defender 全面偵測回應 API 存取合作夥伴，將您的應用程式設定為多租使用者，以便在您收到系統管理員同意後，即可在所有租使用者中使用。 第三方應用程式 需要 合作夥伴存取權，例如，如果您建立要在多個客戶租用戶中執行的應用程式。 如果您建立只想要在租用戶中執行的服務，例如僅與您自己的數據互動的應用程式，則 不需要 這麼做。 若要將您的應用程式設定為多租使用者：

    • 移至 [驗證]，並將 新增 https://portal.azure.com 為 [重新導向 URI]。

    • 在頁面底部的 [ 支持的帳戶類型] 底下，選取您多租使用者應用程式 的任何組織目錄 應用程式同意中的 [帳戶]。

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

    每個租使用者的 Active Directory 全域管理員都必須選取同意連結並核准您的應用程式。

    同意連結具有下列結構：

    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, such as the Azure Key Vault!

$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 日起，尚未新增任何新功能。 強烈建議您升級，如需詳細資訊，請參閱 移轉指南 。

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

  2. 安裝 NuGet Microsoft.Identity.Client。

  3. 新增下列這一行：

    using Microsoft.Identity.Client;

  4. 將下列程式代碼複製並貼到您的應用程式 (別忘了更新三個變數： tenantId、 clientId、 appSecret) ：

    csharp
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 網站下載並安裝工具。

  1. 開啟命令提示字元，並將CLIENT_ID設定為您的 Azure 應用程式識別碼。

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

  3. 將TENANT_ID設定為想要使用您的應用程式來存取 Microsoft Defender 全面偵測回應 之客戶的 Azure 租使用者識別碼。

  4. 執行下列命令：

    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://api.security.microsoft.com/.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. 將令牌複製並貼到 JSON Web 令牌驗證程式網站 JWT， 以將其譯碼。

  2. 請確定已譯碼令牌內 的角色 宣告包含所需的許可權。

    在下圖中，您可以看到從應用程式取得的已譯碼令牌， Incidents.Read.All以及 、 Incidents.ReadWrite.All和 AdvancedHunting.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();

提示

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