建立應用程式,以代表使用者存取 Microsoft 365 Defender APIsCreate an app to access Microsoft 365 Defender APIs on behalf of a user

重要

改良的 Microsoft 365 安全性中心現在可用。The improved Microsoft 365 security center is now available. 這個新的體驗會將適用於端點的 Defender、適用於 Office 365 的 Defender、Microsoft 365 Defender 和更多功能帶到 Microsoft 365 安全性中心。This new experience brings Defender for Endpoint, Defender for Office 365, Microsoft 365 Defender, and more into the Microsoft 365 security center. 了解新功能Learn what's new.

適用於:Applies to:

  • Microsoft 365 DefenderMicrosoft 365 Defender

重要

部分資訊與發行前版本產品有關,在正式發行之前可能會實質上進行修改。Some information relates to prereleased product which may be substantially modified before it's commercially released. Microsoft 對此處提供的資訊,不提供任何明確或隱含的瑕疵擔保。Microsoft makes no warranties, express or implied, with respect to the information provided here.

此頁面說明如何建立應用程式,以對單一使用者以程式設計方式存取 Microsoft 365 Defender。This page describes how to create an application to get programmatic access to Microsoft 365 Defender on behalf of a single user.

如果您需要以程式設計方式存取 Microsoft 365 Defender,但沒有定義的使用者 (例如,如果您正在撰寫後臺應用程式或幕後程式) ,請參閱Create a app to access Microsoft 365 Defender (沒有使用者)。If you need programmatic access to Microsoft 365 Defender without a defined user (for example, if you're writing a background app or daemon), see Create an app to access Microsoft 365 Defender without a user. 如果您需要為多個承租人提供存取權,例如,如果您正在服務大型組織或客戶群組,請參閱 Create a app with partner access to Microsoft 365 Defender APIs。如果您不確定需要哪種類型的存取,請參閱入門If you need to provide access for multiple tenants—for example, if you're serving a large organization or a group of customers—see Create an app with partner access to Microsoft 365 Defender APIs.If you're not sure which kind of access you need, see Get started.

Microsoft 365Defender 會透過一組程式設計 APIs 來公開其大部分資料和動作。Microsoft 365 Defender exposes much of its data and actions through a set of programmatic APIs. 這些 APIs 可協助您自動化工作流程,並利用 Microsoft 365 Defender 的功能。Those APIs help you automate workflows and make use of Microsoft 365 Defender's capabilities. 此 API access 需要 OAuth 2.0 驗證。This API access requires OAuth2.0 authentication. 如需詳細資訊,請參閱OAuth 2.0 授權碼 FlowFor more information, see OAuth 2.0 Authorization Code Flow.

一般來講,您必須採取下列步驟,才能使用這些 APIs:In general, you'll need to take the following steps to use these APIs:

  • 建立 Azure Active Directory (Azure AD) 應用程式。Create an Azure Active Directory (Azure AD) application.
  • 使用此應用程式取得存取權杖。Get an access token using this application.
  • 使用權杖存取 Microsoft 365 Defender API。Use the token to access Microsoft 365 Defender API.

本文將說明如何:This article explains how to:

  • 建立 Azure AD 應用程式Create an Azure AD application
  • 取得 Microsoft 365 Defender 的存取權杖Get an access token to Microsoft 365 Defender
  • 驗證 tokenValidate the token

注意

當您代表使用者存取 Microsoft 365 Defender API 時,您將需要正確的應用程式許可權和使用者許可權。When accessing Microsoft 365 Defender API on behalf of a user, you will need the correct application permissions and user permissions.

提示

如果您有許可權執行入口網站中的動作,您就具有在 API 中執行該動作的許可權。If you have the permission to perform an action in the portal, you have the permission to perform the action in the API.

建立應用程式Create an app

  1. 全域系統管理員 角色的使用者身分登入 AzureSign in to Azure as a user with the Global Administrator role.

  2. 流覽至 Azure Active Directory > App 註冊 > 新註冊Navigate to Azure Active Directory > App registrations > New registration.

    Microsoft Azure 及流覽至應用程式註冊的影像

  3. 在表單中,為您的應用程式選擇一個名稱,並輸入下列重新導向 URI 的資訊,然後選取 [ 註冊]。In the form, choose a name for your application and enter the following information for the redirect URI, then select Register.

    建立應用程式視窗的影像

  4. 在 [應用程式] 頁面上,選取 [ API 許可權 > 新增許可權 > APIs 我的組織使用>],輸入 Microsoft 威脅防護,然後選取 Microsoft 威脅防護On your application page, select API Permissions > Add permission > APIs my organization uses >, type Microsoft Threat Protection, and select Microsoft Threat Protection. 您的應用程式現在可以存取 Microsoft 365 Defender。Your app can now access Microsoft 365 Defender.

    提示

    Microsoft 威脅防護 是 Microsoft 365 Defender 的先前名稱,而且不會出現在原始清單中。Microsoft Threat Protection is a former name for Microsoft 365 Defender, and will not appear in the original list. 您必須先在文字方塊中寫入其名稱,才能看到顯示的名稱。You need to start writing its name in the text box to see it appear.

    API 許可權選取的影像

    • 選擇 [ 委派許可權]。Choose Delegated permissions. 為案例選擇相關許可權 (例如 事件。 Read) ,然後選取 [ 新增許可權]。Choose the relevant permissions for your scenario (for example Incident.Read), and then select Add permissions.

    API 存取和 API 選取的影像

    注意

    您必須選取案例的相關許可權。You need to select the relevant permissions for your scenario. 讀取所有的事件 只是一個範例。Read all incidents is just an example. 若要決定您需要的許可權,請參閱您想要呼叫之 API 中的 [ 許可權 ] 區段。To determine which permission you need, please look at the Permissions section in the API you want to call.

    例如,若要 執行高級查詢,請選取「執行高級查詢」許可權;若要 隔離裝置,請選取「隔離電腦」許可權。For instance, to run advanced queries, select the 'Run advanced queries' permission; to isolate a device, select the 'Isolate machine' permission.

  5. 選取 [授與系統管理員同意]。Select Grant admin consent. 每次您新增許可權時,都必須選取 [授與系統管理員同意 ],才會生效。Every time you add a permission, you must select Grant admin consent for it to take effect.

    授與許可權的影像

  6. 將您的應用程式識別碼和租使用者識別碼記錄在安全的位置。Record your application ID and your tenant ID somewhere safe. 在 [應用程式] 頁面的 [一覽 ] 底下會列出它們。They're listed under Overview on your application page.

    建立之應用程式識別碼的影像

取得存取權杖Get an access token

如需 Azure Active Directory 權杖的詳細資訊,請參閱Azure AD 教學課程。For more information on Azure Active Directory tokens, see the Azure AD tutorial.

使用 PowerShell 取得存取權杖Get an access token using PowerShell

if(!(Get-Package adal.ps)) { Install-Package -Name adal.ps } # Install the ADAL.PS package in case it's not already present

$tenantId = '' # Paste your directory (tenant) ID here.
$clientId = '' # Paste your application (client) ID here.
$redirectUri = '' # Paste your app's redirection URI

$authority = "https://login.windows.net/$tenantId"
$resourceUrl = 'https://api.security.microsoft.com'

$response = Get-ADALToken -Resource $resourceUrl -ClientId $cleintId -RedirectUri $redirectUri -Authority $authority -PromptBehavior:Always
$response.AccessToken | clip

$response.AccessToken

驗證 tokenValidate the token

  1. 將權杖複製並貼到 JWT ,以進行解碼。Copy and paste the token into JWT to decode it.
  2. 請確定已解碼權杖中的 角色 宣告包含所需的許可權。Make sure that the roles claim within the decoded token contains the desired permissions.

在下列影像中,您可以看到從應用程式取得的解碼標記,具有 Incidents.Read.AllIncidents.ReadWrite.AllAdvancedHunting.Read.All 許可權:In the following image, you can see a decoded token acquired from an app, with Incidents.Read.All, Incidents.ReadWrite.All, and AdvancedHunting.Read.All permissions:

權杖驗證的影像

使用權杖存取 Microsoft 365 Defender APIUse the token to access the Microsoft 365 Defender API

  1. 選擇您想要使用 (事件或「高級搜尋) 的 API。Choose the API you want to use (incidents, or advanced hunting). 如需詳細資訊,請參閱支援的 Microsoft 365 Defender APIsFor more information, see Supported Microsoft 365 Defender APIs.
  2. 在您要傳送的 HTTP 要求中,將授權標頭設定為 "Bearer" <token>持有 者為授權配置,而 token 為您驗證的權杖。In the http request you're about to send, set the authorization header to "Bearer" <token>, Bearer being the authorization scheme, and token being your validated token.
  3. 權杖會在一小時內到期。The token will expire within one hour. 在此期間,您可以使用相同的權杖傳送一個以上的要求。You can send more than one request during this time with the same token.

下列範例顯示如何 使用 c # 傳送要求以取得事件清單。The following example shows how to send a request to get a list of incidents using 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();