Membuat aplikasi untuk mengakses Microsoft Defender XDR tanpa pengguna

  • Berlaku untuk: Microsoft Defender XDR

Penting

Beberapa informasi berkaitan dengan produk yang telah dilepas sebelumnya yang mungkin dimodifikasi secara substansial sebelum ketersediaan umumnya. Microsoft tidak memberikan jaminan, tersurat maupun tersirat, sehubungan dengan informasi yang diberikan di sini.

Buat aplikasi untuk mendapatkan akses terprogram ke Microsoft Defender tanpa pengguna yang ditentukan—misalnya, jika Anda membuat daemon atau layanan latar belakang.

Jika Anda memerlukan akses terprogram ke Microsoft Defender atas nama satu atau beberapa pengguna, lihat Membuat aplikasi untuk mengakses API Microsoft Defender atas nama pengguna dan Membuat aplikasi dengan akses mitra ke API Microsoft Defender. Jika Anda tidak yakin jenis akses mana yang Anda butuhkan, lihat Memulai.

Microsoft Defender mengekspos sebagian besar data dan tindakannya melalui serangkaian API terprogram. API tersebut membantu Anda mengotomatiskan alur kerja dan memanfaatkan kemampuan Microsoft Defender. Akses API ini memerlukan autentikasi OAuth2.0. Untuk informasi selengkapnya, lihat Alur Kode Otorisasi OAuth 2.0.

Secara umum, Anda perlu mengambil langkah-langkah berikut untuk menggunakan API ini:

  • Buat aplikasi Microsoft Entra.
  • Dapatkan token akses menggunakan aplikasi ini.
  • Gunakan token untuk mengakses API Microsoft Defender.

Artikel ini menjelaskan cara:

  • Membuat aplikasi Microsoft Entra
  • Mendapatkan token akses ke Microsoft Defender
  • Validasi token.

Buat aplikasi

  1. Masuk ke Azure.

  2. Navigate ke Microsoft Entra ID>Pendaftaran aplikasi>Pendaftaran baru.

    Tab Pendaftaran baru di portal Microsoft Defender

  3. Dalam formulir, pilih nama untuk aplikasi Anda, lalu pilih Daftar.

  4. Pada halaman aplikasi Anda, pilih IZIN> APITambahkan API izin>yang digunakan> organisasi saya, ketik Microsoft Perlindungan Ancaman, dan pilih Microsoft Perlindungan Ancaman. Aplikasi Anda sekarang dapat mengakses Microsoft Defender XDR.

    Aplikasi Anda sekarang dapat mengakses Microsoft Defender.

    Tip

    Microsoft Threat Protection adalah nama sebelumnya untuk Microsoft Defender XDR, dan tidak muncul dalam daftar asli. Anda perlu mulai menulis namanya di kotak teks untuk melihatnya muncul.

    Tab penggunaan API organisasi di portal Microsoft Defender

  5. Pilih Izin aplikasi. Pilih izin yang relevan untuk skenario Anda (misalnya, Incident.Read.All), lalu pilih Tambahkan izin.

    Panel izin aplikasi di portal Microsoft Defender

    Note

    Anda perlu memilih izin yang relevan untuk skenario Anda. Membaca semua insiden hanyalah contoh. Untuk menentukan izin mana yang Anda butuhkan, periksa bagian Izin di API yang ingin Anda panggil.

    Misalnya, untuk menjalankan kueri tingkat lanjut, pilih izin 'Jalankan kueri tingkat lanjut'; untuk mengisolasi perangkat, pilih izin 'Isolate machine'.

  6. Pilih Berikan perizinan admin. Setiap kali Anda menambahkan izin, Anda harus memilih Beri persetujuan admin agar berlaku.

    Panel terkait pemberian persetujuan di portal Microsoft Defender

  7. Untuk menambahkan rahasia ke aplikasi, pilih Sertifikat &rahasia, tambahkan deskripsi ke rahasia, lalu pilih Tambahkan.

    Tip

    Setelah Anda memilih Tambahkan, pilih salin nilai rahasia yang dihasilkan. Anda tidak akan dapat mengambil nilai rahasia setelah anda pergi.

    Panel buat aplikasi di portal Microsoft Defender

  8. Catat ID aplikasi dan ID penyewa Anda di tempat yang aman. Mereka tercantum di bawah Gambaran Umum di halaman aplikasi Anda.

    Panel Gambaran Umum di portal Microsoft Defender

  9. Hanya untuk mitra Microsoft Defender: Ikuti petunjuk ini untuk akses mitra melalui API Microsoft Defender XDR, atur aplikasi Anda menjadi multipenyewa, sehingga dapat tersedia di semua penyewa setelah Anda menerima persetujuan admin. Akses mitra diperlukan untuk aplikasi pihak ketiga—misalnya, jika Anda membuat aplikasi yang dimaksudkan untuk dijalankan di beberapa penyewa pelanggan. Ini tidak diperlukan jika Anda membuat layanan yang ingin Anda jalankan di penyewa Anda saja, seperti aplikasi untuk penggunaan Anda sendiri yang hanya berinteraksi dengan data Anda sendiri. Untuk mengatur aplikasi Anda menjadi multipenyewa:

    • Buka Autentikasi, dan tambahkan https://portal.azure.com sebagai URI Pengalihan.

    • Di bagian bawah halaman, di bawah Jenis akun yang didukung, pilih Akun di persetujuan aplikasi direktori organisasi apa pun untuk aplikasi multipenyewa Anda.

    Karena aplikasi Anda berinteraksi dengan Microsoft Defender XDR atas nama pengguna Anda, aplikasi perlu disetujui untuk setiap penyewa tempat Anda ingin menggunakannya.

    Administrator Direktori Aktif untuk setiap penyewa perlu memilih tautan persetujuan dan menyetujui aplikasi Anda.

    Tautan persetujuan memiliki struktur berikut:

    https://login.microsoftonline.com/common/oauth2/authorize?prompt=consent&client_id=<00000000-0000-0000-0000-000000000000>&response_type=code&sso_reload=true

    Digit 00000000-0000-0000-0000-000000000000 harus diganti dengan ID Aplikasi Anda.

