Microsoft 365 Defender API에 대한 파트너 액세스 권한이 있는 앱 만들기

아티클
06/15/2022
읽는 데 8분 걸림

참고

Microsoft 365 Defender를 경험해 보고 싶으신가요? Microsoft 365 Defender 평가하고 파일럿하는 방법에 대해 자세히 알아보세요.

적용 대상:

Microsoft 365 Defender

중요

일부 정보는 상용으로 출시되기 전에 실질적으로 수정될 수 있는 사전 릴리스된 제품과 관련이 있습니다. Microsoft는 여기에서 제공하는 정보와 관련하여 명시적이거나 묵시적인 어떠한 보증도 제공하지 않습니다.

이 페이지에서는 여러 테넌트에서 사용자를 대신하여 Microsoft 365 Defender 프로그래밍 방식으로 액세스할 수 있는 Azure Active Directory 앱을 만드는 방법을 설명합니다. 다중 테넌트 앱은 대규모 사용자 그룹을 제공하는 데 유용합니다.

단일 사용자를 대신하여 Microsoft 365 Defender 프로그래밍 방식으로 액세스해야 하는 경우 사용자를 대신하여 Microsoft 365 Defender API에 액세스할 수 있는 앱 만들기를 참조하세요. 명시적으로 정의된 사용자 없이 액세스해야 하는 경우(예: 백그라운드 앱 또는 디먼을 작성하는 경우) 사용자 없이 Microsoft 365 Defender 액세스할 수 있는 앱 만들기를 참조하세요. 어떤 종류의 액세스가 필요한지 잘 모르는 경우 시작 참조하세요.

Microsoft 365 Defender 일련의 프로그래밍 API를 통해 많은 데이터와 작업을 노출합니다. 이러한 API는 워크플로를 자동화하고 Microsoft 365 Defender 기능을 활용하는 데 도움이 됩니다. 이 API 액세스에는 OAuth2.0 인증이 필요합니다. 자세한 내용은 OAuth 2.0 권한 부여 코드 Flow 참조하세요.

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

Azure Active Directory(Azure AD) 애플리케이션을 만듭니다.
이 애플리케이션을 사용하여 액세스 토큰을 가져옵니다.
토큰을 사용하여 Microsoft 365 Defender API에 액세스합니다.

이 앱은 다중 테넌트이므로 사용자를 대신하여 각 테넌트의 관리자 동의 도 필요합니다.

이 문서에서는 다음 방법을 설명합니다.

다중 테넌트 Azure AD 애플리케이션 만들기
애플리케이션이 필요한 리소스의 Microsoft 365 Defender 액세스하기 위해 사용자 관리자로부터 승인된 동의를 받습니다.
Microsoft 365 Defender 액세스 토큰 가져오기
토큰 유효성 검사

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

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

다중 테넌트 Azure AD 애플리케이션을 만듭니다.
애플리케이션이 필요한 Microsoft 365 Defender 리소스에 액세스할 수 있도록 사용자 관리자의 권한(동의)을 받습니다.
이 애플리케이션을 사용하여 액세스 토큰을 가져옵니다.
토큰을 사용하여 Microsoft 365 Defender API에 액세스합니다.

다음 단계에서는 다중 테넌트 Azure AD 애플리케이션을 만들고, Microsoft 365 Defender 액세스 토큰을 가져오고, 토큰의 유효성을 검사하는 방법을 안내합니다.

다중 테넌트 앱 만들기

전역 관리자 역할을 가진 사용자로 Azure에 로그인합니다.
Azure Active Directory > 앱 등록 > 새 등록 으로 이동합니다.
등록 양식에서 다음을 수행합니다.
- 애플리케이션의 이름을 선택합니다.
- 지원되는 계정 유형****에서 모든 조직 디렉터리(모든 Azure AD 디렉터리) - 다중 테넌트의 계정을 선택합니다.
- 리디렉션 URI 섹션을 작성합니다. 웹 유형을 선택하고 리디렉션 URI를 로 https://portal.azure.com 지정합니다.
양식 작성이 완료되면 [등록]을 선택합니다.
애플리케이션 페이지에서 조직에서 > 사용하는 API 사용 > 권한 추가 API > 를 선택하고 Microsoft Threat Protection 을 입력하고 Microsoft Threat Protection 을 선택합니다. 이제 앱에서 Microsoft 365 Defender 액세스할 수 있습니다.

팁

