Bagikan melalui

Cakupan dan izin dalam platform identitas Microsoft

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 pengidentifikasi sumber daya, atau URI ID aplikasi.

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

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

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

Hal yang sama berlaku untuk sumber daya pihak ketiga apa pun yang terintegrasi dengan platform identitas Microsoft. Salah satu sumber daya ini juga dapat menentukan sekumpulan izin yang membagi fungsionalitas sumber daya tersebut menjadi potongan yang lebih kecil. Sebagai contoh, Microsoft Graph menentukan izin 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 OpenID Connect yang sudah terdefinisi dengan baik dan izin yang berbasis pada 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.

Izin yang dibatasi admin

Izin dalam platform identitas Microsoft dapat diatur menjadi terbatas untuk admin. 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. Sebagai gantinya, 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. Cakupan ini terkadang opsional dan dipertimbangkan untuk pengayaan token ID. Cakupan ini mungkin tidak selalu muncul dalam baris terpisah pada permintaan persetujuan pengguna.

Jika Anda meminta ruang lingkup dan token OpenID Connect, Anda akan mendapatkan token untuk mengakses titik akhir UserInfo .

Cakupan openid

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

Aplikasi menggunakan izin ini untuk menerima pengidentifikasi unik untuk pengguna dalam bentuk klaim sub. 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 profile klaim yang tersedia dalam parameter id_tokens untuk pengguna tertentu, merujuk ke id_tokens referensi.

Cakupan offline_access

Cakupanoffline_access memberi aplikasi Anda akses ke sumber daya atas nama pengguna dalam jangka waktu yang panjang. Pada halaman persetujuan, cakupan ini muncul sebagai Pertahankan akses ke data yang telah Anda berikan akses ke izin.

Jika salah satu izin yang didelegasikan yang diminta dari parameter scope (tidak termasuk openid, profile, email) diberikan, ini cukup bagi aplikasi untuk meminta token refresh menggunakan offline_access. Misalnya, jika User.Read untuk Microsoft diberikan, aplikasi hanya akan menerima token akses. Namun demikian, jika aplikasi kemudian meminta token penyegar, fakta bahwa User.Read telah diberikan sudah cukup untuk diberikan token penyegar. Token penyegaran memiliki umur 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 alur implisit). Pengaturan ini membahas skenario di mana klien dapat dimulai dalam aliran implisit dan kemudian pindah ke aliran kode di mana token penyegaran diharapkan.

Pada platform identitas Microsoft (permintaan yang dibuat ke endpoint 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 menerima token akses dari /token titik akhir.

Token akses 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 90 hari. Untuk informasi selengkapnya tentang cara mendapatkan dan menggunakan token refresh, lihat referensi protokol platform identitas Microsoft.

Penyertaan token refresh dalam respons dapat bergantung pada beberapa faktor, termasuk konfigurasi spesifik aplikasi Anda dan cakupan yang diminta selama proses otorisasi. Jika Anda ingin menerima token refresh dalam respons tetapi gagal, pertimbangkan faktor-faktor berikut:

  • Persyaratan cakupan: Pastikan Anda meminta offline_access cakupan bersama dengan cakupan lain yang diperlukan.
  • Jenis pemberian otorisasi: Token refresh disediakan saat menggunakan jenis pemberian kode otorisasi. Jika alur Anda berbeda, respons dapat terpengaruh.
  • Konfigurasi klien: Periksa pengaturan aplikasi Anda di platform identitas. Konfigurasi tertentu dapat membatasi penerbitan refresh_tokens.

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 di mana Anda harus menyertakan garis miring kedua untuk meminta token dengan benar, lihat bagian tentang garis miring tambahan.

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 dan untuk memulai persetujuan admin. Penggunaannya diperlukan dalam alur On-Behalf-Of 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 cakupan .default hanya memicu permintaan persetujuan jika persetujuan tidak 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 disediakan), permintaan persetujuan 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 diberikan untuk Microsoft Graph atas nama pengguna yang masuk, proses masuk akan berlanjut. 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 disajikan 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 mendaftar untuk izin User.Read dan Contacts.Read serta mendaftar untuk cakupan 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 menampilkan permintaan persetujuan. (Jika tidak, mereka ditunjukkan pesan kesalahan atau formulir permintaan persetujuan admin .) Baik maupun termasuk dalam prompt persetujuan. Jika persetujuan diberikan dan proses masuk berlanjut, token yang ditampilkan adalah untuk Microsoft Graph, dan berisi Mail.Read dan Contacts.Read.

Menggunakan cakupan .default 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.

Klien baru yang menargetkan platform identitas Microsoft tidak boleh menggunakan penyiapan ini. Pastikan untuk Bermigrasi ke Microsoft Authentication Library (MSAL) dari Azure AD Authentication Library (ADAL).

Alur pemberian kredensial klien dan .default

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

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

Permintaan kredensial 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 aplikasi individual (peran) 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 tentukan, termasuk memberikan persetujuan admin untuk aplikasi, lihat Mengonfigurasi aplikasi klien untuk mengakses API web.

Garis miring di akhir dan .default

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

Dalam hal ini, garis miring di akhir pada URI berarti garis miring tersebut harus ada saat 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 diterbitkan, dan jika token ditolak oleh API yang seharusnya menerimanya, pertimbangkan untuk menambahkan garis miring kedua dan mencoba lagi.

Lihat juga