Cakupan dan izin dalam platform identitas Microsoft

  • Artikel

Platform identitas Microsoft menerapkan protokol otorisasi OAuth 2.0. OAuth 2.0 adalah metode di mana aplikasi pihak ketiga dapat mengakses sumber daya yang dihosting web atas nama pengguna. Setiap sumber daya yang dihosting web yang terintegrasi dengan platform identitas Microsoft memiliki pengenal sumber daya, atau URI ID aplikasi.

Dalam artikel ini, Anda akan mempelajari cakupan dan izin di platform identitas.

Daftar berikut ini memperlihatkan beberapa contoh sumber daya yang dihosting web Microsoft:

  • Microsoft Graph: https://graph.microsoft.com
  • API Email Microsoft 365: https://outlook.office.com
  • Azure Key Vault: https://vault.azure.net

Hal yang sama berlaku untuk setiap sumber daya pihak ketiga yang telah terintegrasi dengan platform identitas Microsoft. Salah satu sumber daya ini juga dapat menentukan sekumpulan izin yang dapat digunakan untuk membagi fungsionalitas sumber daya tersebut menjadi gugus yang lebih kecil. Sebagai contoh, Microsoft Graph memiliki izin yang ditentukan untuk melakukan tugas berikut, antara lain:

  • Membaca kalender pengguna
  • Menulis ke kalender pengguna
  • Kirim email sebagai pengguna

Karena jenis definisi izin ini, sumber daya memiliki kontrol yang halus atas datanya dan bagaimana fungsi API diekspos. Aplikasi pihak ketiga dapat meminta izin ini dari pengguna dan administrator, yang harus menyetujui permintaan sebelum aplikasi dapat mengakses data atau bertindak atas nama pengguna.

Saat fungsionalitas sumber daya dipotong menjadi set izin kecil, aplikasi pihak ketiga hanya dapat dibuat untuk meminta izin yang mereka butuhkan untuk menjalankan fungsinya. Pengguna dan administrator dapat mengetahui data apa yang dapat diakses aplikasi. Dan mereka bisa lebih yakin bahwa aplikasi tidak berperilaku dengan niat jahat. Pengembang harus selalu mematuhi prinsip hak istimewa paling sedikit, hanya meminta izin yang mereka butuhkan agar aplikasi mereka berfungsi.

Di OAuth 2.0, jenis set izin ini disebut cakupan. Mereka juga sering disebut sebagai izin. Di platform identitas Microsoft, izin direpresentasikan sebagai nilai string. Aplikasi meminta izin yang diperlukan dengan menentukan izin dalam scope parameter kueri. Platform identitas mendukung beberapa cakupan Koneksi OpenID yang terdefinisi dengan baik dan izin berbasis sumber daya (setiap izin ditunjukkan dengan menambahkan nilai izin ke pengidentifikasi sumber daya atau URI ID aplikasi). Misalnya, string izin https://graph.microsoft.com/Calendars.Read digunakan untuk meminta izin untuk membaca kalender pengguna di Microsoft Graph.

Dalam permintaan ke server otorisasi, untuk platform identitas Microsoft, jika pengidentifikasi sumber daya dihilangkan dalam parameter cakupan, sumber daya diasumsikan sebagai Microsoft Graph. Misalnya, scope=User.Read sama dengan https://graph.microsoft.com/User.Read.

Izin yang dibatasi admin

Izin dalam platform identitas Microsoft dapat diatur ke admin dibatasi. Misalnya, banyak izin Microsoft Graph dengan hak istimewa yang lebih tinggi memerlukan persetujuan admin. Jika aplikasi Anda memerlukan izin yang dibatasi admin, administrator organisasi harus menyetujui cakupan tersebut atas nama pengguna organisasi. Bagian berikut memberikan contoh jenis izin ini:

  • User.Read.All: Membaca semua profil lengkap pengguna
  • Directory.ReadWrite.All: Menulis data ke direktori organisasi
  • Groups.Read.All: Membaca semua grup dalam direktori organisasi

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 sama dengan https://graph.microsoft.com/User.Read.

Meskipun pengguna konsumen mungkin memberikan akses aplikasi ke data semacam ini, pengguna organisasi tidak dapat memberikan akses ke kumpulan data perusahaan sensitif yang sama. Jika aplikasi Anda meminta akses ke salah satu izin ini dari pengguna organisasi, pengguna menerima pesan kesalahan yang mengatakan bahwa mereka tidak berwenang untuk menyetujui izin aplikasi Anda.

