Bagikan melalui

Panduan pengembang untuk meminta izin dan persetujuan di Microsoft Identity Platform

Aplikasi di platform identitas Microsoft mengandalkan persetujuan untuk mendapatkan akses ke sumber daya atau API yang diperlukan. Berbagai jenis persetujuan lebih baik untuk skenario aplikasi yang berbeda. Memilih pendekatan terbaik untuk menyetujui aplikasi Anda memungkinkannya menjadi lebih sukses dengan pengguna dan organisasi.

Dalam artikel ini, Anda mempelajari tentang berbagai jenis persetujuan dan cara meminta izin untuk aplikasi Anda melalui persetujuan.

Nota

Untuk aplikasi di penyewa eksternal, pelanggan tidak dapat menyetujui izin itu sendiri. Administrator perlu memberikan persetujuan bagi aplikasi untuk mengakses sumber daya atas nama mereka. Untuk informasi selengkapnya, lihat Memberikan persetujuan admin.

Dalam skenario persetujuan pengguna statis, Anda harus menentukan semua izin yang dibutuhkan dalam konfigurasi aplikasi di pusat admin Microsoft Entra. Jika pengguna (atau administrator, sebagaimana mestinya) tidak memberikan persetujuan untuk aplikasi ini, platform identitas Microsoft meminta pengguna untuk memberikan persetujuan saat ini.

Izin statis juga memungkinkan administrator untuk menyetujui atas nama semua pengguna di organisasi.

Meskipun mengandalkan persetujuan statis dan daftar izin tunggal menjaga kode tetap bagus dan sederhana, itu juga berarti bahwa aplikasi Anda meminta semua izin yang mungkin pernah diperlukan di muka. Pengaturan ini dapat mencegah pengguna dan admin menyetujui permintaan akses aplikasi Anda.

Dengan titik akhir platform identitas Microsoft, Anda dapat mengabaikan izin statis yang ditentukan dalam informasi pendaftaran aplikasi di pusat admin Microsoft Entra. Sebagai gantinya, Anda dapat meminta izin secara dinamis, dari kode aplikasi. Anda dapat memulai dengan meminta serangkaian izin minimum di muka dan meminta izin lainnya seiring pelanggan menggunakan lebih banyak fitur aplikasi. Untuk melakukannya, Anda dapat menentukan cakupan yang dibutuhkan aplikasi Anda kapan saja dengan menyertakan cakupan dalam scope parameter saat meminta token akses - tanpa perlu menentukannya dalam informasi pendaftaran aplikasi.

Jika pengguna belum menyetujui salah satu cakupan dalam permintaan, mereka mendapatkan permintaan untuk menyetujui semua izin dalam permintaan tersebut. Izin ini akan ditambahkan ke izin lain yang sudah diberikan untuk aplikasi tersebut (yaitu inkremental). Persetujuan inkremental, hanya berlaku untuk izin yang didelegasikan dan bukan untuk izin aplikasi.

Mengizinkan aplikasi meminta izin secara dinamis melalui scope parameter memberi pengembang kontrol penuh atas pengalaman pengguna Anda. Anda memuat pengalaman persetujuan Anda lebih awal dan meminta semua izin dalam satu permintaan otorisasi awal. Jika aplikasi Anda memerlukan sejumlah besar izin, Anda dapat mengumpulkan izin tersebut dari pengguna secara bertahap saat mereka mencoba menggunakan fitur tertentu dari aplikasi dari waktu ke waktu.

Penting

Persetujuan dinamis bisa nyaman, tetapi memberikan tantangan signifikan untuk izin yang memerlukan persetujuan admin. Pengalaman pemberian persetujuan admin di bilah Pendaftaran aplikasi dan Aplikasi Perusahaan di portal tidak tahu tentang izin dinamis tersebut pada waktu persetujuan. Sebaiknya pengembang mencantumkan semua izin istimewa admin yang dibutuhkan aplikasi di portal.

