Memahami API Privileged Identity Management

Anda dapat melakukan tugas Privileged Identity Management (PIM) menggunakan Microsoft Graph API untuk peran Azure Active Directory (Azure AD) dan Azure Resource Manager API untuk peran Azure. Artikel ini menjelaskan konsep penting untuk menggunakan Microsoft Graph API untuk Privileged Identity Management.

Untuk permintaan dan detail lainnya tentang API PIM, lihat:

Riwayat API PIM

Ada beberapa iterasi API PIM selama beberapa tahun terakhir. Anda akan menemukan beberapa tumpang tindih dalam fungsionalitas, tetapi tidak mewakili perkembangan versi yang linier.

Iterasi 1 – Tidak digunakan lagi

Di bawah titik akhir /beta/privilegedRoles, Microsoft memiliki versi klasik PIM API yang hanya mendukung peran Azure AD dan tidak lagi didukung. Akses ke API ini tidak digunakan lagi pada Juni 2021.

Iterasi 2 – Mendukung peran Azure AD dan peran sumber daya Azure

Di bawah titik akhir /beta/privilegedAccess, Microsoft mendukung /aadRoles dan /azureResources. Titik akhir ini masih tersedia di penyewa Anda tetapi Microsoft merekomendasikan untuk tidak memulai pengembangan baru dengan API ini. API beta ini tidak akan pernah dirilis ke ketersediaan umum dan pada akhirnya akan ditolak.

Iterasi saat ini – Peran Azure AD di Microsoft Graph dan peran sumber daya Azure di Azure Resource Manager

Sekarang dalam versi beta, Microsoft memiliki iterasi akhir dari API PIM sebelum kami merilis API ke ketersediaan umum. Berdasarkan umpan balik pelanggan, Azure AD PIM API sekarang berada di bawah set API unifiedRoleManagement dan Azure Resource PIM API sekarang berada di bawah API penetapan peran Azure Resource Manager. Lokasi ini juga memberikan beberapa keuntungan tambahan termasuk:

  • Perataan API PIM untuk API penetapan peran reguler untuk peran Azure AD dan peran Azure Resource.
  • Mengurangi kebutuhan untuk memanggil API PIM tambahan untuk onboarding sumber daya, mendapatkan sumber daya, atau mendapatkan definisi peran.
  • Mendukung izin khusus aplikasi.
  • Fitur baru seperti persetujuan dan konfigurasi pemberitahuan email.

Dalam iterasi saat ini, tidak ada dukungan API untuk pemberitahuan PIM dan grup akses istimewa.

Izin saat ini yang diperlukan

Peran Azure AD

Untuk memanggil peran PIM Graph API untuk Azure AD, Anda akan memerlukan setidaknya salah satu izin berikut:

  • RoleManagement.ReadWrite.Directory

  • RoleManagement.Read.Directory

    Cara termudah untuk menentukan izin yang diperlukan adalah dengan menggunakan kerangka kerja persetujuan Azure Active Directory.

Peran sumber daya Azure

Peran sumber daya PIM API untuk Azure dikembangkan di atas kerangka kerja Azure Resource Manager. Anda harus memberikan persetujuan kepada Azure Resource Management tetapi tidak memerlukan izin Graph API. Anda juga perlu memastikan pengguna atau perwakilan layanan yang memanggil API memiliki setidaknya peran Pemilik atau Administrator Akses Pengguna pada sumber daya yang ingin Anda berikan.

Memanggil PIM API dengan token khusus aplikasi

Peran Azure AD

PIM API kini mendukung izin khusus aplikasi di atas izin yang didelegasikan.

  • Untuk izin khusus aplikasi, Anda harus memanggil API dengan aplikasi yang sudah disetujui dengan izin peran Azure AD atau Azure yang diperlukan.
  • Untuk izin yang didelegasikan, Anda harus memanggil API PIM dengan pengguna dan token aplikasi. Pengguna harus ditetapkan ke peran Administrator Global atau peran Administrator Peran Istimewa, dan memastikan bahwa prinsipal layanan yang memanggil API memiliki setidaknya peran Pemilik atau Administrator Akses Pengguna pada sumber daya yang ingin Anda berikan.

Peran sumber daya Azure

