엔드포인트용 Microsoft Defender API 사용

아티클
06/25/2024

적용 대상:

중요

고급 헌팅 기능은 비즈니스용 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
ina.api.security.microsoft.com

이 페이지에서는 사용자를 대신하여 엔드포인트용 Defender에 프로그래밍 방식으로 액세스하는 애플리케이션을 만드는 방법을 설명합니다.

사용자 없이 프로그래밍 방식으로 엔드포인트용 Microsoft Defender에 액세스해야 하는 경우 애플리케이션 컨텍스트를 사용하여 엔드포인트용 Microsoft Defender 액세스를 참조하세요.

필요한 액세스 권한을 잘 모르는 경우 소개 페이지를 읽어보세요.

엔드포인트용 Microsoft Defender는 프로그래밍 방식 API 집합을 통해 많은 데이터와 작업을 노출합니다. 이러한 API를 사용하면 엔드포인트용 Microsoft Defender 기능을 기반으로 작업 흐름을 자동화하고 혁신할 수 있습니다. API 액세스에는 OAuth2.0 인증이 필요합니다. 자세한 내용은 OAuth 2.0 권한 부여 코드 흐름을 참조하세요.

일반적으로 API를 사용하려면 다음 단계를 수행해야 합니다.

Microsoft Entra 애플리케이션 만들기
이 애플리케이션을 사용하여 액세스 토큰 가져오기
토큰을 사용하여 엔드포인트용 Defender API에 액세스

이 페이지에서는 Microsoft Entra 애플리케이션을 만들고, 엔드포인트용 Microsoft Defender에 대한 액세스 토큰을 가져오고, 토큰의 유효성을 검사하는 방법을 설명합니다.

참고

사용자를 대신하여 엔드포인트용 Microsoft Defender API에 액세스하는 경우 올바른 애플리케이션 권한 및 사용자 권한이 필요합니다. 엔드포인트용 Microsoft Defender에 대한 사용자 권한에 익숙하지 않은 경우 역할 기반 액세스 제어를 사용하여 포털 액세스 관리를 참조하세요.

팁

포털에서 작업을 수행할 수 있는 권한이 있는 경우 API에서 작업을 수행할 수 있는 권한이 있습니다.

앱 만들기

Azure 포털에 로그인합니다.
Microsoft Entra ID>앱 등록 새 등록으로> 이동합니다.

애플리케이션 등록 페이지가 나타나면 애플리케이션의 등록 정보를 입력합니다.

이름 - 앱 사용자에게 표시되는 의미 있는 애플리케이션 이름을 입력합니다.

지원되는 계정 유형 - 애플리케이션에서 지원할 계정을 선택합니다.

지원 계정 유형	설명
이 조직 디렉터리의 계정만	LOB(기간 업무) 애플리케이션을 빌드하는 경우 이 옵션을 선택합니다. 디렉터리에 애플리케이션을 등록하지 않는 경우 이 옵션을 사용할 수 없습니다. 이 옵션은 Microsoft Entra 전용 단일 테넌트로 매핑됩니다. 이 옵션은 디렉터리 외부에서 앱을 등록하지 않는 한 기본 옵션입니다. 앱이 디렉터리 외부에 등록된 경우 기본값은 Microsoft Entra 다중 테넌트 및 개인 Microsoft 계정입니다.
모든 조직 디렉터리의 계정	모든 비즈니스 및 교육 고객을 대상으로 하려면 이 옵션을 선택합니다. 이 옵션은 Microsoft Entra 전용 다중 테넌트에 매핑됩니다. 앱을 Microsoft Entra 전용 단일 테넌트로 등록한 경우 인증 블레이드를 통해 앱을 Microsoft Entra 다중 테넌트로 업데이트하고 다시 단일 테넌트로 업데이트할 수 있습니다.
모든 조직 디렉터리 및 개인 Microsoft 계정의 계정	가장 광범위한 고객 집합을 대상으로 하려면 이 옵션을 선택합니다. 이 옵션은 Microsoft Entra 다중 테넌트 및 개인 Microsoft 계정에 매핑됩니다. 앱을 Microsoft Entra 다중 테넌트 및 개인 Microsoft 계정으로 등록한 경우 UI에서 변경할 수 없습니다. 대신 애플리케이션 매니페스트 편집기를 사용하여 지원되는 계정 유형을 변경해야 합니다.