Ini memungkinkan admin penyewa untuk menyetujui atas nama semua pengguna mereka di portal sekali. Pengguna tidak perlu melalui pengalaman persetujuan untuk izin tersebut saat masuk. Alternatifnya adalah menggunakan persetujuan dinamis untuk izin tersebut. Untuk memberikan persetujuan admin, admin individu masuk ke aplikasi, memicu permintaan persetujuan untuk izin yang sesuai, dan memilih persetujuan untuk seluruh organisasi saya dalam dialog persetujuan.

Dalam permintaan otorisasi OpenID Connect atau OAuth 2.0 , aplikasi dapat meminta izin yang dibutuhkan dengan menggunakan scope parameter kueri. Misalnya, saat pengguna masuk ke aplikasi, aplikasi mengirimkan permintaan seperti contoh berikut. (Hentian baris ditambahkan untuk legibilitas).

GET https://login.microsoftonline.com/common/oauth2/v2.0/authorize?
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&response_type=code
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&response_mode=query
&scope=
https%3A%2F%2Fgraph.microsoft.com%2Fcalendars.read%20
https%3A%2F%2Fgraph.microsoft.com%2Fmail.send
&state=12345

Parameter scope adalah daftar izin yang didelegasikan yang dipisahkan spasi yang diminta aplikasi. Setiap izin ditunjukkan dengan menambahkan nilai izin ke pengidentifikasi sumber daya (ID aplikasi URI). Dalam contoh permintaan, aplikasi memerlukan izin untuk membaca kalender pengguna dan mengirim email sebagai pengguna.

Setelah masuk, platform identitas Microsoft memeriksa persetujuan pengguna yang ada. Jika pengguna tidak menyetujui izin yang diminta dan administrator juga tidak menyetujuinya, platform akan meminta pengguna untuk memberikan persetujuan.

Dalam contoh berikut, izin offline_access ("Mempertahankan akses ke data yang telah Anda izinkan aksesnya") dan izin User.Read ("Masuk ke akun Anda dan baca profil Anda") secara otomatis disertakan dalam persetujuan awal terhadap aplikasi. Izin ini diperlukan untuk fungsionalitas aplikasi yang tepat.

Izin ini offline_access memberi aplikasi akses ke token refresh yang penting untuk aplikasi asli dan aplikasi web. Izin User.Read memberikan akses ke sub klaim. Ini memungkinkan klien atau aplikasi untuk mengidentifikasi pengguna dengan benar dari waktu ke waktu dan mengakses informasi dasar pengguna.

Contoh cuplikan layar yang memperlihatkan persetujuan akun kerja.

Saat pengguna menyetujui permintaan izin, persetujuan akan direkam. Pengguna tidak perlu menyetujui lagi ketika mereka kemudian masuk ke aplikasi.

Meminta persetujuan untuk seluruh penyewa memerlukan persetujuan admin. Persetujuan admin yang dilakukan atas nama organisasi memerlukan izin statis yang terdaftar untuk aplikasi. Atur izin tersebut di portal pendaftaran aplikasi jika Anda memerlukan admin untuk memberikan persetujuan atas nama seluruh organisasi.

Saat aplikasi Anda meminta izin yang didelegasikan yang memerlukan persetujuan admin, pengguna melihat kesalahan "tidak sah untuk menyetujui" dan perlu meminta akses kepada administrator. Setelah admin memberikan persetujuan untuk seluruh penyewa, pengguna tidak diminta lagi kecuali persetujuan dicabut atau izin baru ditambahkan.

Administrator yang menggunakan aplikasi yang sama melihat permintaan persetujuan admin. Perintah persetujuan admin menyediakan kotak centang yang memungkinkan mereka memberikan akses aplikasi ke data yang diminta atas nama pengguna untuk seluruh penyewa. Untuk informasi selengkapnya tentang pengalaman persetujuan pengguna dan admin, lihat Pengalaman persetujuan aplikasi.

