Meminta izin melalui persetujuan

  • Artikel

Aplikasi dalam 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 akan membantunya menjadi lebih sukses dengan pengguna dan organisasi.

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

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) belum memberikan persetujuan untuk aplikasi ini, maka platform identitas Microsoft akan 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 akan meminta semua izin yang mungkin diperlukan di muka. 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 bertahap. Anda dapat meminta serangkaian izin minimum di muka dan meminta lebih banyak dari waktu ke waktu karena pelanggan menggunakan fitur aplikasi tambahan. Untuk melakukannya, Anda dapat menentukan cakupan yang dibutuhkan aplikasi Anda kapan saja dengan menyertakan cakupan baru dalam scope parameter saat meminta token akses - tanpa perlu menentukannya sebelumnya dalam informasi pendaftaran aplikasi. Jika pengguna belum menyetujui cakupan baru yang ditambahkan ke permintaan, mereka akan diminta untuk hanya menyetujui izin baru. Persetujuan bertahap, atau dinamis, 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 juga dapat memuat pengalaman persetujuan Anda di depan 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 dapat memberi kenyamanan, tetapi menghadirkan tantangan besar untuk izin yang memerlukan persetujuan admin. Pengalaman persetujuan admin di panel Pendaftaran aplikasi dan Aplikasi enterprise di portal tidak mengetahui tentang izin dinamis tersebut pada waktu persetujuan. Sebaiknya pengembang mencantumkan semua izin istimewa admin yang diperlukan oleh aplikasi di portal. Hal ini memungkinkan admin penyewa untuk menyetujui atas nama semua pengguna mereka di portal, satu kali. Pengguna tidak perlu melalui pengalaman persetujuan untuk izin tersebut saat masuk. Alternatifnya adalah menggunakan persetujuan dinamis untuk izin tersebut. Untuk memberikan persetujuan kepada admin, masing-masing admin masuk ke aplikasi, memicu permintaan persetujuan untuk izin yang sesuai, dan memilih persetujuan untuk seluruh organisasi saya dalam dialog persetujuan.

Dalam permintaan otorisasi OpenID Koneksi 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 pengguna memasukkan kredensial mereka, platform identitas Microsoft memeriksa catatan persetujuan pengguna yang cocok. Jika pengguna belum menyetujui salah satu izin yang diminta di masa lalu, dan jika administrator belum menyetujui izin ini atas nama seluruh organisasi, platform identitas Microsoft meminta pengguna untuk memberikan izin yang diminta.

Dalam contoh berikut, offline_access izin ("Pertahankan akses ke data yang telah Anda berikan aksesnya") dan User.Read ("Masuk dan baca profil Anda") secara otomatis disertakan dalam persetujuan awal untuk 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 klaim sub. Ini memungkinkan klien atau aplikasi untuk mengidentifikasi pengguna dengan benar dari waktu ke waktu dan mengakses informasi pengguna yang belum diketahui.

Contoh cuplikan layar yang memperlihatkan persetujuan akun kerja.

Saat pengguna menyetujui permintaan izin, persetujuan akan direkam. Pengguna tidak harus 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 menerima pesan kesalahan yang mengatakan bahwa mereka tidak sah untuk menyetujui izin aplikasi Anda. Pengguna diharuskan meminta akses ke aplikasi kepada admin mereka. Jika admin memberikan persetujuan untuk seluruh penyewa, pengguna organisasi tidak melihat halaman persetujuan untuk aplikasi kecuali izin yang diberikan sebelumnya dicabut atau aplikasi meminta izin baru secara bertahap.

Administrator yang menggunakan aplikasi yang sama akan 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 dapat 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.

Catatan

Dalam permintaan ke titik akhir otorisasi, token, atau persetujuan untuk platform identitas Microsoft, jika pengidentifikasi sumber daya dihilangkan dalam parameter cakupan, sumber daya diasumsikan sebagai Microsoft Graph. Misalnya, scope=User.Read setara dengan 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 multi-penyewa, 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 pengalaman persetujuan admin untuk aplikasi multi-penyewa, lihat Mengaktifkan masuk multi-penyewa

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 bisa:

  • Bagian dari alur pendaftaran aplikasi.
  • Bagian dari pengaturan aplikasi.
  • Aliran "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 tidak terlalu diperlukan, 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 .default cakupan dan opsi Izinkan admin pusat admin Microsoft Entra.

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

Catatan

Izin aplikasi hanya dapat diminta melalui penggunaan .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 aplikasi >Identitas>Pendaftaran aplikasi> Semua aplikasi.
  3. Pilih aplikasi, atau buat aplikasi jika Anda belum melakukannya.
  4. Pada halaman Gambaran Umum aplikasi, di bawah Kelola, pilih Izin API>Tambahkan 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 akan terlihat seperti ini:

GET http://localhost/myapp/permissions?tenant=aaaabbbb-0000-cccc-1111-dddd2222eeee&state=state=12345&admin_consent=True
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 digunakan untuk mengodekan informasi tentang status pengguna dalam aplikasi sebelum permintaan autentikasi terjadi, seperti halaman atau tampilan tempat mereka berada.
admin_consent Akan diatur ke True.

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

Respons kesalahan

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

GET http://localhost/myapp/permissions?error=permission_denied&error_description=The+admin+canceled+the+request
Parameter 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 khusus yang dapat membantu Anda mengidentifikasi penyebab kesalahan autentikasi.

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 telah 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 endpoint platform identitas Microsoft.

Lihat juga