파트너가 Defender API에 액세스할 수 있는 Microsoft 365 만들기Create an app with partner access to Microsoft 365 Defender APIs

중요

개선된 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.

이 페이지에서는 여러 테넌트의 사용자를 대신하여 Azure Active Directory Defender에 프로그래밍 방식의 액세스 권한이 있는 Microsoft 365 앱을 만드는 방법을 설명합니다.This page describes how to create an Azure Active Directory app that has programmatic access to Microsoft 365 Defender, on behalf of users across multiple tenants. 다중 테넌트 앱은 대규모 사용자 그룹을 제공하는 데 유용합니다.Multi-tenant apps are useful for serving large groups of users.

단일 사용자를 대신하여 Microsoft 365 Defender에 프로그래밍식 액세스 권한이 필요한 경우 사용자 대신 Microsoft 365 Defender API에 액세스하는 앱 만들기를 참조하세요.If you need programmatic access to Microsoft 365 Defender on behalf of a single user, see Create an app to access Microsoft 365 Defender APIs on behalf of a user. 사용자가 명시적으로 정의되지 않은 액세스가 필요한 경우(예: 백그라운드 앱 또는 디먼을 작성하는 경우) 사용자 없이 Microsoft 365 Defender에 액세스하는 앱 만들기를 참조하세요.If you need access without a user explicitly defined (for example, if you're writing a background app or daemon), see Create an app to access Microsoft 365 Defender without a user. 필요한 액세스 종류가 확실하지 않은 경우 시작을 참조합니다.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.

이 앱은 다중 테넌트이기 때문에 사용자를 대신하여 각 테넌트의 관리자 동의도 필요합니다.Since this app is multi-tenant, you'll also need admin consent from each tenant on behalf of its users.

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

  • 다중 테넌트 Azure AD 응용 프로그램 만들기Create a multi-tenant Azure AD application
  • 응용 프로그램에 대한 사용자 관리자의 승인을 얻어 필요한 Microsoft 365 Defender에 액세스합니다.Get authorized consent from your user administrator for your application to access the Microsoft 365 Defender that resources it needs.
  • Defender에 액세스 토큰을 Microsoft 365 수 있습니다.Get an access token to Microsoft 365 Defender
  • 토큰 유효성 검사Validate the token

Microsoft 365 Defender는 프로그래밍 API 집합을 통해 많은 데이터와 작업을 노출합니다.Microsoft 365 Defender exposes much of its data and actions through a set of programmatic APIs. 이러한 API는 작업 흐름을 자동화하고 다양한 Defender 기능을 기반으로 Microsoft 365 도움이 될 것입니다.Those APIs will help you automate work flows and innovate based on Microsoft 365 Defender capabilities. API 액세스에는 OAuth2.0 인증이 필요합니다.The 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 the APIs:

  • 다중 테넌트 Azure AD 응용 프로그램을 생성합니다.Create a multi-tenant Azure AD application.
  • 응용 프로그램에서 필요한 Defender 리소스에 액세스할 수 있도록 Microsoft 365 승인(동의)합니다.Get authorized (consent) by your user administrator for your application to access Microsoft 365 Defender resources it needs.
  • 이 응용 프로그램을 사용하여 액세스 토큰을 얻습니다.Get an access token using this application.
  • 토큰을 사용하여 Defender API에 Microsoft 365 액세스합니다.Use the token to access Microsoft 365 Defender API.

다음 단계에 따라 다중 테넌트 Azure AD 응용 프로그램을 만들고, Defender에 액세스 토큰을 Microsoft 365 방법을 안내합니다.The following steps with guide you how to create a multi-tenant Azure AD application, get an access token to Microsoft 365 Defender and validate the token.

다중 테넌트 앱 만들기Create the multi-tenant 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. 등록 양식에서 다음을 합니다.In the registration form:

    • 응용 프로그램의 이름을 선택하십시오.Choose a name for your application.
    • 지원되는 계정 유형에서 조직 디렉터리(모든 Azure AD 디렉터리)의 계정 - 다중텐트를 선택합니다.From Supported account types, select Accounts in any organizational directory (Any Azure AD directory) - Multitenant.
    • URI 리디렉션 섹션을 작성합니다.Fill out the Redirect URI section. 형식을 선택하고 리디렉션 URI를 로 https://portal.azure.com 제공합니다.Select type Web and give the redirect URI as https://portal.azure.com.

    양식 작성을 완료한 후 등록을 선택합니다.After you're done filling out the form, 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 권한 선택 이미지

  5. 응용 프로그램 사용 권한을 선택합니다.Select Application permissions. 시나리오에 대한 관련 사용 권한(예: Incident.Read.All)을 선택한 다음 사용 권한 추가 를 선택합니다.Choose the relevant permissions for your scenario (for example, Incident.Read.All), 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.

  6. 관리자 동의 부여를 선택합니다.Select Grant admin consent. 권한을 추가할 때마다 권한을 적용하려면 관리자 동의 부여를 선택해야 합니다.Every time you add a permission, you must select Grant admin consent for it to take effect.

    권한 부여 이미지

  7. 응용 프로그램에 비밀을 추가하려면 인증서 & 를 선택하고 비밀에 설명을 추가한 다음 추가를 선택합니다.To add a secret to the application, select Certificates & secrets, add a description to the secret, then select Add.

    추가를 선택한 후 생성된 비밀 값 복사 를 선택합니다.After you select Add, select copy the generated secret value. 나가면 비밀 값을 검색할 수 없습니다.You won't be able to retrieve the secret value after you leave.

    앱 키 만들기 이미지

  8. 안전한 곳에 응용 프로그램 ID와 테넌트 ID를 기록합니다.Record your application ID and your tenant ID somewhere safe. 응용 프로그램 페이지 개요 아래에 나열됩니다.They're listed under Overview on your application page.

    생성된 앱 ID의 이미지

  9. 사용자의 테넌트에 응용 프로그램을 추가합니다.Add the application to your user's tenant.

    응용 프로그램은 사용자를 Microsoft 365 Defender와 상호 작용하기 때문에 응용 프로그램을 사용하려는 모든 테넌트에 대해 승인이 필요합니다.Since your application interacts with Microsoft 365 Defender on behalf of your users, it needs be approved for every tenant on which you intend to use it.

    사용자 테넌트의 전역 관리자는 동의 링크를 보고 응용 프로그램을 승인해야 합니다.A Global Administrator from your user's tenant needs to view the consent link and approve your application.

    동의 링크는 다음 형식입니다.Consent link is of the form:

    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 응용 프로그램 ID로 대체해야 합니다.The digits 00000000-0000-0000-0000-000000000000 should be replaced with your Application ID.

    동의 링크를 클릭한 후 사용자 테넌트의 전역 관리자에게 로그인하고 응용 프로그램에 동의합니다.After clicking on the consent link, sign in with the Global Administrator of the user's tenant and consent the application.

    동의 이미지

    또한 사용자에게 테넌트 ID를 요청해야 합니다.You'll also need to ask your user for their tenant ID. 테넌트 ID는 액세스 토큰을 획득하는 데 사용되는 식별자 중 하나입니다.The tenant ID is one of the identifiers used to acquire access tokens.

  • 완료!Done! 응용 프로그램을 성공적으로 등록했습니다.You've successfully registered an application!
  • 토큰 획득 및 유효성 검사에 대한 자세한 내용은 아래 예제를 참조하세요.See examples below for token acquisition and validation.

액세스 토큰을 얻게 됩니다.Get an access token

Azure AD 토큰에 대한 자세한 내용은 Azure AD 자습서를 참조하세요.For more information on Azure AD tokens, see the Azure AD tutorial.

중요

이 섹션의 예제에서는 테스트를 위해 비밀 값에 붙여 넣는 것이 까다로우지만 프로덕션에서 실행되는 응용 프로그램에 암호를 하드코드하면 안 됩니다. Although the examples in this section encourage you to paste in secret values for testing purposes, you should never hardcode secrets into an application running in production. 제3자에서 해당 비밀을 사용하여 리소스에 액세스할 수 있습니다.A third party could use your secret to access resources. Azure Key Vault를 사용하여 앱의 비밀을 안전하게 유지할 수 있습니다.You can help keep your app's secrets secure by using Azure Key Vault. 앱을 보호하는 방법에 대한 실제 예제는 Azure Key Vault를 사용하여 서버 앱의 암호 관리를 참조하세요.For a practical example of how you can protect your app, see Manage secrets in your server apps with Azure Key Vault.

다음 예제에서는 사용자의 테넌트 ID를 사용하여 스크립트가 작동하고 있는지 테스트합니다.In the following examples, use a user's tenant ID to test that the script is working.

PowerShell을 사용하여 액세스 토큰을 얻다Get an access token using PowerShell

# 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

C를 사용하여 액세스 토큰을 얻#Get an access token using C#

참고

다음 코드는 Nuget Microsoft.IdentityModel.Clients.ActiveDirectory 3.19.8을 사용하여 테스트되었습니다.The following code was tested with Nuget Microsoft.IdentityModel.Clients.ActiveDirectory 3.19.8.

  1. 새 콘솔 응용 프로그램을 만들 수 있습니다.Create a new console application.

  2. Microsoft.NuGet.Clients.ActiveDirectory를 설치합니다.Install NuGet Microsoft.IdentityModel.Clients.ActiveDirectory.

  3. 다음 줄을 추가합니다.Add the following line:

    using Microsoft.IdentityModel.Clients.ActiveDirectory;
    
  4. 다음 코드를 복사하여 앱에 붙여 넣습니다(3개의 변수를 업데이트하는 것을 잊지 마세요. tenantId clientId , appSecret ):Copy and paste the following code into your app (don't forget to update the three variables: tenantId, clientId, appSecret):

    string tenantId = ""; // Paste your directory (tenant) ID here
    string clientId = ""; // Paste your application (client) ID here
    string appSecret = ""; // Paste your own app secret here to test, then store it in a safe place, such as the Azure Key Vault!
    
    const string authority = "https://login.windows.net";
    const string wdatpResourceId = "https://api.security.microsoft.com";
    
    AuthenticationContext auth = new AuthenticationContext($"{authority}/{tenantId}/");
    ClientCredential clientCredential = new ClientCredential(clientId, appSecret);
    AuthenticationResult authenticationResult = auth.AcquireTokenAsync(wdatpResourceId, clientCredential).GetAwaiter().GetResult();
    string token = authenticationResult.AccessToken;
    

Python을 사용하여 액세스 토큰을 얻다Get an access token using Python

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.securitycenter.windows.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"]

컬을 사용하여 액세스 토큰을 얻다Get an access token using curl

참고

컬은 1803 이상의 Windows 10 버전에 미리 설치됩니다.Curl is pre-installed on Windows 10, versions 1803 and later. 다른 버전의 Windows 공식 컬 웹 사이트에서 직접 도구를 다운로드하여 설치합니다.For other versions of Windows, download and install the tool directly from the official curl website.

  1. 명령 프롬프트를 열고 azure CLIENT_ID ID로 설정하십시오.Open a command prompt, and set CLIENT_ID to your Azure application ID.
  2. Azure CLIENT_SECRET 비밀로 설정하세요.Set CLIENT_SECRET to your Azure application secret.
  3. TENANT_ID 사용하여 Defender에 액세스하려는 사용자의 Azure 테넌트 ID로 Microsoft 365.Set TENANT_ID to the Azure tenant ID of the user that wants to use your app to access Microsoft 365 Defender.
  4. 다음 명령을 실행합니다.Run the following command:
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

성공적인 응답은 다음과 같습니다.A successful response will look like this:

{"token_type":"Bearer","expires_in":3599,"ext_expires_in":0,"access_token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIn <truncated> aWReH7P0s0tjTBX8wGWqJUdDA"}

토큰 유효성 검사Validate the token

  1. 토큰을 복사하여 JSON 웹 토큰 유효성 검사 웹 사이트 JWT에 붙여넣어 디코드합니다.Copy and paste the token into the JSON web token validator website, 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();