Contoh izin yang didelegasikan untuk Microsoft Graph yang memerlukan persetujuan admin adalah:

  • Membaca profil lengkap semua pengguna menggunakan User.Read.All
  • Menulis data ke direktori organisasi menggunakan Directory.ReadWrite.All
  • Membaca data di direktori organisasi menggunakan Groups.Read.All

Untuk melihat daftar lengkap izin Microsoft Graph, lihat Referensi izin Microsoft Graph.

Anda juga dapat mengonfigurasi izin pada sumber daya Anda sendiri untuk memerlukan persetujuan admin. Untuk informasi selengkapnya tentang cara menambahkan cakupan yang memerlukan persetujuan admin, lihat Menambahkan cakupan yang memerlukan persetujuan admin.

Beberapa organisasi mungkin mengubah kebijakan persetujuan pengguna default untuk penyewa. Saat aplikasi Anda meminta akses ke izin, aplikasi tersebut dievaluasi terhadap kebijakan ini. Pengguna mungkin perlu meminta persetujuan admin bahkan ketika tidak diperlukan secara default. Untuk mempelajari cara administrator mengelola kebijakan persetujuan untuk aplikasi, lihat Mengelola kebijakan persetujuan aplikasi.

Nota

Dalam platform identitas Microsoft, pada permintaan otorisasi, token, atau persetujuan, jika pengidentifikasi sumber daya di parameter scope dihilangkan, maka akan secara default mengacu pada Microsoft Graph. Misalnya, scope=User.Read diperlakukan sebagai https://graph.microsoft.com/User.Read.

Izin aplikasi selalu memerlukan persetujuan admin. Izin aplikasi tidak memiliki konteks pengguna dan pemberian persetujuan tidak dilakukan atas nama pengguna tertentu. Sebaliknya, aplikasi klien diberikan izin secara langsung. Jenis izin ini hanya digunakan oleh layanan daemon dan aplikasi non-interaktif lainnya yang berjalan di latar belakang. Administrator perlu mengonfigurasi izin di muka dan memberikan persetujuan admin melalui pusat admin Microsoft Entra.

Jika aplikasi yang meminta izin adalah aplikasi multipenyewa, pendaftaran aplikasinya hanya ada di penyewa tempat aplikasi dibuat, oleh karena itu izin tidak dapat dikonfigurasi di penyewa lokal. Jika aplikasi meminta izin yang memerlukan persetujuan admin, administrator perlu menyetujui atas nama pengguna. Untuk menyetujui izin ini, administrator perlu masuk ke aplikasi itu sendiri, sehingga pengalaman masuk persetujuan admin dipicu. Untuk mempelajari cara menyiapkan proses persetujuan admin untuk aplikasi multipenyewa, lihat Mengaktifkan login multipenyewa

Administrator dapat memberikan persetujuan untuk aplikasi dengan opsi berikut.

Biasanya, saat Anda membuat aplikasi yang memerlukan persetujuan admin, aplikasi memerlukan halaman atau tampilan di mana admin dapat menyetujui izin aplikasi. Halaman ini dapat berupa:

  • Bagian dari alur pendaftaran aplikasi.
  • Bagian dari pengaturan aplikasi.
  • Alur "sambungkan" khusus.

Dalam banyak kasus, masuk akal bagi aplikasi untuk menampilkan tampilan "sambungkan" hanya setelah pengguna masuk dengan akun Microsoft kantor atau akun Microsoft sekolah.

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

Untuk memasukkan pengguna, ikuti tutorial protokol platform identitas Microsoft .

Meminta izin di portal pendaftaran aplikasi

Di portal pendaftaran aplikasi, aplikasi dapat mencantumkan izin yang mereka butuhkan, termasuk izin yang didelegasikan dan izin aplikasi. Penyiapan ini memungkinkan penggunaan cakupan .default dan opsi Berikan persetujuan admin di pusat admin Microsoft Entra.

Secara umum, izin harus ditentukan secara statis untuk aplikasi tertentu. Mereka harus menjadi superset dari izin yang diminta aplikasi secara dinamis atau bertahap.

