Menggunakan Azure PIM untuk mengelola akses aktif dengan REST API

Artikel
07/19/2023

Azure Privileged Identity Management (PIM) memungkinkan Anda membatasi akses administrator yang berdiri ke peran istimewa, menemukan siapa yang memiliki akses, dan meninjau akses istimewa. Artikel ini menjelaskan cara umum untuk mengelola akses menggunakan REST API.

Mencantumkan penugasan aktif

Untuk mencantumkan penetapan peran aktif (akses daftar), Anda dapat menggunakan salah satu Instans Jadwal Penetapan Peran - Daftar Untuk Cakupan atau Jadwal Penetapan Peran - Daftar Untuk Scope REST API. Untuk menyempurnakan hasil, Anda menentukan cakupan dan filter opsional. Untuk memanggil API, Anda harus memiliki akses ke Microsoft.Authorization/roleAssignments/read operasi pada cakupan yang ditentukan. Semua peran bawaan diberikan akses ke operasi ini.

Penting

Perbedaan antara jadwal dan instans jadwal adalah bahwa meskipun instans jadwal hanya menyertakan penugasan yang aktif pada waktu saat ini, jadwal juga mencakup penugasan yang akan aktif di masa mendatang.

Mulai dengan permintaan berikut:

GET https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleAssignmentScheduleInstances?api-version=2020-10-01&$filter={filter}

GET https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleAssignmentSchedules?api-version=2020-10-01&$filter={filter}

Di dalam URI, ganti {scope} dengan cakupan yang ingin Anda cantumkan penetapan perannya.

Cakupan	Jenis
`providers/Microsoft.Management/managementGroups/{mg-name}`	Grup Manajemen
`subscriptions/{subscriptionId}`	Langganan
`subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1`	Grup sumber daya
`subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1/providers/Microsoft.Web/sites/mysite1`	Sumber daya

Ganti {filter} dengan kondisi yang ingin Anda terapkan untuk memfilter daftar penetapan peran.

Filter	Deskripsi
`$filter=atScope()`	Cantumkan penetapan peran hanya untuk cakupan yang ditentukan, tidak termasuk penetapan peran pada sub-cakupan.
`$filter=principalId%20eq%20'{objectId}'`	Mencantumkan penetapan peran untuk pengguna, grup, atau perwakilan layanan tertentu.
`$filter=roleDefinitionId%20eq%20'{roleDefinitionId}'`	Mencantumkan penetapan peran untuk definisi peran tertentu.
`$filter=assignedTo('{objectId}')`	Mencantumkan penetapan peran untuk pengguna tertentu, termasuk yang diwarisi dari grup.
`$filter=asTarget()`	Mencantumkan penetapan peran untuk pengguna atau perwakilan layanan saat ini, termasuk yang diwarisi dari grup.
`$filter=assignedTo('{objectId}')+and+atScope()`	Mencantumkan penetapan peran untuk pengguna tertentu, termasuk yang diwarisi dari grup hanya untuk cakupan yang ditentukan, tidak termasuk penetapan peran pada subskop.

Memberikan penugasan aktif

Untuk membuat penetapan peran aktif (memberikan akses), Anda menggunakan Permintaan Jadwal Penetapan Peran - Buat REST API dan tentukan prinsip keamanan, definisi peran, jadwal, requestType = AdminAssign dan cakupan. Untuk memanggil API ini, Anda harus memiliki akses ke Microsoft.Authorization/roleAssignments/write operasi. Dari peran bawaan, hanya Pemilik dan Admin Akses Pengguna yang diberikan akses ke operasi ini.

Gunakan Definisi Peran - Daftar REST API atau lihat Peran bawaan untuk mendapatkan pengidentifikasi untuk definisi peran yang ingin Anda tetapkan.
Gunakan alat GUID untuk menghasilkan pengidentifikasi unik yang akan digunakan untuk pengidentifikasi penetapan peran. Pengidentifikasi memiliki format: 00000000-0000-0000-0000-000000000000