리디렉션 URI(선택 사항) - 빌드 중인 앱 유형, 웹 또는 퍼블릭 클라이언트(모바일 & 데스크톱)를 선택한 다음 애플리케이션에 대한 리디렉션 URI(또는 회신 URL)를 입력합니다.
- 웹 애플리케이션의 경우 앱의 기본 URL을 제공합니다. 예를 들어 http://localhost:31544 은 로컬 컴퓨터에서 실행되는 웹앱의 URL일 수 있습니다. 사용자는 이 URL을 사용하여 웹 클라이언트 애플리케이션에 로그인합니다.
- 공용 클라이언트 애플리케이션의 경우 토큰 응답을 반환하기 위해 Microsoft Entra ID에서 사용하는 URI를 제공합니다. 애플리케이션과 관련된 값(예: myapp://auth)을 입력합니다.
웹 애플리케이션 또는 네이티브 애플리케이션에 대한 특정 예제를 보려면 빠른 시작을 확인하세요.

완료되면 등록을 선택합니다.

애플리케이션이 엔드포인트용 Microsoft Defender에 액세스하고 '경고 읽기' 권한을 할당하도록 허용합니다.
- 애플리케이션 페이지에서 조직에서 사용하는 >API 권한추가 권한>>API를 선택하고 WindowsDefenderATP를 선택하고 WindowsDefenderATP를 선택합니다.
  
  참고
  
  WindowsDefenderATP 는 원래 목록에 표시되지 않습니다. 텍스트 상자에 이름을 작성하여 표시되는지 확인합니다.
- 위임된 권한>경고를 선택합니다. 읽기> 권한 추가를 선택합니다.
중요

관련 권한을 선택합니다. 읽기 경고는 예제일 뿐입니다.

예:
- 고급 쿼리를 실행하려면 고급 쿼리 실행 권한을 선택합니다.
- 디바이스를 격리하려면 컴퓨터 권한 격리를 선택합니다.
- 필요한 권한을 확인하려면 호출하려는 API의 사용 권한 섹션을 확인합니다.
- 동의 부여를 선택합니다.
  
  참고
  
  권한을 추가할 때마다 새 사용 권한을 적용하려면 동의 부여 를 선택해야 합니다.
애플리케이션 ID 및 테넌트 ID를 적어 씁니다.

애플리케이션 페이지에서 개요 로 이동하여 다음 정보를 복사합니다.

액세스 토큰 가져오기

Microsoft Entra 토큰에 대한 자세한 내용은 Microsoft Entra 자습서를 참조하세요.

C 사용#

애플리케이션에서 아래 클래스를 복사/붙여넣습니다.

토큰을 획득하려면 Application ID, 테넌트 ID, 사용자 이름 및 암호와 함께 AcquireUserTokenAsync 메서드를 사용합니다.

namespace WindowsDefenderATP
{
    using System.Net.Http;
    using System.Text;
    using System.Threading.Tasks;
    using Newtonsoft.Json.Linq;

    public static class WindowsDefenderATPUtils
    {
        private const string Authority = "https://login.microsoftonline.com";

        private const string WdatpResourceId = "https://api.securitycenter.microsoft.com";

        public static async Task<string> AcquireUserTokenAsync(string username, string password, string appId, string tenantId)
        {
            using (var httpClient = new HttpClient())
            {
                var urlEncodedBody = $"resource={WdatpResourceId}&client_id={appId}&grant_type=password&username={username}&password={password}";

                var stringContent = new StringContent(urlEncodedBody, Encoding.UTF8, "application/x-www-form-urlencoded");

                using (var response = await httpClient.PostAsync($"{Authority}/{tenantId}/oauth2/token", stringContent).ConfigureAwait(false))
                {
                    response.EnsureSuccessStatusCode();

                    var json = await response.Content.ReadAsStringAsync().ConfigureAwait(false);

                    var jObject = JObject.Parse(json);

                    return jObject["access_token"].Value<string>();
                }
            }
        }
    }
}

토큰 유효성 검사

올바른 토큰이 있는지 확인합니다.

디코딩하기 위해 이전 단계에서 얻은 토큰을 JWT 에 복사/붙여넣습니다.
원하는 앱 권한이 있는 'scp' 클레임을 가져오는지 확인합니다.
아래 스크린샷에서는 자습서에서 앱에서 획득한 디코딩된 토큰을 볼 수 있습니다.

토큰을 사용하여 엔드포인트용 Microsoft Defender API에 액세스

사용하려는 API - 엔드포인트용 Microsoft Defender API를 선택합니다.
보내는 HTTP 요청에서 권한 부여 헤더를 "전달자 {token}"(전달자는 권한 부여 체계임)으로 설정합니다.
토큰의 만료 시간은 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

참고 항목

팁

더 자세히 알아보고 싶으신가요? Microsoft 기술 커뮤니티: 엔드포인트용 Microsoft Defender 기술 커뮤니티에서 Microsoft 보안 커뮤니티에 참여하세요.

다음을 통해 공유