Nota

Izin aplikasi hanya dapat diminta dengan menggunakan .default. Jadi, jika aplikasi Anda memerlukan izin aplikasi, pastikan aplikasi tersebut tercantum di portal pendaftaran aplikasi.

Untuk mengonfigurasi daftar izin yang diminta secara statis untuk aplikasi:

  1. Masuk ke pusat admin Microsoft Entra sebagai setidaknya Administrator Aplikasi Cloud.
  2. Telusuri pendaftaranAplikasi>Entra ID>Semua aplikasi.
  3. Pilih aplikasi, atau buat aplikasi jika Anda belum melakukannya.
  4. Pada halaman Gambaran Umum aplikasi, di bawah Kelola, pilih Izin> APITambahkan izin.
  5. Pilih Microsoft Graph dari daftar API yang tersedia. Kemudian tambahkan izin yang diperlukan aplikasi Anda.
  6. Pilih Tambahkan Izin.

Respons berhasil

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

GET http://localhost/myapp/permissions?tenant=aaaabbbb-0000-cccc-1111-dddd2222eeee&state=state=12345&admin_consent=True
Pengaturan Deskripsi
tenant Penyewa direktori yang memberi aplikasi Anda izin yang dimintanya, dalam format GUID.
state Nilai yang disertakan dalam permintaan yang dikembalikan dalam respons token. Ini bisa berupa string dari konten apa pun yang Anda inginkan. Status digunakan untuk mengodekan informasi tentang status pengguna dalam aplikasi sebelum permintaan autentikasi terjadi, seperti halaman atau tampilan tempat mereka berada.
admin_consent Diatur ke True.

Setelah Anda menerima respons yang berhasil dari titik akhir persetujuan admin, aplikasi Anda diberikan izin yang dimintanya. Selanjutnya, Anda dapat meminta token untuk sumber daya yang Anda inginkan.

Tanggapan kesalahan

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

GET http://localhost/myapp/permissions?error=permission_denied&error_description=The+admin+canceled+the+request
Pengaturan Deskripsi
error String kode kesalahan yang dapat digunakan untuk mengklasifikasikan jenis kesalahan yang terjadi. Ini juga dapat digunakan untuk bereaksi terhadap kesalahan.
error_description Pesan kesalahan tertentu yang dapat membantu pengembang mengidentifikasi akar penyebab kesalahan.

Setelah pengguna menyetujui izin untuk aplikasi Anda, aplikasi Anda dapat memperoleh token akses yang mewakili izin aplikasi untuk mengakses sumber daya dalam beberapa kapasitas. Token akses hanya dapat digunakan untuk satu sumber daya. Tetapi dikodekan di dalam token akses adalah setiap izin yang diberikan aplikasi Anda untuk sumber daya tersebut. Untuk memperoleh token akses, aplikasi Anda dapat membuat permintaan ke titik akhir token platform identitas Microsoft, seperti ini:

POST common/oauth2/v2.0/token HTTP/1.1
Host: https://login.microsoftonline.com
Content-Type: application/json

{
    "grant_type": "authorization_code",
    "client_id": "00001111-aaaa-2222-bbbb-3333cccc4444",
    "scope": "https://microsoft.graph.com/Mail.Read https://microsoft.graph.com/mail.send",
    "code": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...",
    "redirect_uri": "https://localhost/myapp",
    "client_secret": "A1bC2dE3f..."  // NOTE: Only required for web apps
}

Anda dapat menggunakan token akses yang dihasilkan dalam permintaan HTTP ke sumber daya. Ini dengan andal menunjukkan kepada sumber daya bahwa aplikasi Anda memiliki izin yang tepat untuk melakukan tugas tertentu.

Untuk informasi selengkapnya tentang protokol OAuth 2.0 dan cara mendapatkan token akses, lihat referensi protokol titik akhir platform identitas Microsoft.

Konten terkait

  • Last updated on