Mulai dengan permintaan dan isi berikut:

PUT https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleAssignmentScheduleRequests/{roleAssignmentScheduleRequestName}?api-version=2020-10-01

{
  "Properties": {
    "RoleDefinitionId": "/subscriptions/{subscriptionId}/providers/Microsoft.Authorization/roleDefinitions/{roleDefinitionId}",
    "PrincipalId": "{principalId}",
    "RequestType": "AdminAssign",
    "ScheduleInfo": {
      "StartDateTime": "2020-09-09T21:31:27.91Z",
      "Expiration": {
        "Type": "AfterDuration", // Values: AfterDuration, AfterDateTime, NoExpiration
        "EndDateTime": null,
        "Duration": "P30D" // Use ISO 8601 format
      }
    }
  }
}

Dalam URI, ganti {cakupan} dengan cakupan untuk penetapan peran.

Cakupan	Jenis
`providers/Microsoft.Management/managementGroups/{mg-name}`	Grup Manajemen
`subscriptions/{subscriptionId}`	Langganan
`subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1`	Grup sumber daya
`subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1/providers/Microsoft.Web/sites/mysite1`	Sumber daya

Ganti {roleAssignmentScheduleRequestName} dengan pengidentifikasi GUID penetapan peran.
Dalam isi permintaan, ganti {subscriptionId} dengan pengidentifikasi langganan Anda.
Ganti {roleDefinitionId} dengan pengidentifikasi definisi peran.
Ganti {principalId} dengan pengidentifikasi objek pengguna, grup, atau perwakilan layanan yang akan diberi peran.

Menghapus penetapan aktif

Untuk menghapus penetapan peran aktif (menghapus akses), gunakan Permintaan Jadwal Penetapan Peran - Buat REST API untuk membuat permintaan baru untuk mencabut penetapan dan menentukan prinsip keamanan, definisi peran, requestType = AdminRemove dan cakupan. Untuk memanggil API ini, Anda harus memiliki akses ke Microsoft.Authorization/roleAssignments/write operasi. Dari peran bawaan, hanya Pemilik dan Admin Akses Pengguna yang diberikan akses ke operasi ini.

Gunakan alat GUID untuk menghasilkan pengidentifikasi unik yang akan digunakan untuk pengidentifikasi penetapan peran. Pengidentifikasi memiliki format: 00000000-0000-0000-0000-000000000000

Mulai dengan permintaan berikut:

PUT https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleAssignmentScheduleRequests/{roleAssignmentScheduleRequestName}?api-version=2020-10-01

{
  "Properties": {
    "RoleDefinitionId": "/subscriptions/{subscriptionId}/providers/Microsoft.Authorization/roleDefinitions/{roleDefinitionId}",
    "PrincipalId": "{principalId}",
    "RequestType": "AdminRemove"
    }
}

Dalam URI, ganti {scope} dengan cakupan untuk penetapan peran.

Cakupan	Jenis
`providers/Microsoft.Management/managementGroups/{mg-name}`	Grup Manajemen
`subscriptions/{subscriptionId}`	Langganan
`subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1`	Grup sumber daya
`subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1/ providers/Microsoft.Web/sites/mysite1`	Sumber daya

Ganti {roleAssignmentScheduleRequestName} dengan pengidentifikasi GUID penetapan peran.

Mengaktifkan penetapan peran yang memenuhi syarat

Untuk mengaktifkan penetapan peran yang memenuhi syarat (mendapatkan akses yang diaktifkan), gunakan Permintaan Jadwal Penetapan Peran - Buat REST API untuk membuat permintaan baru dan tentukan prinsip keamanan, definisi peran, requestType = SelfActivate dan cakupan. Untuk memanggil API ini, Anda harus memiliki penetapan peran yang memenuhi syarat pada cakupan.

