Membuat aplikasi dengan akses mitra ke API Microsoft Defender XDR

  • 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 Microsoft Entra yang memiliki akses terprogram ke Microsoft Defender atas nama pengguna di beberapa penyewa. Aplikasi multi-penyewa berguna untuk melayani sekelompok besar pengguna.

Jika Anda memerlukan akses terprogram ke Microsoft Defender atas nama satu pengguna, lihat Membuat aplikasi untuk mengakses API Microsoft Defender atas nama pengguna. Jika Anda memerlukan akses tanpa pengguna yang ditentukan secara eksplisit (misalnya, jika Anda menulis aplikasi latar belakang atau daemon), lihat Membuat aplikasi untuk mengakses Microsoft Defender tanpa pengguna. 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.

Karena aplikasi ini multi-penyewa, Anda juga memerlukan persetujuan admin dari setiap penyewa atas nama penggunanya.

Artikel ini menjelaskan cara:

  • Membuat aplikasi Microsoft Entra multi-penyewa
  • Dapatkan persetujuan administrator untuk aplikasi Anda untuk mengakses sumber daya Microsoft Defender yang dibutuhkannya.
  • Mendapatkan token akses ke Microsoft Defender
  • Validasi token

Microsoft Defender mengekspos sebagian besar data dan tindakannya melalui serangkaian API terprogram. API tersebut membantu Anda mengotomatiskan alur kerja dan berinovasi berdasarkan kemampuan Microsoft Defender. Akses API 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:

  • Buat aplikasi Microsoft Entra multi-penyewa.
  • Dapatkan persetujuan administrator untuk aplikasi Anda untuk mengakses sumber daya Microsoft Defender yang dibutuhkannya.
  • Dapatkan token akses menggunakan aplikasi ini.
  • Gunakan token untuk mengakses API Microsoft Defender.

Langkah-langkah berikut memandu Anda membuat aplikasi Microsoft Entra multi-penyewa, mendapatkan token akses ke Microsoft Defender, dan memvalidasi token.

Membuat aplikasi multi-penyewa

  1. Masuk ke Azure.

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

    Bagian pendaftaran aplikasi di portal Microsoft Defender

  3. Dalam formulir pendaftaran:

    • Pilih nama untuk aplikasi Anda.
    • Dari Jenis akun yang didukung, pilih Akun di direktori organisasi apa pun (Direktori Microsoft Entra apa pun) - Multipenyewa.
    • Isi bagian URI Pengalihan . Pilih ketik Web dan berikan URI pengalihan sebagai https://portal.azure.com.

    Setelah Selesai mengisi formulir, pilih Daftar.

    Bagian pendaftaran aplikasi di portal Microsoft Defender

  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.

    Bagian penggunaan API 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, 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'.

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

    Bagian untuk memberikan persetujuan admin 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.

    Bagian Penambahan rahasia 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. Tambahkan aplikasi ke penyewa pengguna Anda.

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

    Administrator dari penyewa pengguna Anda perlu melihat tautan persetujuan dan menyetujui aplikasi Anda.

    Tautan persetujuan adalah formulir:

    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.

    Setelah mengklik tautan persetujuan, masuk sebagai administrator penyewa pengguna dan berikan persetujuan untuk aplikasi.

    Halaman aplikasi persetujuan di portal Microsoft Defender

    Anda juga perlu meminta ID penyewa kepada pengguna Anda. ID penyewa adalah salah satu pengidentifikasi yang digunakan untuk memperoleh token akses.

  • Selesai! Anda berhasil mendaftarkan aplikasi!
  • Lihat contoh di bawah ini 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.

Tip

Dalam contoh berikut, gunakan ID penyewa pengguna untuk menguji bahwa skrip berfungsi.

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!

$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

Paket Microsoft.IdentityModel.Clients.ActiveDirectory NuGet dan Pustaka Otentikasi Azure AD (ADAL) telah dihentikan. 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):

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

Respons yang berhasil akan terlihat seperti ini:

{"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 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