Jika aplikasi meminta izin aplikasi dan administrator memberikan izin ini, pemberian ini tidak dilakukan atas nama pengguna tertentu. Sebaliknya, aplikasi klien diberikan izin secara langsung. Jenis izin ini hanya boleh digunakan oleh layanan daemon dan aplikasi non-interaktif lainnya yang berjalan di latar belakang. Untuk informasi selengkapnya tentang skenario akses langsung, lihat Skenario akses di platform identitas Microsoft.

Untuk panduan langkah demi langkah tentang cara mengekspos cakupan di API web, lihat Mengonfigurasi aplikasi untuk mengekspos API web.

Cakupan OpenID Connect

Implementasi platform identitas Microsoft dari OpenID Connect memiliki beberapa cakupan yang terdefinisi dengan baik yang juga dihosting di Microsoft Graph: openid,email, profile, dan offline_access. Cakupan address dan phone OpenID Connect tidak didukung.

Jika Anda meminta cakupan OpenID Connect dan token, Anda akan mendapatkan token untuk menghubungi titik akhir UserInfo.

Cakupan openid

Jika aplikasi masuk dengan menggunakan OpenID Connect, aplikasi harus meminta cakupan openid. Lingkup openid muncul di halaman persetujuan akun kerja sebagai izin Masuk Anda.

Dengan menggunakan izin ini, aplikasi dapat menerima pengidentifikasi unik untuk pengguna dalam bentuk klaimsub. Izin ini juga memberi aplikasi akses ke titik akhir UserInfo. Ruang lingkup openid dapat digunakan di titik akhir token platform identitas Microsoft untuk memperoleh token ID. Aplikasi ini dapat menggunakan token ini untuk autentikasi.

Cakupan email

Ruang lingkup email dapat digunakan dengan ruang lingkup openid dan cakupan lainnya. Ini memberi aplikasi akses ke alamat email utama pengguna dalam bentuk klaim email.

Klaim email disertakan dalam token hanya jika alamat email dikaitkan dengan akun pengguna, yang tidak selalu terjadi. Jika aplikasi Anda menggunakan cakupan email, aplikasi harus dapat menangani kasus di mana tidak ada klaim email dalam token.

Cakupan profile

Ruang lingkup profile dapat digunakan dengan ruang lingkup openid dan cakupan lainnya. Ini memberi aplikasi akses ke sejumlah besar informasi tentang pengguna. Informasi yang dapat diakses mencakup, tetapi tidak terbatas pada, nama yang diberikan pengguna, nama keluarga, nama pengguna pilihan, dan ID objek.

Untuk daftar lengkap klaim profile yang tersedia dalam parameter id_tokens untuk pengguna tertentu, lihatid_tokens referensi.

Cakupan offline_access

Ruang lingkup offline_access memberi aplikasi Anda akses ke sumber daya atas nama pengguna untuk waktu yang lama. Pada halaman persetujuan, lingkup ini muncul sebagai Pertahankan akses ke data yang telah Anda berikan akses ke izin.

Saat pengguna menyetujui cakupan offline_access, aplikasi Anda dapat menerima token refresh dari titik akhir token platform identitas Microsoft. Token refresh berumur panjang. Aplikasi Anda bisa mendapatkan token akses baru saat token yang lebih lama kedaluwarsa.

Catatan

Izin ini saat ini muncul di semua halaman persetujuan, bahkan untuk alur yang tidak menyediakan token refresh (seperti aliran implisit). Pengaturan ini membahas skenario tempat klien dapat dimulai dalam aliran implisit dan kemudian pindah ke aliran kode tempat token refresh diharapkan.

Pada platform identitas Microsoft (permintaan yang dibuat ke titik akhir v2.0), aplikasi Anda harus secara eksplisit meminta cakupan offline_access, untuk menerima token refresh. Jadi, ketika Anda menukarkan kode otorisasi dalam alur kode otorisasi OAuth 2.0, Anda hanya akan menerima token akses dari /token titik akhir.

Token akses biasanya berlaku selama sekitar satu jam. Pada saat itu, aplikasi Anda perlu mengalihkan pengguna kembali ke /authorize titik akhir untuk meminta kode otorisasi baru. Selama pengalihan ini dan bergantung pada jenis aplikasi, pengguna mungkin perlu memasukkan kredensial mereka lagi atau menyetujui izin lagi.