Gunakan alat GUID untuk menghasilkan pengidentifikasi unik yang akan digunakan untuk pengidentifikasi penetapan peran. Pengidentifikasi memiliki format: 00000000-0000-0000-0000-000000000000
[Opsional] RoleEligibilitySchedule Pilih yang ingin Anda aktifkan dan dapatkan RoleEligibilityScheduleId dari API Jadwal Kelayakan Peran untuk diteruskan LinkedRoleEligibilityScheduleIdsebagai . Ini opsional, dan jika tidak lulus, sistem akan memilih RoleEligibilitySchedule.

Mulai dengan permintaan berikut:

PUT https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleAssignmentScheduleRequests/{roleAssignmentScheduleRequestName}?api-version=2020-10-01

 {
   "Properties": {
     "RoleDefinitionId": "/subscriptions/{subscriptionId}/providers/Microsoft.Authorization/roleDefinitions/{roleDefinitionId}",
     "PrincipalId": "{principalId}",
     "RequestType": "SelfActivate",
     "ScheduleInfo": {
       "StartDateTime": "2020-09-09T21:31:27.91Z",
       "Expiration": {
         "Type": "AfterDuration", // Values: AfterDuration, AfterDateTime, NoExpiration
         "EndDateTime": null,
         "Duration": "PT8H" // Use ISO 8601 format
       }
     },
     "LinkedRoleEligibilityScheduleId": "/subscriptions/{subscriptionId}/providers/Microsoft.Authorization/roleAssignmentSchedules/{roleAssignmentScheduleId}" //Optional
   }
 }

Dalam URI, ganti {scope} dengan cakupan untuk penetapan peran.

Cakupan	Jenis
`providers/Microsoft.Management/managementGroups/{mg-name}`	Grup Manajemen
`subscriptions/{subscriptionId}`	Langganan
`subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1`	Grup sumber daya
`subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1/ providers/Microsoft.Web/sites/mysite1`	Sumber daya

Ganti {roleAssignmentScheduleRequestName} dengan pengidentifikasi GUID penetapan peran.

Menonaktifkan penetapan peran aktif

Untuk membatalkan aktifkan penetapan peran yang diaktifkan (hapus akses yang diaktifkan), gunakan Permintaan Jadwal Penetapan Peran - Buat REST API untuk membuat permintaan baru dan tentukan prinsip keamanan, definisi peran, requestType = SelfDeactivate dan cakupan. Untuk memanggil API ini, Anda harus memiliki penetapan peran yang diaktifkan pada cakupan.

Gunakan alat GUID untuk menghasilkan pengidentifikasi unik yang akan digunakan untuk pengidentifikasi penetapan peran. Pengidentifikasi memiliki format: 00000000-0000-0000-0000-000000000000

Mulai dengan permintaan berikut:

PUT https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleAssignmentScheduleRequests/{roleAssignmentScheduleRequestName}?api-version=2020-10-01

 {
   "Properties": {
     "RoleDefinitionId": "/subscriptions/{subscriptionId}/providers/Microsoft.Authorization/roleDefinitions/{roleDefinitionId}",
     "PrincipalId": "{principalId}",
     "RequestType": "SelfDeactivate"        
   }
 }

Dalam URI, ganti {scope} dengan cakupan untuk penetapan peran.

Cakupan	Jenis
`providers/Microsoft.Management/managementGroups/{mg-name}`	Grup Manajemen
`subscriptions/{subscriptionId}`	Langganan
`subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1`	Grup sumber daya
`subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1/ providers/Microsoft.Web/sites/mysite1`	Sumber daya

Ganti {roleAssignmentScheduleRequestName} dengan pengidentifikasi GUID penetapan peran.

Just-Enough-Access (JEA)

Jika pengguna memiliki penetapan peran yang memenuhi syarat di sumber daya (induk), mereka dapat memilih untuk mengaktifkan peran pada cakupan tingkat anak sumber daya induk alih-alih seluruh cakupan induk. Misalnya, jika pengguna memiliki Contributor peran yang memenuhi syarat di langganan, mereka dapat mengaktifkan peran di tingkat grup sumber daya anak langganan.

