Bagikan melalui

Persetujuan admin pada platform identitas Microsoft

  • Artikel

Beberapa izin memerlukan persetujuan dari administrator sebelum dapat diberikan dalam penyewa. Anda juga dapat menggunakan titik akhir persetujuan admin untuk memberikan izin kepada seluruh penyewa.

Biasanya, saat Anda membuat aplikasi yang menggunakan titik akhir persetujuan admin, aplikasi memerlukan halaman atau tampilan di mana admin dapat menyetujui izin aplikasi. Halaman ini dapat menjadi bagian dari alur pendaftaran aplikasi, bagian dari pengaturan aplikasi, atau dapat menjadi alur "connect" khusus. Dalam banyak kasus, dapat dimengerti jika aplikasi menampilkan tampilan "terhubung" ini hanya setelah pengguna masuk dengan akun Microsoft kantor atau sekolah.

Saat membuat pengguna masuk ke aplikasi, Anda dapat mengidentifikasi organisasi tempat admin berada sebelum meminta mereka menyetujui izin yang diperlukan. Meskipun tidak terlalu diperlukan, ini dapat membantu Anda menciptakan pengalaman yang lebih intuitif bagi pengguna organisasi Anda.

Meminta izin dari admin direktori

Saat Anda siap untuk meminta izin dari admin organisasi, Anda dapat mengalihkan pengguna ke titik akhir persetujuan admin platform identitas Microsoft.

https://login.microsoftonline.com/{tenant}/v2.0/adminconsent
        ?client_id=00001111-aaaa-2222-bbbb-3333cccc4444
        &scope=https://graph.microsoft.com/Calendars.Read https://graph.microsoft.com/Mail.Send
        &redirect_uri=http://localhost/myapp/permissions
        &state=12345
Parameter Kondisi Deskripsi
tenant Wajib diisi Penyewa direktori yang ingin dimintai izinnya. Dapat disediakan dalam GUID atau format nama yang ramah ATAU direferensikan secara umum dengan organizations seperti yang terlihat dalam contoh. Jangan gunakan 'common', karena akun pribadi tidak dapat memberikan persetujuan admin kecuali dalam konteks penyewa. Untuk memastikan kompatibilitas terbaik dengan akun pribadi yang mengelola penyewa, gunakan ID penyewa jika memungkinkan.
client_id Wajib ID Aplikasi (klien) yang ditetapkan pusat admin Microsoft Entra – pengalaman Pendaftaran aplikasi ke aplikasi Anda.
redirect_uri Wajib URI pengalihan tempat Anda ingin respons dikirim untuk ditangani aplikasi Anda. URI pengalihan ini harus sama persis dengan salah satu URI pengalihan yang Anda daftarkan di portal pendaftaran aplikasi.
state Disarankan Nilai yang disertakan dalam permintaan yang juga akan dikembalikan dalam respons token. Ini bisa berupa string dari konten apa pun yang Anda inginkan. Gunakan status ini untuk mengkodekan informasi tentang status pengguna di aplikasi sebelum permintaan autentikasi muncul, seperti halaman atau tampilan tempat mereka berada.
scope Wajib Menentukan sekumpulan izin yang diminta oleh aplikasi. Ini dapat berupa cakupan statik (menggunakan /.default) atau dinamis. Ini dapat meliputi cakupan OIDC (openid, profile, email).

Pada titik ini, MICROSOFT Entra ID mengharuskan administrator penyewa untuk masuk untuk menyelesaikan permintaan. Administrator diminta untuk menyetujui semua izin yang Anda minta dalam parameter scope. Jika Anda telah menggunakan nilai (/.default) statik, nilai tersebut akan berfungsi seperti titik akhir persetujuan admin v1.0 dan meminta persetujuan untuk semua cakupan yang ditemukan dalam izin yang diperlukan (baik pengguna maupun aplikasi). Untuk meminta izin aplikasi, Anda harus menggunakan nilai /.default. Jika Anda tidak menginginakn admin melihat izin yang diberikan di layar persetujuan admin pada saat Anda menggunakan /.default, praktik terbaiknya adalah tidak memasukkan izin di bagian izin yang diperlukan. Sebagai gantinya, Anda dapat menggunakan persetujuan dinamis untuk menambahkan izin yang ingin Anda munculkan di layar persetujuan pada waktu proses, alih-alih menggunakan /.default.

Respons berhasil

Jika admin menyetujui izin untuk aplikasi Anda, respons yang berhasil akan terlihat seperti ini:

http://localhost/myapp/permissions
    ?admin_consent=True
    &tenant=aaaabbbb-0000-cccc-1111-dddd2222eeee
    &scope=https://graph.microsoft.com/Calendars.Read https://graph.microsoft.com/Mail.Send
    &state=12345
Parameter Deskripsi
tenant Penyewa direktori yang memberi izin yang diminta aplikasi Anda, dalam format GUID.
state Nilai yang disertakan dalam permintaan juga akan dikembalikan dalam respons token. Ini bisa berupa string dari konten apa pun yang Anda inginkan. Status ini digunakan untuk mengkodekan informasi tentang status pengguna di aplikasi sebelum permintaan autentikasi muncul, seperti halaman atau tampilan tempat mereka berada.
scope Kumpulan izin yang diberikan akses untuk aplikasi.
admin_consent Akan diatur ke True.

Peringatan

Jangan pernah menggunakan nilai tenant ID penyewa parameter untuk mengautentikasi atau mengotorisasi pengguna. Nilai ID penyewa dapat diperbarui dan dikirim oleh pelaku jahat untuk meniru respons terhadap aplikasi Anda. Hal ini dapat menyebabkan aplikasi Anda terpapar insiden keamanan.

Respons kesalahan

http://localhost/myapp/permissions
        ?admin_consent=True
        &error=consent_required
        &error_description=AADSTS65004%3a+The+resource+owner+or+authorization+server+denied+the+request.%0d%0aTrace+ID%3a+0000aaaa-11bb-cccc-dd22-eeeeee333333%0d%0aCorrelation+ID%3a+8478d534-5b2c-4325-8c2c-51395c342c89%0d%0aTimestamp%3a+2019-09-24+18%3a34%3a26Z
        &state=12345

Menambahkan parameter terlihat dalam respons yang berhasil, parameter kesalahan terlihat seperti di bawah ini.

Parameter Deskripsi
error String kode kesalahan yang dapat digunakan untuk mengklasifikasikan jenis kesalahan yang terjadi, dan dapat digunakan untuk bereaksi terhadap kesalahan.
error_description Pesan kesalahan khusus yang dapat membantu Anda mengidentifikasi penyebab kesalahan autentikasi.
state Nilai yang disertakan dalam permintaan juga akan dikembalikan dalam respons token. Ini bisa berupa string dari konten apa pun yang Anda inginkan. Status ini digunakan untuk mengkodekan informasi tentang status pengguna di aplikasi sebelum permintaan autentikasi muncul, seperti halaman atau tampilan tempat mereka berada.
admin_consent Akan diatur ke True menunjukkan bahwa respons ini terjadi pada alur persetujuan admin.

Langkah berikutnya