Membuat aplikasi untuk mengakses API Microsoft Defender XDR atas nama pengguna

  • Berlaku untuk: Microsoft Defender XDR

Penting

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

Buat aplikasi untuk mendapatkan akses terprogram ke Microsoft Defender atas nama satu pengguna.

Jika Anda memerlukan akses terprogram ke Microsoft Defender tanpa pengguna yang ditentukan (misalnya, jika Anda menulis aplikasi latar belakang atau daemon), lihat Membuat aplikasi untuk mengakses Microsoft Defender tanpa pengguna. Jika Anda perlu menyediakan akses untuk beberapa penyewa—misalnya, jika Anda melayani organisasi besar atau sekelompok pelanggan—lihat 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 harus 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

Note

Saat mengakses API Microsoft Defender atas nama pengguna, Anda memerlukan izin aplikasi dan izin pengguna yang benar.

Tip

Jika Anda memiliki izin untuk melakukan tindakan di portal, Anda memiliki izin untuk melakukan tindakan di API. Untuk informasi selengkapnya tentang peran dan izin, lihat Mengelola akses ke Microsoft Defender dengan peran global Microsoft Entra.

Buat aplikasi

  1. Masuk ke Azure.

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

    Opsi Pendaftaran baru di panel Kelola di portal Azure

  3. Dalam formulir, pilih nama untuk aplikasi Anda dan masukkan informasi berikut untuk URI pengalihan, lalu pilih Daftar.

    Panel pendaftaran aplikasi di portal Azure

  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.

    Tip

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

    Panel API organisasi Anda di portal Microsoft Defender

    • Pilih Izin yang didelegasikan. Pilih izin yang relevan untuk skenario Anda (misalnya Incident.Read), lalu pilih Tambahkan izin.

      Panel Izin yang didelegasikan 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, silakan lihat 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'.

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

    Panel pemberian persetujuan admin di portal Microsoft Defender

  6. 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

Mendapatkan token akses

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

Mendapatkan token akses atas nama pengguna menggunakan PowerShell

Gunakan pustaka MSAL.PS untuk memperoleh token akses dengan izin Yang didelegasikan. Jalankan perintah berikut untuk mendapatkan token akses atas nama pengguna:

Install-Module -Name MSAL.PS # Install the MSAL.PS module from PowerShell Gallery

$TenantId = " " # Paste your directory (tenant) ID here.
$AppClientId="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" # Paste your application (client) ID here.

$MsalParams = @{
   ClientId = $AppClientId
   TenantId = $TenantId
   Scopes   = 'https://graph.microsoft.com/User.Read.All','https://graph.microsoft.com/Files.ReadWrite','https://api.securitycenter.windows.com/AdvancedQuery.Read'
}

$MsalResponse = Get-MsalToken @MsalParams
$AccessToken  = $MsalResponse.AccessToken
 
$AccessToken # Display the token in PS console

Validasi token

  1. Salin dan tempel token ke 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 :

Bagian izin di panel Token Yang Dikodekan di portal Microsoft Defender

Menggunakan token untuk mengakses API Microsoft Defender

  1. Pilih API yang ingin Anda gunakan (insiden, atau perburuan tingkat lanjut). Untuk informasi selengkapnya, lihat API Microsoft Defender yang didukung.
  2. Dalam permintaan http yang akan Anda kirim, atur header otorisasi ke "Bearer" <token>, Pembawa menjadi skema otorisasi, dan token menjadi token yang divalidasi.
  3. Token akan 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