Token refresh memiliki kedaluwarsa lebih lama daripada token akses, dan biasanya berlaku selama satu hari. Untuk informasi selengkapnya tentang cara mendapatkan dan menggunakan token refresh, lihat referensi protokol platform identitas Microsoft.

Cakupan .default

Cakupan .default digunakan untuk merujuk secara umum ke layanan sumber daya (API) dalam permintaan, tanpa mengidentifikasi izin khusus. Jika persetujuan diperlukan, menggunakan .default menandakan bahwa persetujuan harus diminta untuk semua izin yang diperlukan yang tercantum dalam pendaftaran aplikasi (untuk semua API dalam daftar).

Nilai parameter cakupan dibuat dengan menggunakan URI pengidentifikasi untuk sumber daya dan .default, dipisahkan oleh garis miring (/). Misalnya, jika URI pengidentifikasi sumber daya adalah https://contoso.com, cakupan yang diminta adalah https://contoso.com/.default. Untuk kasus saat Anda harus menyertakan garis miring kedua untuk meminta token dengan benar, lihat bagian tentang garis miring.

Menggunakan scope={resource-identifier}/.default secara fungsional sama dengan resource={resource-identifier} pada titik akhir v1.0 (dengan {resource-identifier} adalah URI pengenal untuk API, misalnya https://graph.microsoft.com untuk Microsoft Graph).

Cakupan .default dapat digunakan dalam alur OAuth 2.0 apa pun dan untuk memulai persetujuan admin. Penggunaannya diperlukan dalam alur Atas Nama dan alur kredensial klien.

Klien tidak dapat menggabungkan persetujuan statis (.default) dan persetujuan dinamis dalam satu permintaan. Jadi scope=https://graph.microsoft.com/.default Mail.Read menghasilkan kesalahan karena menggabungkan tipe lingkup.

Parameter .default cakupan hanya memicu permintaan persetujuan jika persetujuan belum diberikan untuk izin yang didelegasikan antara klien dan sumber daya, atas nama pengguna yang masuk.

Jika ada persetujuan, token yang dikembalikan berisi semua cakupan yang diberikan untuk sumber daya tersebut untuk pengguna yang masuk. Namun, jika tidak ada izin yang diberikan untuk sumber daya yang diminta (atau jika parameter prompt=consent telah diberikan), permintaan persetujuan akan ditampilkan untuk semua izin yang diperlukan yang dikonfigurasi pada pendaftaran aplikasi klien, untuk semua API dalam daftar.

Misalnya, jika cakupan https://graph.microsoft.com/.default diminta, aplikasi Anda meminta token akses untuk API Microsoft Graph. Jika setidaknya satu izin yang didelegasikan telah diberikan untuk Microsoft Graph atas nama pengguna yang masuk, rincian masuk akan dilanjutkan dan semua izin yang didelegasikan Microsoft Graph yang telah diberikan untuk pengguna tersebut akan disertakan dalam token akses. Jika tidak ada izin yang diberikan untuk sumber daya yang diminta (Microsoft Graph, dalam contoh ini), maka permintaan persetujuan akan diberikan untuk semua izin yang diperlukan yang dikonfigurasi pada aplikasi, untuk semua API dalam daftar.

Contoh 1: Pengguna, atau admin penyewa, telah memberikan izin

Dalam contoh ini, pengguna atau administrator penyewa telah memberikan izin Microsoft Graph Mail.Read dan User.Read kepada klien.

Jika klien meminta scope=https://graph.microsoft.com/.default, tidak ada permintaan persetujuan yang ditampilkan, terlepas dari isi izin terdaftar aplikasi klien untuk Microsoft Graph. Token yang dikembalikan berisi cakupan Mail.Read dan User.Read.

Contoh 2: Pengguna belum memberikan izin antara klien dan sumber daya

Dalam contoh ini, pengguna belum memberikan persetujuan antara klien dan Microsoft Graph, juga tidak memiliki administrator. Klien telah mendaftar untuk izin User.Read dan Contacts.Read. Ini juga telah terdaftar untuk lingkup Azure Key Vault https://vault.azure.net/user_impersonation.

Saat klien meminta token untuk scope=https://graph.microsoft.com/.default, pengguna akan melihat halaman persetujuan untuk cakupan Microsoft Graph User.Read dan Contacts.Read, dan untuk cakupan Azure Key Vault user_impersonation. Token yang ditampilkan hanya berisi cakupan User.Read dan Contacts.Read, dan hanya dapat digunakan terhadap Microsoft Graph.

Contoh 3: Pengguna telah menyetujui, dan klien meminta lebih banyak cakupan

Dalam contoh ini, pengguna telah menyetujui Mail.Read untuk klien. Klien telah mendaftar untuk cakupan Contacts.Read.

Klien pertama kali masuk menggunakan scope=https://graph.microsoft.com/.default . Berdasarkan parameter scopes dari respons, kode aplikasi mendeteksi bahwa hanya Mail.Read yang diberikan. Klien kemudian memulai proses masuk kedua menggunakan scope=https://graph.microsoft.com/.default, dan kali ini memaksa persetujuan menggunakan prompt=consent. Jika pengguna diizinkan untuk menyetujui semua izin yang didaftarkan aplikasi, mereka akan ditampilkan permintaan persetujuan. (Jika tidak, pesan kesalahan akan ditampilkan atau formulir permintaan persetujuan admin.) Keduanya Contacts.Read dan Mail.Read akan berada dalam permintaan persetujuan. Jika persetujuan diberikan dan proses masuk berlanjut, token yang ditampilkan adalah untuk Microsoft Graph, dan berisi Mail.Read dan Contacts.Read.

.default Menggunakan cakupan dengan klien

Dalam beberapa kasus, klien dapat meminta cakupan .defaultnya sendiri. Diagram berikut menunjukkan skenario ini.

// Line breaks are for legibility only.

GET https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize
    ?response_type=token            //Code or a hybrid flow is also possible here
    &client_id=00001111-aaaa-2222-bbbb-3333cccc4444
    &scope=9ada6f8a-6d83-41bc-b169-a306c21527a5/.default
    &redirect_uri=https%3A%2F%2Flocalhost
    &state=1234

Contoh kode ini menghasilkan halaman persetujuan untuk semua izin terdaftar jika deskripsi persetujuan sebelumnya dan .default berlaku untuk skenario. Kemudian kode mengembalikan sebuah id_token, bukan token akses.

Penyetelan ini tidak boleh digunakan oleh klien baru yang menargetkan platform identitas Microsoft. Pastikan untuk Bermigrasi ke Microsoft Authentication Library (MSAL) dari Azure AD Authentication Library (ADAL).

Alur pemberian kredensial klien dan .default

Penggunaan lain dari .default adalah untuk meminta peran aplikasi (juga dikenal sebagai izin aplikasi) dalam aplikasi non-interaktif seperti aplikasi daemon yang menggunakan alur pemberian info masuk klien untuk memanggil API web.

Untuk menentukan peran aplikasi (izin aplikasi) untuk API web, lihat Menambahkan peran aplikasi di aplikasi Anda.

Permintaan info masuk klien di layanan klien Anda harus menyertakan scope={resource}/.default. Di sini, {resource} adalah API web yang ingin dipanggil oleh aplikasi Anda, dan ingin mendapatkan token aksesnya. Mengeluarkan permintaan kredensial klien dengan menggunakan izin (peran) aplikasi individual tidak didukung. Semua peran aplikasi (izin aplikasi) yang telah diberikan untuk API web tersebut disertakan dalam token akses yang ditampilkan.

Untuk memberikan akses ke peran aplikasi yang Anda tetapkan, termasuk memberikan izin admin untuk aplikasi, lihat Mengonfigurasi aplikasi klien untuk mengakses API web.

Garis miring dan .default

Beberapa URI sumber daya memiliki garis miring berikutnya ke depan, misalnya, https://contoso.com/ dibandingkan dengan https://contoso.com. Garis miring berikutnya dapat menyebabkan masalah dengan validasi token. Masalah terjadi terutama ketika token diminta untuk Azure Resource Manager (https://management.azure.com/).

Dalam hal ini, garis miring berikutnya pada sumber daya URI berarti garis miring harus ada ketika token diminta. Jadi ketika Anda meminta token untuk https://management.azure.com/ dan menggunakan .default, Anda harus meminta https://management.azure.com//.default (perhatikan garis miring ganda!).

Secara umum, jika Anda memverifikasi bahwa token sedang dikeluarkan, dan jika token ditolak oleh API yang harus menerimanya, pertimbangkan untuk menambahkan garis miring maju kedua dan mencoba lagi.

Lihat juga