Microsoft Defender XDR API에 대한 파트너 액세스 권한이 있는 앱 Create
적용 대상:
- Microsoft Defender XDR
중요
일부 정보는 상용으로 출시되기 전에 실질적으로 수정될 수 있는 사전 릴리스된 제품과 관련이 있습니다. Microsoft는 여기에서 제공하는 정보와 관련하여 명시적이거나 묵시적인 어떠한 보증도 제공하지 않습니다.
이 페이지에서는 여러 테넌트에서 사용자를 대신하여 Microsoft Defender XDR 프로그래밍 방식으로 액세스할 수 있는 Microsoft Entra 앱을 만드는 방법을 설명합니다. 다중 테넌트 앱은 대규모 사용자 그룹을 제공하는 데 유용합니다.
단일 사용자를 대신하여 Microsoft Defender XDR 프로그래밍 방식으로 액세스해야 하는 경우 사용자를 대신하여 Microsoft Defender XDR API에 액세스하려면 앱 Create 참조하세요. 사용자가 명시적으로 정의하지 않고 액세스해야 하는 경우(예: 백그라운드 앱 또는 디먼을 작성하는 경우) 사용자 없이 Microsoft Defender XDR 액세스하려면 앱 Create 참조하세요. 어떤 종류의 액세스가 필요한지 잘 모르는 경우 시작을 참조하세요.
Microsoft Defender XDR 프로그래밍 방식 API 집합을 통해 많은 데이터와 작업을 노출합니다. 이러한 API는 워크플로를 자동화하고 Microsoft Defender XDR 기능을 활용하는 데 도움이 됩니다. 이 API 액세스에는 OAuth2.0 인증이 필요합니다. 자세한 내용은 OAuth 2.0 권한 부여 코드 흐름을 참조하세요.
일반적으로 이러한 API를 사용하려면 다음 단계를 수행해야 합니다.
- Microsoft Entra 애플리케이션을 Create.
- 이 애플리케이션을 사용하여 액세스 토큰을 가져옵니다.
- 토큰을 사용하여 Microsoft Defender XDR API에 액세스합니다.
이 앱은 다중 테넌트이므로 사용자를 대신하여 각 테넌트의 관리자 동의 도 필요합니다.
이 문서에서는 다음 방법을 설명합니다.
- 다중 테넌트 Microsoft Entra 애플리케이션 Create
- 애플리케이션이 필요한 리소스의 Microsoft Defender XDR 액세스하기 위해 사용자 관리자로부터 승인된 동의를 받습니다.
- Microsoft Defender XDR 액세스 토큰 가져오기
- 토큰 유효성 검사
Microsoft Defender XDR 프로그래밍 방식 API 집합을 통해 많은 데이터와 작업을 노출합니다. 이러한 API는 Microsoft Defender XDR 기능을 기반으로 작업 흐름을 자동화하고 혁신하는 데 도움이 됩니다. API 액세스에는 OAuth2.0 인증이 필요합니다. 자세한 내용은 OAuth 2.0 권한 부여 코드 흐름을 참조하세요.
일반적으로 API를 사용하려면 다음 단계를 수행해야 합니다.
- 다중 테넌트 Microsoft Entra 애플리케이션을 Create.
- 애플리케이션이 필요한 Microsoft Defender XDR 리소스에 액세스할 수 있도록 사용자 관리자가 권한을 부여(동의)합니다.
- 이 애플리케이션을 사용하여 액세스 토큰을 가져옵니다.
- 토큰을 사용하여 Microsoft Defender XDR API에 액세스합니다.
다음 단계에서는 다중 테넌트 Microsoft Entra 애플리케이션을 만들고, Microsoft Defender XDR 액세스 토큰을 가져와서 토큰의 유효성을 검사하는 방법을 안내합니다.
다중 테넌트 앱 Create
전역 관리자 역할을 가진 사용자로 Azure에 로그인합니다.
Microsoft Entra ID>앱 등록>새 등록으로 이동합니다.
등록 양식에서 다음을 수행합니다.
- 애플리케이션의 이름을 선택합니다.
- 지원되는 계정 유형에서 모든 조직 디렉터리(모든 Microsoft Entra 디렉터리) - 다중 테넌트의 계정을 선택합니다.
- 리디렉션 URI 섹션을 작성합니다. 웹 유형을 선택하고 리디렉션 URI를 로 https://portal.azure.com지정합니다.
양식 작성이 완료되면 등록을 선택합니다.
애플리케이션 페이지에서 API 권한> 내organization 사용하는>권한> API 추가를 선택하고 Microsoft Threat Protection을 입력한 다음 Microsoft Threat Protection을 선택합니다. 이제 앱이 Microsoft Defender XDR 액세스할 수 있습니다.
팁
Microsoft Threat Protection은 Microsoft Defender XDR 이전 이름이며 원래 목록에 표시되지 않습니다. 표시되는 것을 보려면 텍스트 상자에 이름을 쓰기 시작해야 합니다.
애플리케이션 권한을 선택합니다. 시나리오에 대한 관련 권한(예: Incident.Read.All)을 선택한 다음 , 권한 추가를 선택합니다.
참고
시나리오에 대한 관련 권한을 선택해야 합니다. 모든 인시던트를 읽는 것은 단지 예제일 뿐입니다. 필요한 권한을 확인하려면 호출하려는 API의 권한 섹션을 참조하세요.
instance 고급 쿼리를 실행하려면 '고급 쿼리 실행' 권한을 선택하고 디바이스를 격리하려면 '컴퓨터 격리' 권한을 선택합니다.
관리자 동의 부여를 선택합니다. 권한을 추가할 때마다 적용하려면 관리자 동의 부여 를 선택해야 합니다.
애플리케이션에 비밀을 추가하려면 인증서 & 비밀을 선택하고 비밀에 설명을 추가한 다음 추가를 선택합니다.
팁
추가를 선택한 후 생성된 비밀 값 복사를 선택합니다. 떠난 후에는 비밀 값을 검색할 수 없습니다.
안전한 곳에 애플리케이션 ID와 테넌트 ID를 기록합니다. 애플리케이션 페이지의 개요 아래에 나열됩니다.
사용자의 테넌트에서 애플리케이션을 추가합니다.
애플리케이션은 사용자를 대신하여 Microsoft Defender XDR 상호 작용하므로 사용하려는 모든 테넌트에서 승인되어야 합니다.
사용자 테넌트의 전역 관리자는 동의 링크를 보고 애플리케이션을 승인해야 합니다.
동의 링크는 다음과 같은 형식입니다.
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 자습서를 참조하세요.
중요
이 섹션의 예제에서는 테스트 목적으로 비밀 값을 붙여넣는 것이 권장되지만 프로덕션에서 실행되는 애플리케이션에 비밀을 하드 코딩해서는 안 됩니다. 타사에서 비밀을 사용하여 리소스에 액세스할 수 있습니다. 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 인증 라이브러리)은 더 이상 사용되지 않습니다. 2020년 6월 30일 이후 새로운 기능이 추가되지 않았습니다. 업그레이드하는 것이 좋습니다. 자세한 내용은 마이그레이션 가이드 를 참조하세요.
새 콘솔 애플리케이션을 Create.
다음 줄을 추가합니다.
using Microsoft.Identity.Client;
다음 코드를 복사하여 앱에 붙여넣습니다(, , )
clientId
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을 사용하여 액세스 토큰 가져오기
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 Defender XDR 액세스하려는 사용자의 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.ReadWrite.All
및 AdvancedHunting.Read.All
권한을 사용하여 앱Incidents.Read.All
에서 획득한 디코딩된 토큰을 볼 수 있습니다.
토큰을 사용하여 Microsoft Defender XDR API에 액세스
- 사용하려는 API(인시던트 또는 고급 헌팅)를 선택합니다. 자세한 내용은 지원되는 Microsoft Defender XDR 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();
관련 문서
- Microsoft Defender XDR API 개요
- Microsoft Defender XDR API 액세스
- 'Hello 월드' 애플리케이션 Create
- 사용자가 없는 Microsoft Defender XDR 액세스하도록 앱 Create
- 사용자를 대신하여 Microsoft Defender XDR API에 액세스하도록 앱 Create
- API 제한 및 라이선스에 대해 알아보기
- 오류 코드 이해
- Azure Key Vault 사용하여 서버 앱에서 비밀 관리
- 사용자 로그인 및 API 액세스를 위한 OAuth 2.0 권한 부여
팁
더 자세히 알아보고 싶으신가요? 기술 커뮤니티: Microsoft Defender XDR Tech Community의 Microsoft 보안 커뮤니티와 Engage.