사용자 없이 엔드포인트용 Microsoft Defender 액세스하는 앱 만들기

아티클
08/29/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에 프로그래밍 방식으로 액세스하는 애플리케이션을 만드는 방법을 설명합니다. 사용자를 대신하여 엔드포인트용 Defender에 프로그래밍 방식으로 액세스해야 하는 경우 사용자 컨텍스트로 액세스 가져오기를 참조하세요. 필요한 액세스 권한을 잘 모르는 경우 시작을 참조하세요.

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

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

Microsoft Entra 애플리케이션을 만듭니다.
이 애플리케이션을 사용하여 액세스 토큰을 가져옵니다.
토큰을 사용하여 엔드포인트용 Defender API에 액세스합니다.

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

중요

사용 권한이 가장 적은 역할을 사용하는 것이 좋습니다. 이렇게 하면 조직의 보안을 개선하는 데 도움이 됩니다. 전역 관리자는 기존 역할을 사용할 수 없는 경우 긴급 시나리오로 제한해야 하는 매우 권한이 높은 역할입니다.

앱 만들기

Azure 포털에 로그인합니다.
Microsoft Entra ID>앱 등록>새 등록으로 이동합니다.
등록 양식에서 애플리케이션의 이름을 선택한 다음 등록을 선택합니다.
앱이 엔드포인트용 Defender에 액세스하고 '모든 경고 읽기' 권한을 할당할 수 있도록 하려면 애플리케이션 페이지에서 API 권한>내 organization 사용하는>권한> API 추가를 선택하고 WindowsDefenderATP를 입력한 다음 WindowsDefenderATP를 선택합니다.

참고

WindowsDefenderATP 는 원래 목록에 표시되지 않습니다. 텍스트 상자에 이름을 작성하여 표시되는지 확인합니다.

애플리케이션 권한>Alert.Read.All을 선택한 다음, 권한 추가를 선택합니다.
적절한 권한을 선택합니다. Read All Alerts 은 예제일 뿐입니다. 다음은 몇 가지 예입니다.
- 고급 쿼리를 실행하려면 권한을 선택합니다Run advanced queries.
- 디바이스를 격리하려면 권한을 선택합니다Isolate machine.
- 필요한 권한을 확인하려면 호출하려는 API의 사용 권한 섹션을 참조하세요.
동의 부여를 선택합니다.

참고

사용 권한을 추가할 때마다 새 사용 권한을 적용하려면 동의 부여 를 선택해야 합니다.
애플리케이션에 비밀을 추가하려면 인증서 & 비밀을 선택하고 비밀에 설명을 추가한 다음 추가를 선택합니다.

참고

추가를 선택한 후 생성된 비밀 값 복사를 선택합니다. 나가면 이 값을 검색할 수 없습니다.
애플리케이션 ID 및 테넌트 ID를 적어 씁니다. 애플리케이션 페이지에서 개요 로 이동하여 다음을 복사합니다.
엔드포인트용 Microsoft Defender 파트너에만 해당합니다. 앱을 다중 테넌트(동의 후 모든 테넌트에서 사용 가능)로 설정합니다. 이는 타사 앱에 필요합니다 (예: 여러 고객의 테넌트에서 실행하려는 앱을 만드는 경우). 테넌트에서만 실행하려는 서비스를 만드는 경우에는 필요하지 않습니다 (예: 사용자 고유의 데이터와만 상호 작용하는 고유한 용도로 애플리케이션을 만드는 경우). 앱을 다중 테넌트로 설정하려면 다음 단계를 수행합니다.
1. 인증으로 이동하여 리디렉션 URI로 추가 https://portal.azure.com 합니다.
2. 페이지 아래쪽의 지원되는 계정 유형에서 다중 테넌트 앱 에 대한 모든 조직 디렉터리 애플리케이션 동의의 계정을 선택합니다.
  
  애플리케이션을 사용하려는 각 테넌트에서 승인해야 합니다. 애플리케이션이 고객을 대신하여 엔드포인트용 Defender와 상호 작용하기 때문입니다.
  
  사용자(또는 타사 앱을 작성하는 경우 고객)는 동의 링크를 선택하고 앱을 승인해야 합니다. 동의는 Active Directory에서 관리 권한이 있는 사용자와 함께 수행해야 합니다.
  
  동의 링크는 다음과 같이 구성됩니다.
```
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로 바뀝니다.

완료되었습니다! 애플리케이션을 성공적으로 등록했습니다! 토큰 획득 및 유효성 검사는 아래 예제를 참조하세요.

액세스 토큰 가져오기

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

PowerShell 사용

# This script acquires the App Context Token and stores it in the variable $token for later use in the script.
# Paste your Tenant ID, App ID, and App Secret (App key) into the indicated quotes below.

$tenantId = '' ### Paste your tenant ID here
$appId = '' ### Paste your Application ID here
$appSecret = '' ### Paste your Application key here

$sourceAppIdUri = 'https://api.securitycenter.microsoft.com/.default'
$oAuthUri = "https://login.microsoftonline.com/$TenantId/oauth2/v2.0/token"
$authBody = [Ordered] @{
    scope = "$sourceAppIdUri"
    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
$token

C#을 사용합니다.

다음 코드는 NuGet Microsoft.Identity.Client 3.19.8에서 테스트되었습니다.

중요

Microsoft.IdentityModel.Clients.ActiveDirectory NuGet 패키지 및 ADAL(Azure AD 인증 라이브러리)은 더 이상 사용되지 않습니다. 2020년 6월 30일 이후 새로운 기능이 추가되지 않았습니다. 업그레이드하는 것이 좋습니다. 자세한 내용은 마이그레이션 가이드 를 참조하세요.

새 콘솔 애플리케이션을 만듭니다.
NuGet Microsoft.Identity.Client를 설치합니다.
다음을 추가합니다.
```
using Microsoft.Identity.Client;
```

다음 코드를 복사하여 앱에 붙여넣습니다(세 가지 변수를 업데이트하는 것을 잊지 마세요. tenantId, appId, appSecret)

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 사용

참고

다음 절차에서는 Windows용 Curl이 컴퓨터에 이미 설치되어 있다고 가정합니다.

명령 프롬프트를 열고 Azure 애플리케이션 ID로 설정합니다 CLIENT_ID .
Azure 애플리케이션 비밀로 설정합니다 CLIENT_SECRET .
앱을 사용하여 엔드포인트용 Defender에 액세스하려는 고객의 Azure 테넌트 ID로 설정합니다 TENANT_ID .

다음 명령을 실행합니다.

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"}

토큰 유효성 검사

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

이전 단계에서 얻은 토큰을 복사하여 JWT 에 붙여넣어 디코딩합니다.
원하는 권한으로 역할 클레임을 가져오는지 확인합니다.

다음 이미지에서는 모든 엔드포인트용 Microsoft Defender 역할에 대한 권한이 있는 앱에서 획득한 디코딩된 토큰을 볼 수 있습니다.

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

사용할 API를 선택합니다. 자세한 내용은 엔드포인트용 지원되는 Defender API를 참조하세요.
보내는 요청에서 권한 부여 헤더를 httpBearer {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 Defender Tech Community의 Microsoft 보안 커뮤니티와 Engage.

다음을 통해 공유