Akses Microsoft Defender for Cloud Apps API dengan konteks pengguna

Halaman ini menjelaskan cara membuat aplikasi untuk mendapatkan akses terprogram ke Defender for Cloud Apps atas nama pengguna.

Jika Anda memerlukan akses terprogram Microsoft Defender for Cloud Apps tanpa pengguna, lihat Akses Microsoft Defender for Cloud Apps dengan konteks aplikasi.

Jika Anda tidak yakin akses mana yang Anda butuhkan, baca halaman Pengenalan.

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

  • Membuat aplikasi Microsoft Entra
  • Dapatkan token akses menggunakan aplikasi ini
  • Gunakan token untuk mengakses API Defender for Cloud Apps

Halaman ini menjelaskan cara membuat aplikasi Microsoft Entra, mendapatkan token akses untuk Microsoft Defender for Cloud Apps dan memvalidasi token.

Note

Saat mengakses API Microsoft Defender for Cloud Apps atas nama pengguna, Anda memerlukan izin Aplikasi dan izin pengguna yang benar. Jika Anda tidak terbiasa dengan izin pengguna di Microsoft Defender for Cloud Apps, lihat Mengelola akses admin.

Tip

Jika Anda memiliki izin untuk melakukan tindakan di portal, Anda memiliki izin untuk melakukan tindakan di API.

Buat aplikasi

  1. Di pusat admin Microsoft Entra, daftarkan aplikasi baru. Untuk informasi selengkapnya, lihat Mulai Cepat: Mendaftarkan aplikasi dengan pusat admin Microsoft Entra.

  2. Saat halaman Daftarkan aplikasi muncul, masukkan informasi pendaftaran aplikasi Anda:

    • Nama - Masukkan nama aplikasi yang bermakna yang ditampilkan kepada pengguna aplikasi.

    • Jenis akun yang didukung - Pilih akun mana yang ingin Anda dukung aplikasi Anda.

      Jenis akun yang didukung Deskripsi
      Akun dalam direktori organisasi ini saja Pilih opsi ini jika Anda membangun aplikasi lini bisnis (LOB). Opsi ini tidak tersedia jika Anda tidak mendaftarkan aplikasi di direktori.

      Opsi ini memetakan ke penyewa tunggal khusus Microsoft Entra.

      Ini adalah opsi default kecuali Anda mendaftarkan aplikasi di luar direktori. Dalam kasus di mana aplikasi terdaftar di luar direktori, defaultnya adalah Microsoft Entra akun Microsoft multipenyewa dan pribadi.
      Akun di direktori organisasi apa pun Pilih opsi ini jika Anda ingin menargetkan semua pelanggan bisnis dan pendidikan.

      Opsi ini memetakan ke multitenant khusus Microsoft Entra.

      Jika Anda mendaftarkan aplikasi sebagai penyewa tunggal khusus Microsoft Entra, Anda dapat memperbaruinya menjadi Microsoft Entra multipenyewa dan kembali ke penyewa tunggal melalui panel Autentikasi.
      Akun di direktori organisasi dan akun Microsoft pribadi apa pun Pilih opsi ini untuk menargetkan kumpulan pelanggan terluas.

      Opsi ini memetakan ke Microsoft Entra akun multipenyewa dan Microsoft pribadi.

      Jika Anda mendaftarkan aplikasi sebagai Microsoft Entra akun multipenyewa dan Microsoft pribadi, Anda tidak dapat mengubahnya di UI. Sebagai gantinya, Anda harus menggunakan editor manifes aplikasi untuk mengubah jenis akun yang didukung.

    • URI Pengalihan (opsional) - Pilih jenis aplikasi yang Anda buat, **Web, atau Klien publik (seluler &desktop), lalu masukkan URI pengalihan (atau URL balasan) untuk aplikasi Anda.

      • Untuk aplikasi web, berikan URL dasar aplikasi Anda. Misalnya, http://localhost:31544 mungkin URL untuk aplikasi web yang berjalan di komputer lokal Anda. Pengguna akan menggunakan URL ini untuk masuk ke aplikasi klien web.
      • Untuk aplikasi klien publik, berikan URI yang digunakan oleh Microsoft Entra ID untuk mengembalikan respons token. Masukkan nilai khusus untuk aplikasi Anda, seperti myapp://auth.

      Untuk melihat contoh spesifik untuk aplikasi web atau aplikasi asli, lihat mulai cepat kami.

      Setelah selesai, pilih Daftarkan.

  3. Izinkan Aplikasi Anda mengakses Microsoft Defender for Cloud Apps dan menetapkan izin 'Baca pemberitahuan':

  4. Pada halaman aplikasi Anda, pilih API Izin> APITambahkan izin>organisasi saya menggunakan> jenis Microsoft Cloud App Security lalu pilih Microsoft Cloud App Security.

    Note

    Microsoft Cloud App Security tidak muncul di daftar asli. Mulai tulis namanya di kotak teks untuk melihatnya muncul. Pastikan untuk mengetikkan nama ini, meskipun produk sekarang disebut Defender for Cloud Apps.

    Cuplikan layar yang memperlihatkan cara menambahkan izin.

  5. Pilih Izin >Investigasi.Baca> pilih Tambahkan izin

    Cuplikan layar memperlihatkan cara menambahkan izin aplikasi.

    Note

    Pilih izin yang relevan. Investigation.Read hanyalah contoh. Untuk cakupan izin lainnya, lihat Cakupan izin yang didukung

  6. Untuk menentukan izin mana yang Anda butuhkan, lihat bagian Izin di API yang ingin Anda panggil.

  7. Pilih Berikan izin admin

    Note

    Setiap kali Anda menambahkan izin, Anda harus memilih Berikan persetujuan admin agar izin baru diterapkan.

    Cuplikan layar yang memperlihatkan opsi untuk memberikan persetujuan admin.

  8. Tulis ID aplikasi dan ID penyewa Anda.

  9. Pada halaman aplikasi Anda, buka Gambaran Umum dan salin informasi berikut:

    Cuplikan layar yang memperlihatkan ID aplikasi yang dibuat.