API PIM untuk sumber daya Azure hanya mendukung panggilan pengguna dan aplikasi saja. Cukup pastikan perwakilan layanan memiliki peran pemilik atau administrator akses pengguna pada sumber daya.

Desain iterasi API saat ini

PIM API terdiri dari dua kategori yang konsisten untuk peran API untuk Azure AD dan peran sumber daya Azure: permintaan API penugasan dan aktivasi, dan pengaturan kebijakan.

API penugasan dan aktivasi

Untuk membuat penugasan yang memenuhi syarat, penugasan yang memenuhi syarat/aktif yang terikat waktu, dan untuk mengaktifkan penugasan, PIM menyediakan entitas berikut:

  • RoleAssignmentSchedule
  • RoleEligibilitySchedule
  • RoleAssignmentScheduleInstance
  • RoleEligibilityScheduleInstance
  • RoleAssignmentScheduleRequest
  • RoleEligibilityScheduleRequest

Entitas ini bekerja bersama entitas roleDefinition dan roleAssignment yang sudah ada sebelumnya untuk peran Azure AD dan peran Azure untuk memungkinkan Anda membuat skenario ujung ke ujung.

  • Jika Anda mencoba membuat atau mengambil penetapan peran persisten (aktif) yang tidak memiliki jadwal (waktu mulai atau berakhir), Anda harus menghindari entitas PIM ini dan berfokus pada operasi baca/tulis di bawah entitas roleAssignment

  • Untuk membuat penugasan yang memenuhi syarat dengan atau tanpa waktu kedaluwarsa, Anda dapat menggunakan operasi tulis pada roleEligibilityScheduleRequest

  • Untuk membuat penugasan persisten (aktif) dengan jadwal (waktu mulai atau berakhir), Anda dapat menggunakan operasi tulis pada roleAssignmentScheduleRequest

  • Untuk mengaktifkan penugasan yang memenuhi syarat, Anda juga harus menggunakan operasi tulis pada roleAssignmentScheduleRequest dengan parameter tindakan yang dimodifikasi yang disebut selfActivate

Setiap objek permintaan akan membuat roleAssignmentSchedule atau objek roleEligibilitySchedule. Objek ini adalah baca-saja dan menunjukkan jadwal semua penugasan saat ini dan yang akan datang.

Saat penugasan yang memenuhi syarat diaktifkan, peranEligibilityScheduleInstance terus ada. roleAssignmentScheduleRequest untuk aktivasi akan menciptakan peran roleAssignmentSchedule dan roleAssignmentScheduleInstance untuk durasi yang diaktifkan.

Objek instans adalah penugasan aktual yang saat ini ada baik itu penugasan yang memenuhi syarat atau penugasan aktif. Anda harus menggunakan operasi GET pada entitas instans untuk mengambil daftar penugasan/pengguna aktif yang memenuhi syarat ke peran/pengguna.

API pengaturan kebijakan

Untuk mengelola pengaturan, kami menyediakan entitas berikut:

  • roleManagementPolicy
  • roleManagementPolicyAssignment

Kebijakan manajemen peran mendefinisikan pengaturan aturan. Misalnya, apakah MFA/persetujuan diperlukan, baik dan siapa yang harus mengirim pemberitahuan email, atau apakah penugasan permanen diizinkan atau tidak. Penetapan kebijakan melampirkan kebijakan ke peran tertentu.

Gunakan API ini untuk mendapatkan daftar semua roleManagementPolicyAssignments, filter dengan roleDefinitionID yang ingin Anda modifikasi, lalu perbarui kebijakan yang terkait dengan policyAssignment.

Hubungan antara entitas PIM dan entitas penugasan peran

Satu-satunya tautan antara entitas PIM dan entitas penetapan peran untuk penugasan persisten (aktif) untuk peran Azure AD atau peran Azure adalah roleAssignmentScheduleInstance. Ada pemetaan satu-ke-satu antara dua entitas. Pemetaan itu berarti roleAssignment dan roleAssignmentScheduleInstance akan mencakup:

  • Penugasan persisten (aktif) yang dibuat di luar PIM
  • Penugasan persisten (aktif) dengan jadwal yang dibuat di dalam PIM
  • Penugasan yang memenuhi syarat yang diaktifkan

Langkah berikutnya