사용자를 대신하여 Microsoft 365 Defender API에 액세스하는 앱 만들기Create 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 프로그래밍 방식의 액세스 권한을 부여하는 응용 프로그램을 만드는 방법을 설명합니다.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에 프로그래밍식 액세스 권한이 필요한 경우(예: 백그라운드 앱 또는 디먼을 작성하는 경우) 사용자 없이 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. 대규모 조직 또는 고객 그룹에게 서비스를 제공하는 경우와 같은 여러 테넌트에 대한 액세스를 제공해야 하는 경우 파트너 액세스로 Microsoft 365 Defender API를 참조하세요. 필요한 액세스 종류가 확실하지 않은 경우 시작을 참조합니다.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 365 Defender는 프로그래밍 API 집합을 통해 많은 데이터와 작업을 노출합니다.Microsoft 365 Defender exposes much of its data and actions through a set of programmatic APIs. 이러한 API를 사용하면 워크플로를 자동화하고 Microsoft 365 기능을 사용할 수 있습니다.Those APIs help you automate workflows and make use of Microsoft 365 Defender's capabilities. 이 API 액세스에는 OAuth2.0 인증이 필요합니다.This API access requires OAuth2.0 authentication. 자세한 내용은 OAuth 2.0 Authorization Code Flow.For more information, see OAuth 2.0 Authorization Code Flow.

일반적으로 이러한 API를 사용하려면 다음 단계를 수행해야 합니다.In general, you'll need to take the following steps to use these APIs:

  • Azure AD(Azure Active Directory 응용 프로그램을 만들 수 있습니다.Create an Azure Active Directory (Azure AD) application.
  • 이 응용 프로그램을 사용하여 액세스 토큰을 얻습니다.Get an access token using this application.
  • 토큰을 사용하여 Defender API에 Microsoft 365 액세스합니다.Use the token to access Microsoft 365 Defender API.

이 문서에서는 이러한 방법을 설명합니다.This article explains how to:

  • Azure AD 응용 프로그램 만들기Create an Azure AD application
  • Defender에 액세스 토큰을 Microsoft 365 수 있습니다.Get an access token to Microsoft 365 Defender
  • 토큰 유효성 검사Validate 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. 전역 관리자 역할을 사용하여 사용자로 Azure에 로그인합니다.Sign in to Azure as a user with the Global Administrator role.

  2. 앱 등록 Azure Active Directory > > 등록으로 이동합니다.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 권한 추가 권한 API를 선택하고 > 를 Microsoft Threat Protection > > 를 Microsoft Threat Protection. On your application page, select API Permissions > Add permission > APIs my organization uses >, type Microsoft Threat Protection, and select Microsoft Threat Protection. 이제 앱이 Defender에 액세스할 Microsoft 365 있습니다.Your app can now access Microsoft 365 Defender.

    Microsoft Threat Protection 은 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. 시나리오에 대한 관련 사용 권한(예: Incident.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. 안전한 곳에 응용 프로그램 ID와 테넌트 ID를 기록합니다.Record your application ID and your tenant ID somewhere safe. 응용 프로그램 페이지 개요 아래에 나열됩니다.They're listed under Overview on your application page.

    생성된 앱 ID의 이미지

액세스 토큰을 얻게 됩니다.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

토큰 유효성 검사Validate 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.All Incidents.ReadWrite.All AdvancedHunting.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 API에 액세스Use the token to access the Microsoft 365 Defender API

  1. 사용할 API(인시던트 또는 고급 헌팅)를 선택하십시오.Choose the API you want to use (incidents, or advanced hunting). 자세한 내용은 Supported Microsoft 365 Defender API를 참조하세요.For more information, see Supported Microsoft 365 Defender APIs.
  2. 보내고자 하는 http 요청에서 권한 부여 헤더를 로 설정하고, 권한 부여 체계인 "Bearer" <token> Bearer를 로 설정하고 유효성이 검사된 토큰이 됩니다. 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. 토큰은 1시간 이내에 만료됩니다.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();