Cakupan izin yang didukung

Nama izin Deskripsi Tindakan yang didukung
Investigation.read Lakukan semua tindakan yang didukung pada aktivitas dan pemberitahuan kecuali menutup pemberitahuan.
Lihat rentang IP tetapi tidak menambahkan, memperbarui, atau menghapus.

Lakukan semua tindakan entitas.		 Daftar aktivitas, pengambilan, umpan balik
Daftar pemberitahuan, ambil, tandai sebagai sudah dibaca/belum dibaca
Daftar entitas, ambil, ambil pohon
Daftar subnet
Investigation.manage Lakukan semua tindakan investigation.read selain mengelola pemberitahuan dan rentang IP. Daftar aktivitas, pengambilan, umpan balik
Daftar pemberitahuan, ambil, tandai sebagai sudah dibaca/belum dibaca, tutup
Daftar entitas, ambil, ambil pohon
Daftar subnet, buat/perbarui/hapus
Discovery.read Lakukan semua tindakan yang didukung pada aktivitas dan pemberitahuan kecuali menutup pemberitahuan.
Mencantumkan laporan dan kategori penemuan.		 Daftar pemberitahuan, ambil, tandai sebagai sudah dibaca/belum dibaca
Laporan daftar penemuan, kategori laporan daftar
Discovery.manage Izin Discovery.read
Tutup pemberitahuan, unggah file penemuan, dan hasilkan skrip blok		 Daftar pemberitahuan, ambil, tandai sebagai sudah dibaca/belum dibaca, tutup
Laporan daftar penemuan, kategori laporan daftar
Unggahan file penemuan, hasilkan skrip blok
Settings.read Mencantumkan rentang IP. Daftar subnet
Settings.manage Mencantumkan dan mengelola rentang IP. Daftar subnet, buat/perbarui/hapus

Mendapatkan token akses

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

Menggunakan C#

  • Salin/Tempel kelas berikut di aplikasi Anda.
  • Gunakan metode AcquireUserTokenAsync dengan ID aplikasi, ID penyewa, dan autentikasi Anda memperoleh token.

Note

Meskipun sampel kode berikut menunjukkan cara memperoleh token menggunakan alur nama pengguna dan kata sandi, Microsoft menyarankan Agar Anda menggunakan alur autentikasi yang lebih aman di lingkungan produksi.

namespace MDA
{
    using System.Net.Http;
    using System.Text;
    using System.Threading.Tasks;
    using Newtonsoft.Json.Linq;

    public static class MDAUtils
    {
        private const string Authority = "https://login.microsoftonline.com";

        private const string MDAId = "05a65629-4c1b-48c1-a78b-804c4abdd4af";
        private const string Scope = "Investigation.read";

        public static async Task<string> AcquireUserTokenAsync(string username, string password, string appId, string tenantId)
        {
            using (var httpClient = new HttpClient())
            {
                var urlEncodedBody = $"scope={MDAId}/{Scope}&client_id={appId}&grant_type=password&username={username}&password={password}";

                var stringContent = new StringContent(urlEncodedBody, Encoding.UTF8, "application/x-www-form-urlencoded");

                using (var response = await httpClient.PostAsync($"{Authority}/{tenantId}/oauth2/token", stringContent).ConfigureAwait(false))
                {
                    response.EnsureSuccessStatusCode();

                    var json = await response.Content.ReadAsStringAsync().ConfigureAwait(false);

                    var jObject = JObject.Parse(json);

                    return jObject["access_token"].Value<string>();
                }
            }
        }
    }
}

Validasi token

Verifikasi untuk memastikan Anda mendapatkan token yang benar:

  • Salin/tempel ke JWT token yang Anda dapatkan di langkah sebelumnya untuk mendekodenya.

  • Validasi bahwa Anda mendapatkan klaim 'scp' dengan izin aplikasi yang diinginkan.

  • Pada cuplikan layar di bawah ini Anda dapat melihat token yang didekodekan yang diperoleh dari aplikasi dalam tutorial:

    Cuplikan layar yang memperlihatkan token yang didekodekan.

Gunakan token untuk mengakses API Microsoft Defender for Cloud Apps

  • Pilih API yang ingin Anda gunakan. Untuk informasi selengkapnya, lihat API Defender for Cloud Apps.

  • Atur header Otorisasi dalam permintaan HTTP yang Anda kirim ke "Pembawa {token}" (Pembawa adalah skema Otorisasi).

  • Waktu kedaluwarsa token adalah 1 jam (Anda dapat mengirim lebih dari satu permintaan dengan token yang sama).

  • Contoh pengiriman permintaan untuk mendapatkan daftar pemberitahuan menggunakan C#:

    var httpClient = new HttpClient();

var request = new HttpRequestMessage(HttpMethod.Get, "https://portal.cloudappsecurity.com/cas/api/v1/alerts/");

request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);

var response = httpClient.SendAsync(request).GetAwaiter().GetResult();

// Do something useful with the response

Baca juga

  • Last updated on