Mengapa memperbarui ke platform identitas Microsoft (v2.0)?

  • Artikel

Saat mengembangkan aplikasi baru, penting untuk mengetahui perbedaan antara titik akhir platform identitas Microsoft (v2.0) dan Azure Active Directory (v1.0). Artikel ini membahas perbedaan utama antara titik akhir dan beberapa batasan yang ada untuk platform identitas Microsoft.

Siapa yang dapat masuk

Siapa yang bisa masuk dengan titik akhir v1.0 dan v2.0

  • Titik akhir v1.0 hanya mengizinkan akun kantor dan sekolah untuk masuk ke aplikasi Anda (Microsoft Azure Active Directory)
  • Titik akhir platform identitas Microsoft memungkinkan akun kantor dan sekolah dari ID Microsoft Entra dan akun Microsoft pribadi (MSA), seperti hotmail.com, outlook.com, dan msn.com, untuk masuk.
  • Kedua titik akhir juga menerima rincian masuk pengguna tamu dari direktori Microsoft Entra untuk aplikasi yang dikonfigurasi sebagai penyewa tunggal atau untuk aplikasi multi-penyewa yang dikonfigurasi untuk menunjuk ke titik akhir khusus penyewa (https://login.microsoftonline.com/{TenantId_or_Name}).

Titik akhir platform identitas Microsoft memungkinkan Anda menulis aplikasi yang menerima masuk dari akun Microsoft pribadi, serta akun kantor dan sekolah. Ini memberi Anda kemampuan untuk menulis aplikasi Anda yang sepenuhnya akun agnostik. Misalnya, jika aplikasi Anda memanggil Microsoft Graph, beberapa fungsionalitas dan data tambahan akan tersedia untuk akun kerja, seperti situs SharePoint atau data direktori mereka. Namun, untuk banyak tindakan, seperti Membaca email pengguna, kode yang sama dapat mengakses email untuk akun pribadi serta kantor dan sekolah.

Untuk titik akhir platform identitas Microsoft, Anda dapat menggunakan Pusraka Autentikasi Microsoft (MSAL) untuk mendapatkan akses ke dunia konsumen, pendidikan, dan perusahaan. Titik akhir Azure AD v1.0 hanya menerima masuk dari akun kantor dan sekolah.

Aplikasi yang menggunakan titik akhir Azure AD v1.0 diperlukan untuk menentukan izin OAuth 2.0 yang diperlukan sebelumnya, misalnya:

Contoh memperlihatkan Antarmuka Pengguna Pendaftaran Izin

Izin yang ditetapkan langsung pada pendaftaran aplikasi adalah statis. Meskipun izin statis dari aplikasi yang ditentukan di portal Microsoft Azure menjaga kode tetap bagus dan sederhana, aplikasi ini menyajikan beberapa masalah yang mungkin bagi pengembang:

  • Aplikasi ini perlu meminta semua izin yang diperlukan pada masuk pertama pengguna. Hal ini dapat menyebabkan daftar panjang izin yang mencegah pengguna akhir menyetujui akses aplikasi pada masuk awal.

  • Aplikasi harus mengetahui semua sumber daya yang pernah diakses sebelumnya. Sulit untuk membuat aplikasi yang dapat mengakses jumlah sumber daya arbitrer.

Dengan titik akhir platform identitas Microsoft, Anda dapat mengabaikan izin statis yang ditentukan dalam informasi pendaftaran aplikasi di portal Microsoft Azure dan meminta izin secara bertahap sebagai gantinya, yang berarti meminta serangkaian izin minimum di muka dan berkembang lebih banyak dari waktu ke waktu karena pelanggan menggunakan fitur aplikasi tambahan. Untuk melakukannya, Anda dapat menentukan cakupan yang dibutuhkan aplikasi kapan saja dengan menyertakan cakupan baru dalam paramater scope saat meminta token akses - tanpa harus menentukannya sebelumnya dalam informasi pendaftaran aplikasi. Jika pengguna belum menyetujui cakupan baru yang ditambahkan ke permintaan, mereka akan diminta untuk hanya menyetujui izin baru. Untuk mempelajari selengkapnya, lihat izin, persetujuan, dan cakupan.

Mengizinkan aplikasi untuk meminta izin secara dinamis melalui parameter scope 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 mencoba menggunakan fitur tertentu aplikasi dari waktu ke waktu.

Persetujuan admin yang dilakukan atas nama organisasi masih memerlukan izin statis yang didaftarkan untuk aplikasi, jadi, Anda harus menetapkan izin tersebut untuk aplikasi di portal pendaftaran aplikasi jika Anda memerlukan admin untuk memberikan persetujuan atas nama seluruh organisasi. Ini mengurangi siklus yang diperlukan oleh admin organisasi untuk menyiapkan aplikasi.

Cakupan, bukan sumber daya

Untuk aplikasi yang menggunakan titik akhir v1.0, aplikasi dapat berperilaku sebagai sumber daya, atau penerima token. Sumber daya dapat menentukan sejumlah cakupan atau oAuth2Permissions yang dipahaminya, memungkinkan aplikasi klien meminta token dari sumber daya tersebut untuk sekumpulan cakupan tertentu. Pertimbangkan API Microsoft Graph sebagai contoh sumber daya:

  • Pengidentifikasi sumber daya, atau AppID URI: https://graph.microsoft.com/
  • Cakupan, atau oAuth2Permissions: Directory.Read, Directory.Write, dan sebagainya.

Ini berlaku untuk titik akhir platform identitas Microsoft. Aplikasi masih dapat berperilaku sebagai sumber daya, menentukan cakupan, dan diidentifikasi oleh URI. Aplikasi klien masih dapat meminta akses ke cakupan tersebut. Namun, cara klien meminta izin tersebut sudah berubah.

Untuk titik akhir v1.0, permintaan otorisasi OAuth 2.0 ke Microsoft Azure Active Directory mungkin terlihat seperti:

GET https://login.microsoftonline.com/common/oauth2/authorize?
client_id=2d4d11a2-f814-46a7-890a-274a72a7309e
&resource=https://graph.microsoft.com/
...

Di sini, parameter sumber daya menunjukkan sumber daya mana yang otorisasinya diminta oleh aplikasi klien. Microsoft Azure Active Directory menghitung izin yang diperlukan oleh aplikasi berdasarkan konfigurasi statis di portal Microsoft Azure, dan mengeluarkan token yang sesuai.

Untuk aplikasi yang menggunakan titik poin platform identitas Microsoft, permintaan otorisasi OAuth 2.0 yang sama terlihat seperti:

GET https://login.microsoftonline.com/common/oauth2/v2.0/authorize?
client_id=2d4d11a2-f814-46a7-890a-274a72a7309e
&scope=https://graph.microsoft.com/directory.read%20https://graph.microsoft.com/directory.write
...

Di sini, parameter cakupan menunjukkan sumber daya dan izin mana yang otorisasinya diminta oleh aplikasi. Sumber daya yang diinginkan masih ada dalam permintaan - ini tercakup dalam tiap nilai parameter cakupan. Menggunakan parameter cakupan dengan cara ini memungkinkan titik akhir platform identitas Microsoft untuk lebih mematuhi spesifikasi OAuth 2.0, dan menyelaraskan lebih dekat dengan praktik industri umum. Ini juga memungkinkan aplikasi melakukan persetujuan inkremental - hanya meminta izin ketika aplikasi mengharuskannya sebagai ganti di muka.

Cakupan terkenal

Akses offline

Aplikasi yang menggunakan titik akhir platform identitas Microsoft mungkin memerlukan penggunaan izin terkenal baru untuk aplikasi - cakupan offline_access. Semua aplikasi harus meminta izin ini jika perlu mengakses sumber daya atas nama pengguna untuk jangka waktu yang lama, bahkan ketika pengguna mungkin tidak aktif menggunakan aplikasi. Cakupan offline_access akan muncul ke pengguna dalam dialog persetujuan sebagai Akses data Anda kapan saja, yang harus disetujui pengguna. Meminta izin offline_access akan memungkinkan aplikasi web Anda menerima refresh_tokens OAuth 2.0 dari titik akhir platform identitas Microsoft. Token refresh bertahan lama, dan dapat ditukar dengan token akses OAuth 2.0 baru untuk jangka waktu akses yang lama.

Jika aplikasi Anda tidak meminta cakupan offline_access, aplikasi tersebut tidak akan menerima token refresh. Artinya ketika Anda menukarkan kode otorisasi di alur kode otorisasi OAuth 2.0, Anda hanya akan menerima kembali token akses dari titik akhir /token. Token akses tersebut tetap berlaku untuk waktu yang singkat (biasanya satu jam), tetapi akhirnya akan kedaluwarsa. Pada saat itu, aplikasi Anda harus mengarahkan pengguna kembali ke titik akhir /authorize untuk mengambil kode otorisasi baru. Selama pengalihan ini, pengguna mungkin atau mungkin tidak perlu memasukkan info masuk mereka lagi atau menyetujui ulang izin, tergantung pada jenis aplikasi.

Untuk mempelajari selengkapnya tentang OAuth 2.0, refresh_tokens, dan access_tokens, lihat referensi protokol platform identitas Microsoft.

OpenID, profil, dan email

Secara historis, alur masuk OpenID Connect yang paling mendasar dengan platform identitas Microsoft akan memberikan banyak informasi tentang pengguna dalam id_token yang dihasilkan. Klaim dalam id_token mencakup nama pengguna, nama pengguna pilihan, alamat email, ID objek, dan banyak lagi.

Informasi yang diberikan oleh cakupan openid untuk mengakses aplikasi Anda sekarang dibatasi. Cakupan openid hanya akan memungkinkan aplikasi Anda masuk ke pengguna dan menerima pengidentifikasi khusus aplikasi untuk pengguna. Jika Anda ingin mendapatkan data pribadi tentang pengguna di aplikasi, aplikasi Anda harus meminta izin tambahan dari pengguna. Dua cakupan baru, email dan profile, akan mengizinkan Anda meminta izin tambahan.

  • Cakupan email memungkinkan aplikasi Anda mengakses alamat email utama pengguna melalui klaim email di id_token, dengan asumsi pengguna memiliki alamat email yang dapat diatasi.
  • Cakupan profile ini memberikan akses aplikasi Anda ke semua informasi dasar lainnya tentang pengguna, seperti nama mereka, nama pengguna pilihan, ID objek, dan sebagainya, dalam id_token.

Cakupan ini memungkinkan Anda mengodekan aplikasi Anda dengan cara pengungkapan minimal sehingga Anda hanya dapat meminta pengguna untuk serangkaian informasi yang diperlukan aplikasi Anda untuk melakukan pekerjaannya. Untuk informasi selengkapnya tentang cakupan ini, lihat referensi cakupan platform identitas Microsoft.

Klaim token

Titik akhir platform identitas Microsoft mengeluarkan serangkaian klaim yang lebih kecil dalam tokennya secara default untuk menjaga payload tetap kecil. Jika Anda memiliki aplikasi dan layanan yang memiliki dependensi pada klaim tertentu dalam token v1.0 yang tidak lagi disediakan secara default dalam token platform identitas Microsoft, pertimbangkan untuk menggunakan fitur klaim opsional untuk menyertakan klaim tersebut.

Penting

Token v1.0 dan v2.0 dapat dikeluarkan oleh titik akhir v1.0 dan v2.0! id_tokens selalu cocok dengan titik akhir yang mereka minta, dan token akses selalu cocok dengan format yang diharapkan oleh API Web yang akan dipanggil klien Anda menggunakan token tersebut. Jadi, jika aplikasi Anda menggunakan titik akhir v2.0 untuk mendapatkan token untuk memanggil Microsoft Graph, yang mengharapkan token akses format v1.0, aplikasi Anda akan menerima token dalam format v1.0.

Batasan

Ada beberapa batasan yang perlu diperhatikan saat menggunakan platform identitas Microsoft.

Saat Anda membangun aplikasi yang terintegrasi dengan platform identitas Microsoft, Anda perlu memutuskan apakah titik akhir platform identitas Microsoft dan protokol autentikasi memenuhi kebutuhan Anda. Titik akhir v1.0 dan platform masih didukung sepenuhnya dan, dalam beberapa hal, fiturnya lebih kaya daripada platform identitas Microsoft. Namun, platform identitas Microsoft memperkenalkan manfaat signifikan bagi pengembang.

Berikut adalah rekomendasi yang disederhanakan untuk pengembang sekarang:

  • Jika Anda ingin atau perlu mendukung akun Microsoft pribadi di aplikasi Anda, atau Anda sedang menulis aplikasi baru, gunakan platform identitas Microsoft. Namun, sebelum Anda melakukannya, pastikan Anda memahami batasan yang dibahas dalam artikel ini.
  • Jika Anda memigrasikan atau memperbarui aplikasi yang bergantung pada SAML, Anda tidak dapat menggunakan platform identitas Microsoft. Sebagai gantinya, lihat panduan Azure AD v1.0.

Titik akhir platform identitas Microsoft akan berkembang untuk menghilangkan pembatasan yang tercantum di sini, sehingga Anda hanya perlu menggunakan titik akhir platform identitas Microsoft. Sementara itu, gunakan artikel ini untuk menentukan apakah titik akhir platform identitas Microsoft tepat untuk Anda. Kami akan terus memperbarui artikel ini untuk mencerminkan status titik akhir platform identitas Microsoft saat ini. Periksa kembali untuk mengevaluasi ulang persyaratan Anda terhadap kemampuan platform identitas Microsoft.

Pembatasan pendaftaran aplikasi

Untuk tiap aplikasi yang ingin Anda integrasikan dengan titik akhir platform identitas Microsoft, Anda dapat membuat pendaftaran aplikasi di pengalaman Pendaftaran aplikasi baru di portal Microsoft Azure. Aplikasi akun Microsoft yang ada tidak kompatibel dengan portal, tetapi semua aplikasi Microsoft Entra berada, terlepas dari di mana atau kapan aplikasi tersebut terdaftar.

Pendaftaran aplikasi yang mendukung akun kantor dan sekolah serta akun pribadi memiliki peringatan berikut:

  • Hanya dua rahasia aplikasi yang diizinkan per ID aplikasi.
  • Aplikasi yang tidak terdaftar di penyewa hanya dapat dikelola oleh akun yang mendaftarkannya. Ini tidak dapat dibagikan dengan pengembang lain. Ini adalah kasus untuk sebagian besar aplikasi yang terdaftar menggunakan akun Microsoft pribadi di Portal Pendaftaran Aplikasi. Jika Anda ingin berbagi pendaftaran aplikasi dengan beberapa pengembang, daftarkan aplikasi di penyewa menggunakan bagian Pendaftaran aplikasi baru di portal Microsoft Azure.
  • Ada beberapa batasan format URL pengalihan yang diizinkan. Untuk informasi selengkapnya tentang URL, lihat bagian berikutnya.

Pembatasan pada URL pengalihan

Untuk informasi terbaru tentang pembatasan URL pengalihan untuk aplikasi yang terdaftar untuk platform identitas Microsoft, lihat pembatasan dan batasan URI pengalihan/URL balasan dalam dokumentasi platform identitas Microsoft.

Untuk mempelajari cara mendaftarkan aplikasi untuk digunakan dengan platform identitas Microsoft, lihat Mendaftarkan aplikasi menggunakan pengalaman Pendaftaran aplikasi baru.

Pembatasan pustaka dan SDK

Saat ini, dukungan pustaka untuk titik akhir platform identitas Microsoft terbatas. Jika Anda ingin menggunakan titik akhir platform identitas Microsoft dalam aplikasi produksi, Anda memiliki opsi ini:

  • Jika Anda membangun aplikasi web, Anda dapat menggunakan middleware sisi server yang tersedia secara umum untuk melakukan validasi masuk dan token. Ini termasuk middleware OpenID Connect OWIN untuk ASP.NET dan plug-in Node.js Passport. Untuk sampel kode yang menggunakan middleware Microsoft, lihat bagian Memulai platform identitas Microsoft.
  • Jika Anda membuat aplikasi desktop atau seluler, Anda bisa menggunakan salah satu Pustaka Autentikasi Microsoft (MSAL). Pustaka ini umumnya tersedia atau dalam pratinjau yang didukung produksi, sehingga aman untuk menggunakannya dalam aplikasi produksi. Anda bisa membaca selengkapnya tentang ketentuan pratinjau dan pustaka yang tersedia dalam referensi pustaka autentikasi.
  • Untuk platform yang tidak tercakup oleh pustaka Microsoft, Anda dapat berintegrasi dengan titik akhir platform identitas Microsoft dengan langsung mengirim dan menerima pesan protokol dalam kode aplikasi Anda. Protokol OpenID Connect dan OAuth secara eksplisit didokumentasikan untuk membantu Anda melakukan integrasi seperti itu.
  • Terakhir, Anda dapat menggunakan pustaka OpenID Connect dan OAuth sumber terbuka untuk berintegrasi dengan titik akhir platform identitas Microsoft. Titik akhir platform identitas Microsoft harus kompatibel dengan banyak pustaka protokol sumber terbuka tanpa perubahan. Ketersediaan pustaka semacam ini bervariasi menurut bahasa dan platform. Situs web OpenID Connect dan OAuth 2.0 mempertahankan daftar implementasi populer. Untuk informasi selengkapnya, lihat Pustaka platform identitas dan autentikasi Microsoft, dan daftar pustaka dan sampel klien sumber terbuka yang telah diuji dengan titik akhir platform identitas Microsoft.
  • Sebagai referensi, titik akhir .well-known untuk titik akhir umum platform identitas Microsoft adalah https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration. Ganti common dengan ID penyewa Anda untuk mendapatkan data yang spesifik dengan penyewa Anda.

Perubahan protokol

Titik akhir platform identitas Microsoft tidak mendukung SAML atau WS-Federation; ini hanya mendukung OpenID Connect dan OAuth 2.0. Perubahan penting pada protokol OAuth 2.0 dari titik akhir v1.0 adalah:

  • Klaim email dikembalikan jika klaim opsional dikonfigurasi ataupun ruang lingkup=email ditentukan dalam permintaan.
  • Parameter scope sekarang didukung sebagai ganti parameter resource.
  • Banyak respons sudah dimodifikasi untuk membuatnya lebih sesuai dengan spesifikasi OAuth 2.0, misalnya, mengambalikan expires_in dengan benar sebagai int, bukan string.

Untuk lebih memahami cakupan fungsionalitas protokol yang didukung di titik akhir platform identitas Microsoft, lihat referensi protokol OpenID Connect dan OAuth 2.0.

Penggunaan SAML

Jika Anda sudah menggunakan Active Directory Authentication Library (ADAL) di aplikasi Windows, Anda mungkin sudah memanfaatkan autentikasi Terintegrasi Windows, yang menggunakan hibah pernyataan Security Assertion Markup Language (SAML). Dengan pemberian ini, pengguna penyewa Microsoft Entra federasi dapat secara diam-diam mengautentikasi dengan instans Active Directory lokal mereka tanpa memasukkan kredensial. Meskipun SAML masih merupakan protokol yang didukung untuk digunakan dengan pengguna perusahaan, titik akhir v2.0 hanya untuk digunakan dengan aplikasi OAuth 2.0.

Langkah berikutnya

Pelajari lebih lanjut di dokumentasi platform identitas Microsoft.