Share via


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

適用於:

重要事項

商務用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:

  • Create 多租使用者 Microsoft Entra 應用程式。
  • 取得客戶系統管理員) 授權 (同意,讓您的應用程式能夠存取其所需的適用於端點的 Defender 資源。
  • 使用此應用程式取得存取令牌。
  • 使用令牌來存取 適用於端點的 Microsoft Defender API。

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

Create 多租用戶應用程式

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

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

    瀏覽至應用程式註冊窗格

  3. 在註冊表單中:

    • 選擇應用程式的名稱。

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

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

      Microsoft Azure 合作夥伴應用程式註冊頁面

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

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

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

      [新增許可權] 選項

要求 API 許可權

若要判斷您需要的許可權,請檢閱您想要呼叫之 API 中的許可權一節。 例如:

在下列範例中,我們使用 「讀取所有警示」權 限:

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

    允許新增許可權的選項

  2. 取 [授與同意]

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

    允許授與同意的選項

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

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

    重要:選取 [ 新增] 之後,請務必複製產生的秘密值。 離開之後就無法擷取!

    建立應用程式金鑰

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

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

      建立應用程式的標識碼

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

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

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

    同意連結的形式如下:

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

    其中 000000000-0000-0000-0000-0000000000000 應該取代為您的應用程式識別符

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

    [接受] 按鈕

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

  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#

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

重要事項

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

  • Create 新的主控台應用程式

  • 安裝 NuGet Microsoft.Identity.Client

  • 使用 新增下列內容

    using Microsoft.Identity.Client;
    
  • 在應用程式中複製/貼上下列程式代碼 (別忘了更新三個變數: tenantIdappIdappSecret)

    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設定為想要使用您的應用程式來存取 適用於端點的 Microsoft Defender 應用程式之客戶的 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 標頭 (Bearer 是授權配置) 。 令牌的到期時間為 1 小時, (您可以傳送多個具有相同令牌) 的要求。

    以下是傳送要求以使用 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
    

另請參閱

提示

想要深入了解? Engage 技術社群中的 Microsoft 安全性社群:適用於端點的 Microsoft Defender 技術社群。