Microsoft Threat Protection 은 Microsoft 365 Defender 이전 이름이며 원래 목록에 표시되지 않습니다. 표시되는 것을 보려면 텍스트 상자에 이름을 쓰기 시작해야 합니다.
애플리케이션 권한 을 선택합니다. 시나리오에 대한 관련 권한(예: Incident.Read.All)을 선택한 다음 , 권한 추가를 선택합니다.

참고

시나리오에 대한 관련 권한을 선택해야 합니다. 모든 인시던트를 읽는 것은 단지 예제일 뿐입니다. 필요한 권한을 확인하려면 호출하려는 API의 사용 권한 섹션을 참조하세요.

예를 들어 고급 쿼리를 실행하려면 '고급 쿼리 실행' 권한을 선택합니다. 디바이스를 격리하려면 '컴퓨터 격리' 권한을 선택합니다.
관리자 동의 부여를 선택합니다. 권한을 추가할 때마다 권한을 적용하려면 관리자 동의 부여 를 선택해야 합니다.
애플리케이션에 비밀을 추가하려면 인증서 & 비밀을 선택하고 비밀에 설명을 추가한 다음 추가 를 선택합니다.

팁

추가 를 선택한 후 생성된 비밀 값 복사를 선택합니다. 떠난 후에는 비밀 값을 검색할 수 없습니다.
안전한 곳에 애플리케이션 ID와 테넌트 ID를 기록합니다. 애플리케이션 페이지의 개요 아래에 나열됩니다.
사용자의 테넌트에 애플리케이션을 추가합니다.

애플리케이션은 사용자를 대신하여 Microsoft 365 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는 액세스 토큰을 획득하는 데 사용되는 식별자 중 하나입니다.

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

액세스 토큰 가져오기

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

중요

이 섹션의 예제에서는 테스트 목적으로 비밀 값을 붙여 넣도록 권장하지만 프로덕션에서 실행되는 애플리케이션에 비밀을 하드 코드해서는 안 됩니다. 타사에서 사용자의 비밀을 사용하여 리소스에 액세스할 수 있습니다. Azure Key Vault 사용하여 앱의 비밀을 안전하게 유지할 수 있습니다. 앱을 보호하는 방법에 대한 실용적인 예제는 Azure Key Vault 사용하여 서버 앱에서 비밀 관리를 참조하세요.

팁

다음 예제에서는 사용자의 테넌트 ID를 사용하여 스크립트가 작동하는지 테스트합니다.

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를 사용하여 액세스 토큰 가져오기#

참고

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

중요

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

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

다음 코드를 복사하여 앱에 붙여넣습니다(세 가지 변수를 업데이트하는 것을 잊지 마세요.tenantId, clientId``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을 사용하여 액세스 토큰 가져오기

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.security.microsoft.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"]

curl을 사용하여 액세스 토큰 가져오기

참고

Curl은 Windows 10 버전 1803 이상에 미리 설치되어 있습니다. 다른 버전의 Windows 경우 공식 curl 웹 사이트에서 직접 도구를 다운로드하고 설치합니다.

명령 프롬프트를 열고 CLIENT_ID Azure 애플리케이션 ID로 설정합니다.
CLIENT_SECRET Azure 애플리케이션 비밀로 설정합니다.
TENANT_ID 앱을 사용하여 Microsoft 365 Defender 액세스하려는 사용자의 Azure 테넌트 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"}

토큰 유효성 검사

토큰을 복사하여 JSON 웹 토큰 유효성 검사기 웹 사이트 JWT 에 붙여넣어 디코딩합니다.
디코딩된 토큰 내의 역할 클레임에 원하는 권한이 포함되어 있는지 확인합니다.

다음 이미지에서는 앱에서 획득한 디코딩된 토큰과 권한, 그리고 Incidents.Read.All``````Incidents.ReadWrite.All``````AdvancedHunting.Read.All 사용 권한을 확인할 수 있습니다.

토큰을 사용하여 Microsoft 365 Defender API에 액세스

사용하려는 API(인시던트 또는 고급 헌팅)를 선택합니다. 자세한 내용은 지원되는 Microsoft 365 Defender API를 참조하세요.
보내려는 http 요청에서 권한 부여 헤더 "Bearer" <token>를 로 설정하고, 전달자는 권한 부여 체계이고, 토큰 은 유효성이 검사된 토큰으로 설정합니다.
토큰은 1시간 이내에 만료됩니다. 이 시간 동안 동일한 토큰을 사용하여 둘 이상의 요청을 보낼 수 있습니다.

다음 예제에서는 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();