Selesai! Anda berhasil mendaftarkan aplikasi! Lihat contoh berikut untuk akuisisi dan validasi token.

Mendapatkan token akses

Untuk informasi selengkapnya tentang token Microsoft Entra, lihat tutorial Microsoft Entra.

Penting

Meskipun contoh di bagian ini mendorong Anda untuk menempelkan nilai rahasia untuk tujuan pengujian, Anda tidak boleh melakukan hardcode rahasia ke dalam aplikasi yang berjalan dalam produksi. Pihak ketiga dapat menggunakan rahasia Anda untuk mengakses sumber daya. Anda dapat membantu menjaga rahasia aplikasi tetap aman dengan menggunakan Azure Key Vault. Untuk contoh praktis tentang cara melindungi aplikasi, lihat Mengelola rahasia di aplikasi server Anda dengan Azure Key Vault.

Mendapatkan token akses menggunakan 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, such as the Azure Key Vault!

$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

Mendapatkan token akses menggunakan C#

Note

Kode berikut diuji dengan Nuget Microsoft. Identity.Client 3.19.8.

Penting

Microsoft. Paket IdentityModel.Clients.ActiveDirectory NuGet dan Azure AD Authentication Library (ADAL) tidak digunakan lagi. Tidak ada fitur baru yang ditambahkan sejak 30 Juni 2020. Kami sangat menyarankan Anda untuk melakukan upgrade, lihat panduan migrasi untuk detail selengkapnya.

  1. Buat aplikasi konsol baru.

  2. Instal NuGet Microsoft. Identity.Client.

  3. Tambahkan baris berikut:

    using Microsoft.Identity.Client;

  4. Salin dan tempel kode berikut ke dalam aplikasi Anda (jangan lupa untuk memperbarui tiga variabel: tenantId, , clientIdappSecret):

    csharp
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;

Mendapatkan token akses menggunakan 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"]

Mendapatkan token akses menggunakan curl

Note

Curl telah diinstal sebelumnya pada Windows 10, versi 1803 dan yang lebih baru. Untuk versi Windows lainnya, unduh dan instal alat langsung dari situs web curl resmi.

  1. Buka prompt perintah, dan atur CLIENT_ID ke ID aplikasi Azure Anda.

  2. Atur CLIENT_SECRET ke rahasia aplikasi Azure Anda.

  3. Atur TENANT_ID ke ID penyewa Azure pelanggan yang ingin menggunakan aplikasi Anda untuk mengakses Microsoft Defender.

  4. Jalankan perintah berikut:

    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://api.security.microsoft.com/.default" -d "client_secret=%CLIENT_SECRET%" "https://login.microsoftonline.com/%TENANT_ID%/oauth2/v2.0/token" -k

    Respons yang berhasil akan terlihat seperti:

    {"token_type":"Bearer","expires_in":3599,"ext_expires_in":0,"access_token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIn <truncated> aWReH7P0s0tjTBX8wGWqJUdDA"}

Validasi token

  1. Salin dan tempel token ke situs web validator token web JSON, JWT, untuk mendekodenya.

  2. Pastikan bahwa klaim peran dalam token yang didekodekan berisi izin yang diinginkan.

    Dalam gambar berikut, Anda dapat melihat token yang didekodekan yang diperoleh dari aplikasi, dengan Incidents.Read.Allizin , Incidents.ReadWrite.All, dan AdvancedHunting.Read.All :

    Panel Token yang didekodekan di portal Microsoft Defender

Menggunakan token untuk mengakses API Microsoft Defender XDR

  1. Pilih API yang ingin Anda gunakan (insiden, atau perburuan tingkat lanjut). Untuk informasi selengkapnya, lihat API Microsoft Defender yang didukung.

  2. Dalam permintaan berbasis HTTP yang akan Anda kirim, atur header otorisasi ke "Bearer" <token>, Pembawa menjadi skema otorisasi, dan token menjadi token yang divalidasi.

  3. Token kedaluwarsa dalam waktu satu jam. Anda dapat mengirim lebih dari satu permintaan selama waktu ini dengan token yang sama.

Contoh berikut menunjukkan cara mengirim permintaan untuk mendapatkan daftar insiden menggunakan 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();

Tip

Apakah Anda ingin mempelajari lebih lanjut? Terlibatlah dengan komunitas Microsoft Security di Komunitas Teknologi kami: Microsoft Defender XDR Tech Community.

  • Last updated on