建立具有合作夥伴存取 Microsoft Defender 全面偵測回應 API 的應用程式
適用於:
- Microsoft Defender XDR
重要
部分資訊與發行前版本產品有關,在正式發行之前可能會實質上進行修改。 Microsoft 對此處提供的資訊,不提供任何明確或隱含的瑕疵擔保。
此頁面描述如何建立 Microsoft Entra 應用程式,以程式設計方式代表多個租用戶的使用者存取 Microsoft Defender 全面偵測回應。 多租使用者應用程式適用於為大型使用者群組提供服務。
如果您需要以程式設計方式存取代表單一使用者 Microsoft Defender 全面偵測回應,請參閱建立應用程式以代表使用者存取 Microsoft Defender 全面偵測回應 API。 例如,如果您不需要使用者明確定義的存取權 (,如果您要撰寫背景應用程式或精靈) ,請參閱建立應用程式以存取 Microsoft Defender 全面偵測回應 而不使用使用者。 如果您不確定需要哪種存取,請參閱 開始使用。
Microsoft Defender 全面偵測回應 會透過一組程序設計 API 公開其大部分的數據和動作。 這些 API 可協助您將工作流程自動化,並利用 Microsoft Defender 全面偵測回應 功能。 此 API 存取需要 OAuth2.0 驗證。 如需詳細資訊,請參閱 OAuth 2.0 授權碼流程。
一般而言,您必須採取下列步驟來使用這些 API:
- 建立 Microsoft Entra 應用程式。
- 使用此應用程式取得存取令牌。
- 使用令牌存取 API Microsoft Defender 全面偵測回應。
由於此應用程式是多租使用者,因此您也需要每個租使用者代表其用戶的 系統管理員同意 。
本文說明如何:
- 建立多租使用者 Microsoft Entra 應用程式
- 取得使用者系統管理員對應用程式的授權同意,以存取所需的 Microsoft Defender 全面偵測回應 資源。
- 取得存取令牌以 Microsoft Defender 全面偵測回應
- 驗證令牌
Microsoft Defender 全面偵測回應 會透過一組程序設計 API 公開其大部分的數據和動作。 這些 API 可協助您將工作流程自動化,並根據 Microsoft Defender 全面偵測回應 功能進行創新。 API 存取需要 OAuth2.0 驗證。 如需詳細資訊,請參閱 OAuth 2.0 授權碼流程。
一般而言,您必須採取下列步驟來使用 API:
- 建立多租使用者 Microsoft Entra 應用程式。
- 取得使用者系統管理員) 授權 (同意,讓您的應用程式存取所需的 Microsoft Defender 全面偵測回應 資源。
- 使用此應用程式取得存取令牌。
- 使用令牌存取 API Microsoft Defender 全面偵測回應。
下列步驟會引導您如何建立多租使用者 Microsoft Entra 應用程式、取得存取令牌以 Microsoft Defender 全面偵測回應 並驗證令牌。
登入 Azure。
流覽至 Microsoft Entra ID>應用程式註冊>新增註冊。
在註冊表單中:
- 選擇應用程式的名稱。
- 從 [支持的帳戶類型] 中,選取 [任何組織目錄中的帳戶] ([任何 Microsoft Entra 目錄) - 多租使用者]。
- 填寫 [ 重新導向 URI] 區 段。 選取 [ Web ] 類型,並將重新導向 URI 指定為 https://portal.azure.com。
填寫完窗體之後,請選取 [ 註冊]。
在您的應用程式頁面上,選取 [API 權>限][新增>我的組織使用的>許可權 API]、輸入 Microsoft Threat Protection],然後選取 [Microsoft威脅防護]。 您的應用程式現在可以存取 Microsoft Defender 全面偵測回應。
提示
Microsoft威脅防護是 Microsoft Defender 全面偵測回應 的先前名稱,不會出現在原始清單中。 您必須開始在文字框中寫入其名稱,才能看到它出現。
選取 應用程式權限。 選擇案例的相關許可權 (例如 Incident.Read.All) ,然後選取 [ 新增許可權]。
選 取 [授與系統管理員同意]。 每次新增許可權時,您都必須選取 [ 授與系統管理員同意 ] 使其生效。
若要將秘密新增至應用程式,請選 取 [憑證 & 秘密],將描述新增至秘密,然後選取 [ 新增]。
提示
選取 [ 新增] 之後,選取 [複製產生的秘密] 值。 離開之後,您將無法擷取秘密值。
在安全的地方記錄您的應用程式識別碼和租用戶標識碼。 它們會列在應用程式頁面的 [ 概觀 ] 底下。
將應用程式新增至使用者的租使用者。
由於您的應用程式會代表您的使用者與 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 金鑰保存庫 管理伺服器應用程式中的秘密。
提示
在下列範例中,使用使用者的租使用者標識碼來測試腳本是否正常運作。
# 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
注意
下列程式代碼已使用 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
) :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://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
權限:
- 選擇您想要使用 (事件或進階搜捕) 的 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 全面偵測回應
- 建立應用程式以代表使用者存取 Microsoft Defender 全面偵測回應 API
- 瞭解 API 限制和授權
- 瞭解錯誤碼
- 使用 Azure 金鑰保存庫 管理伺服器應用程式中的秘密
- 使用者登入和 API 存取的 OAuth 2.0 授權
提示
想要深入了解? 請到我們的技術社群中與 Microsoft 安全性社群互動: Microsoft Defender 全面偵測回應技術社群。