엔드포인트용 Microsoft Defender API를 통한 파트너 액세스

아티클
06/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

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

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

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

다중 테넌트 Microsoft Entra 애플리케이션을 만듭니다.
필요한 엔드포인트용 Defender 리소스에 액세스하기 위해 애플리케이션에 대한 고객 관리자의 권한 부여(동의)를 받습니다.
이 애플리케이션을 사용하여 액세스 토큰을 가져옵니다.
토큰을 사용하여 엔드포인트용 Microsoft Defender API에 액세스합니다.

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

중요

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

다중 테넌트 앱 만들기

전역 관리자 역할이 있는 사용자를 사용하여 Azure 테넌트에서 로그인합니다.
Microsoft Entra ID>앱 등록 새 등록으로> 이동합니다.
등록 양식에서 다음을 수행합니다.
- 애플리케이션의 이름을 선택합니다.
- 지원되는 계정 유형 - 모든 조직 디렉터리의 계정입니다.
- 리디렉션 URI - 형식: 웹, URI: https://portal.azure.com
애플리케이션이 엔드포인트용 Microsoft Defender에 액세스하고 통합을 완료하는 데 필요한 최소한의 권한 집합으로 할당하도록 허용합니다.
- 애플리케이션 페이지에서 조직에서 사용하는 >API 권한추가 권한>>API를 선택하고 WindowsDefenderATP를 선택하고 WindowsDefenderATP를 선택합니다.
- WindowsDefenderATP 는 원래 목록에 표시되지 않습니다. 텍스트 상자에 이름을 작성하여 표시되는지 확인합니다.

API 권한 요청

필요한 권한을 확인하려면 호출하려는 API의 권한 섹션을 검토합니다. 예:

고급 쿼리를 실행하려면 고급 쿼리 실행 권한을 선택합니다.
디바이스를 격리하려면 컴퓨터 격리 권한을 선택합니다.

다음 예제에서는 모든 경고 읽기 권한을 사용합니다.

애플리케이션 사용 권한>경고.읽기를 선택합니다. 권한추가에서 모두 > 선택
동의 부여를 선택합니다.
- 권한을 추가할 때마다 새 사용 권한을 적용하려면 동의 부여 를 선택해야 합니다.
애플리케이션에 비밀을 추가합니다.
- 비밀에 & 인증서를 선택하고, 비밀에 설명을 추가하고, 추가를 선택합니다.
추가를 선택한 후 생성된 비밀 값을 복사해야 합니다. 떠난 후에는 검색할 수 없습니다!
애플리케이션 ID를 적어 씁니다.
- 애플리케이션 페이지에서 개요 로 이동하여 다음 정보를 복사합니다.
고객의 테넌트에서 애플리케이션을 추가합니다.

애플리케이션을 사용하려는 각 고객 테넌트에서 애플리케이션을 승인해야 합니다. 이 승인은 애플리케이션이 고객을 대신하여 엔드포인트용 Microsoft Defender 애플리케이션과 상호 작용하기 때문에 필요합니다.

고객 테넌트의 전역 관리자 가 있는 사용자는 동의 링크를 선택하고 애플리케이션을 승인해야 합니다.

동의 링크는 다음과 같은 형식입니다.
```
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로 바꿔야 합니다.

동의 링크를 선택한 후 고객 테넌트의 전역 관리자로 로그인하고 애플리케이션에 동의합니다.

또한 고객에게 테넌트 ID를 요청하고 토큰을 획득할 때 나중에 사용할 수 있도록 저장해야 합니다.
완료되었습니다! 애플리케이션을 성공적으로 등록했습니다. 토큰 획득 및 유효성 검사는 다음 예제를 참조하세요.

액세스 토큰 가져오기 예제

고객을 대신하여 액세스 토큰을 가져오려면 다음 토큰 획득에서 고객의 테넌트 ID를 사용합니다.

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

PowerShell 사용

# That code gets the App Context Token and save it to a file named "Latest-token.txt" under the current directory
# Paste below your Tenant ID, App ID and App Secret (App key).

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

$resourceAppIdUri = 'https://api.securitycenter.microsoft.com'
$oAuthUri = "https://login.microsoftonline.com/$TenantId/oauth2/token"
$authBody = [Ordered] @{
    resource = "$resourceAppIdUri"
    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
Out-File -FilePath "./Latest-token.txt" -InputObject $token
return $token

C 사용#

중요

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

새 콘솔 애플리케이션을 만듭니다.
NuGet Microsoft.Identity.Client를 설치합니다.
코드를 사용하여 다음을 추가합니다.
```
 using Microsoft.Identity.Client;
```
이 코드는 NuGet Microsoft.Identity.Client을 사용하여 테스트되었습니다.

애플리케이션에서 다음 코드를 복사/붙여넣습니다(, , appId및 appSecret)의 세 가지 변수를 tenantId업데이트하는 것을 잊지 마세요.

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 .
애플리케이션을 사용하여 엔드포인트용 Microsoft 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에 대한 여러 권한이 있는 애플리케이션에서 획득한 디코딩된 토큰을 볼 수 있습니다.

"tid" 클레임은 토큰이 속한 테넌트 ID입니다.

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

사용할 API를 선택합니다. 자세한 내용은 지원되는 엔드포인트용 Microsoft Defender API를 참조하세요.

보내는 Http 요청에서 권한 부여 헤더를 Bearer {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 보안 커뮤니티에 참여하세요.

다음을 통해 공유