建立應用程式以存取不含使用者的 Microsoft Defender 全面偵測回應
適用於:
- Microsoft Defender XDR
重要
部分資訊與發行前版本產品有關,在正式發行之前可能會實質上進行修改。 Microsoft 對此處提供的資訊,不提供任何明確或隱含的瑕疵擔保。
此頁面描述如何建立應用程式,以程式設計方式存取沒有已定義使用者的 Microsoft Defender 全面偵測回應,例如,如果您要建立精靈或背景服務。
如果您需要以程式設計方式代表一或多個使用者存取 Microsoft Defender 全面偵測回應,請參閱建立應用程式以代表使用者存取 Microsoft Defender 全面偵測回應 API 和建立具有合作夥伴存取 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 全面偵測回應
- 驗證令牌。
登入 Azure。
流覽至 Microsoft Entra ID>應用程式註冊>新增註冊。
在表單中,選擇應用程式的名稱,然後選取 [ 註冊]。
在您的應用程式頁面上,選取 [API 權>限][新增>我的組織使用的>許可權 API]、輸入 Microsoft Threat Protection],然後選取 [Microsoft威脅防護]。 您的應用程式現在可以存取 Microsoft Defender 全面偵測回應。
提示
Microsoft威脅防護是 Microsoft Defender 全面偵測回應 的先前名稱,不會出現在原始清單中。 您必須開始在文字框中寫入其名稱,才能看到它出現。
選取 應用程式權限。 選擇案例的相關許可權 (例如 Incident.Read.All) ,然後選取 [ 新增許可權]。
選 取 [授與系統管理員同意]。 每次新增許可權時,您都必須選取 [ 授與系統管理員同意 ] 使其生效。
若要將秘密新增至應用程式,請選 取 [憑證 & 秘密],將描述新增至秘密,然後選取 [ 新增]。
提示
選取 [ 新增] 之後,選取 [複製產生的秘密] 值。 離開之後,您將無法擷取秘密值。
在安全的地方記錄您的應用程式識別碼和租用戶標識碼。 它們會列在應用程式頁面的 [ 概觀 ] 底下。
僅限 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 金鑰保存庫 管理伺服器應用程式中的秘密。
# 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
注意
下列程式代碼已使用 Nuget Microsoft.Identity.Client 3.19.8 進行測試。
重要
Microsoft.IdentityModel.Clients.ActiveDirectory NuGet 套件和 Azure AD 驗證 Library (ADAL) 已被取代。 自 2020 年 6 月 30 日起,尚未新增任何新功能。 強烈建議您升級,如需詳細資訊,請參閱 移轉指南 。
建立新的主控台應用程式。
安裝 NuGet Microsoft.Identity.Client。
新增下列這一行:
using Microsoft.Identity.Client;
將下列程式代碼複製並貼到您的應用程式 (別忘了更新三個變數:
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;
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 已預安裝在 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://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"}
將令牌複製並貼到 JSON Web 令牌驗證程式網站 JWT, 以將其譯碼。
請確定已譯碼令牌內 的角色 宣告包含所需的許可權。
在下圖中,您可以看到從應用程式取得的已譯碼令牌,
Incidents.Read.All
以及 、Incidents.ReadWrite.All
和AdvancedHunting.Read.All
權限:
選擇您想要使用 (事件或進階搜捕) 的 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();
- Microsoft Defender 全面偵測回應 API 概觀
- 存取 Microsoft Defender 全面偵測回應 API
- 建立 『Hello world』 應用程式
- 建立應用程式以代表使用者存取 Microsoft Defender 全面偵測回應 API
- 建立具有多租用戶合作夥伴存取 Microsoft Defender 全面偵測回應 API 的應用程式
- 瞭解 API 限制和授權
- 瞭解錯誤碼
- 使用 Azure 金鑰保存庫 管理伺服器應用程式中的秘密
- 使用者登入和 API 存取的 OAuth 2.0 授權
提示
想要深入了解? 請到我們的技術社群中與 Microsoft 安全性社群互動: Microsoft Defender 全面偵測回應技術社群。