Untuk mendapatkan daftar semua anak dari sumber daya tempat Anda memiliki akses yang memenuhi syarat, Anda dapat menggunakan API Sumber Daya Anak yang Memenuhi Syarat .

Mulai dengan permintaan berikut:

GET https://management.azure.com/{scope}/providers/Microsoft.Authorization/eligibleChildResources?api-version=2020-10-01&$filter={filter}

Di dalam URI, ganti {scope} dengan cakupan yang ingin Anda cantumkan penetapan perannya.

Cakupan	Jenis
`providers/Microsoft.Management/managementGroups/{mg-name}`	Grup Manajemen
`subscriptions/{subscriptionId}`	Langganan
`subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1`	Grup sumber daya

Ganti {filter} dengan kondisi yang ingin Anda terapkan untuk memfilter daftar penetapan peran.

Filter	Deskripsi
`$filter=resourceType+eq+'Subscription'`	Cantumkan sumber daya jenis = 'Langganan'.
`$filter=$filter=resourceType+eq+'subscription'+or+resourceType+eq+'resourcegroup''`	Cantumkan sumber daya jenis = 'Langganan' atau jenis = 'ResourceGroup'.

id Gunakan sumber daya anak apa pun untuk digunakan sebagai scope untuk aktivasiRoleAssignmentScheduleRequest

Kesalahan umum yang dikembalikan untuk permintaan baru

Berikut ini adalah daftar kesalahan umum yang mungkin Anda temui saat membuat permintaan baru dan cara menguranginya.

Pesan kesalahan	Penjelasan	Mitigasi
`code`: RoleAssignmentExists `message`: Penetapan Peran sudah ada.	Penetapan peran serupa sudah ada	Anda dapat `GET` menetapkan peran ini dan memverifikasi jadwalnya.
`code`: RoleAssignmentRequestPolicyValidationFailed `message`: Aturan kebijakan berikut gagal: ["ExpirationRule"]	yang `ScheduleInfo` ditentukan dalam permintaan melebihi durasi maksimum yang diizinkan	Anda dapat `GET`roleManagementPolicy untuk ini `RoleDefinitionId` dan memeriksa `RoleManagementPolicyExpirationRule`
`code`: RoleAssignmentRequestPolicyValidationFailed `message`: Aturan kebijakan berikut gagal: ["JustificationRule"]	Anda perlu menentukan `Justification` dalam isi permintaan	Anda dapat `GET`roleManagementPolicy untuk ini `RoleDefinitionId` dan memeriksa `RoleManagementPolicyEnablementRule`
`code`: RoleAssignmentRequestPolicyValidationFailed `message`: Aturan kebijakan berikut gagal: ["EligibilityRule"]	`RoleEligibilityScheduleInstance` Valid tidak ada untuk mengaktifkan peran ini	Admin sumber daya perlu membuat `RoleEligibilityScheduleRequest` untuk prinsipal ini
`code`: RoleAssignmentRequestPolicyValidationFailed `message`: Aturan kebijakan berikut gagal: ["TicketingRule"]	Anda perlu menentukan `TicketInfo` dalam isi permintaan	Anda dapat `GET`roleManagementPolicy untuk ini `RoleDefinitionId` dan memeriksa `RoleManagementPolicyEnablementRule`
`code`: RoleAssignmentRequestPolicyValidationFailed `message`: Aturan kebijakan berikut gagal: ["MfaRule"]	Anda perlu menyelesaikan Azure Multi-Factor Authentication untuk mengirimkan permintaan ini	Anda dapat `GET`roleManagementPolicy untuk ini `RoleDefinitionId` dan memeriksa `RoleManagementPolicyEnablementRule`

Menggunakan Azure PIM untuk mengelola akses aktif dengan REST API

Mencantumkan penugasan aktif

Memberikan penugasan aktif

Menghapus penetapan aktif

Mengaktifkan penetapan peran yang memenuhi syarat

Menonaktifkan penetapan peran aktif

Just-Enough-Access (JEA)

Kesalahan umum yang dikembalikan untuk permintaan baru

Sumber Daya Tambahan: