alur pemberian implisit platform identitas Microsoft dan OAuth 2.0

  • Artikel

Platform identitas Microsoft mendukung alur pemberian implisit OAuth 2.0 seperti yang dijelaskan dalam Spesifikasi OAuth 2.0. Karakteristik yang menentukan dari pemberian implisit adalah bahwa token (token ID atau token akses) dihasilkan langsung dari titik akhir /otorisasi, alih-alih titik akhir /token. Hak ini sering digunakan sebagai bagian dari alur kode otorisasi, dalam apa yang disebut "alur hibrid" - mengambil token ID pada permintaan /otorisasi dengan kode otorisasi.

Artikel ini menjelaskan cara memprogram secara langsung terhadap protokol di aplikasi Anda untuk meminta token dari ID Microsoft Entra. Jika memungkinkan, sebaiknya Anda menggunakan Pustaka Autentikasi Microsoft (MSAL) yang didukung, bukan untuk memperoleh token dan memanggil API web aman. Lihat juga sampel aplikasi yang menggunakan MSAL.

Lebih memilih alur kode autentikasi

Dengan rencana untuk menghapus cookie pihak ketiga dari browser, pemberian implisit bukan lagi metode autentikasi yang cocok. Fitur akses menyeluruh (SSO) senyap dari alur implisit tidak berfungsi tanpa cookie pihak ketiga, menyebabkan aplikasi rusak ketika mereka mencoba untuk mendapatkan token baru. Kami menyarankan agar semua aplikasi baru menggunakan alur kode otorisasi yang sekarang mendukung aplikasi halaman tunggal yang menggantikan alur implisit. Aplikasi halaman tunggal yang ada juga harus bermigrasi ke alur kode otorisasi.

Skenario yang cocok untuk pemberian implisit OAuth2

Pemberian implisit hanya diandalkan untuk bagian awal dan interaktif dari alur masuk Anda, di mana kurangnya cookie pihak ketiga tidak memengaruhi aplikasi Anda. Batasan ini berarti Anda harus menggunakannya secara eksklusif sebagai bagian dari alur hibrid, di mana aplikasi Anda meminta kode serta token dari titik akhir otorisasi. Dalam alur hibrida, aplikasi Anda menerima kode yang dapat ditukarkan dengan token refresh, sehingga memastikan sesi masuk aplikasi Anda tetap berlaku dari waktu ke waktu.

Diagram protokol

Diagram berikut menunjukkan keseluruhan alur masuk implisit dan bagian setelahnya menjelaskan setiap langkah secara detail.

Diagram showing the implicit sign-in flow

Mengirim permintaan masuk

Untuk pertama memasukkan pengguna ke aplikasi, Anda dapat mengirim permintaan autentikasi OpenID Connect dan mendapatkan id_token dari platform identitas Microsoft.

Penting

Agar berhasil meminta token ID dan/atau token akses, pendaftaran aplikasi di pusat admin Microsoft Entra - Pendaftaran aplikasi halaman harus mengaktifkan alur pemberian implisit yang sesuai, dengan memilih token ID dan token akses di bagian Pemberian implisit dan alur hibrid. Jika tidak diaktifkan, kesalahan unsupported_response akan dikembalikan:

The provided value for the input parameter 'response_type' is not allowed for this client. Expected value is 'code'

// Line breaks for legibility only

https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?
client_id=535fb089-9ff3-47b6-9bfb-4f1264799865
&response_type=id_token
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&scope=openid
&response_mode=fragment
&state=12345
&nonce=678910
Parameter Jenis Deskripsi
tenant diperlukan Nilai {tenant} di jalur permintaan dapat digunakan untuk mengontrol siapa yang dapat masuk ke aplikasi. Nilai yang diizinkan adalah common, organizations, consumers, dan pengidentifikasi penyewa. Untuk detail selengkapnya, lihat dasar-dasar protokol. Yang terpenting, untuk skenario tamu di mana Anda memasukkan pengguna dari satu penyewa ke penyewa lain, Anda harus memberikan pengidentifikasi penyewa untuk memasukkan mereka ke dalam sumber daya penyewa dengan benar.
client_id diperlukan ID Aplikasi (klien) yang ditetapkan pusat admin Microsoft Entra - halaman Pendaftaran aplikasi ke aplikasi Anda.
response_type diperlukan Harus menyertakan id_token untuk masuk OpenID Connect. Ini juga dapat mencakup response_type, token. Penggunaan token di sini akan memungkinkan aplikasi Anda untuk langsung menerima token akses dari titik akhir otorisasi tanpa harus membuat permintaan kedua ke titik akhir otorisasi. Jika Anda menggunakan token response_type, scope parameter harus berisi cakupan yang menunjukkan sumber daya mana yang akan mengeluarkan token (misalnya, user.read di Microsoft Graph). Ini juga dapat code alih-alih token untuk memberikan kode otorisasi, untuk digunakan dalam alur kode otorisasi. Respons ini id_token+code terkadang disebut aliran hibrid.
redirect_uri Disarankan URI pengalihan aplikasi Anda, di mana respons autentikasi dapat dikirim dan diterima oleh aplikasi Anda. Hal ini harus sama persis dengan salah satu URI pengalihan yang Anda daftarkan di portal, kecuali jika harus dikodekan URL.
scope diperlukan Daftar cakupan yang dipisahkan spasi. Untuk OpenID Koneksi (id_tokens), harus menyertakan cakupan openid, yang diterjemahkan ke izin "Masuk Anda" di UI persetujuan. Secara opsional Anda mungkin juga ingin menyertakan cakupan email dan profile untuk mendapatkan akses ke data pengguna tambahan. Anda juga dapat menyertakan cakupan lain dalam permintaan ini untuk meminta persetujuan ke berbagai sumber daya, jika token akses diminta.
response_mode opsional Menentukan metode yang akan digunakan untuk mengirim token yang dihasilkan kembali ke aplikasi Anda. Default guna melakukan kueri hanya untuk token akses, tetapi fragmen jika permintaan menyertakan id_token.
state Disarankan Nilai yang disertakan dalam permintaan yang juga akan dikembalikan dalam respons token. Ini bisa berupa untai (karakter) dari konten yang Anda inginkan. Nilai unik yang dihasilkan secara acak biasanya digunakan untuk mencegah serangan pemalsuan permintaan lintas situs. Status ini juga digunakan untuk mengkodekan informasi tentang status pengguna di aplikasi sebelum permintaan autentikasi muncul, seperti halaman atau tampilan tempat mereka berada.
nonce diperlukan Nilai yang disertakan dalam permintaan, yang dihasilkan oleh aplikasi, yang akan disertakan dalam token ID yang dihasilkan sebagai klaim. Aplikasi kemudian dapat memverifikasi nilai ini untuk meminimalkan serangan replay token. Biasanya, nilainya adalah string acak dan unik yang dapat digunakan untuk mengidentifikasi asal permintaan. Hanya diperlukan ketika id_token diminta.
prompt opsional Menunjukkan jenis interaksi pengguna yang diperlukan. Satu-satunya nilai yang valid saat ini adalah login, none, select_account dan consent. prompt=login akan memaksa pengguna untuk memasukkan info masuk mereka pada permintaan itu, meniadakan single sign-on. prompt=none adalah sebaliknya - ini akan memastikan bahwa pengguna tidak diberikan permintaan interaktif apa pun. Jika permintaan tidak dapat diselesaikan secara diam-diam melalui SSO, platform identitas Microsoft akan mengembalikan kesalahan. prompt=select_account mengirim pengguna ke pemilih akun di mana semua akun yang diingat di sesi akan muncul. prompt=consent akan memicu dialog persetujuan OAuth setelah pengguna masuk, meminta pengguna untuk memberikan izin ke aplikasi.
login_hint opsional Anda dapat menggunakan parameter ini untuk mengisi terlebih dulu bidang nama pengguna dan alamat email halaman masuk untuk pengguna, jika Anda mengetahui nama pengguna sebelumnya. Sering kali, aplikasi menggunakan parameter ini selama autentikasi ulang, setelah mengekstrak login_hintklaim opsional dari proses masuk sebelumnya.
domain_hint opsional Jika disertakan, hal ini akan melewati proses penemuan berbasis email yang dilalui pengguna di halaman masuk, untuk pengalaman pengguna yang sedikit lebih mudah. Parameter ini biasanya digunakan untuk aplikasi Lini Bisnis yang beroperasi dalam satu penyewa, di mana mereka akan memberikan nama domain dalam penyewa tertentu, meneruskan pengguna ke penyedia federasi untuk penyewa tersebut. Petunjuk ini mencegah tamu masuk ke aplikasi ini, dan membatasi penggunaan info masuk cloud seperti FIDO.

Pada titik ini, pengguna diminta untuk memasukkan kredensial mereka dan menyelesaikan autentikasi. Platform identitas Microsoft memverifikasi bahwa pengguna sudah menyetujui izin yang ditunjukkan dalam parameter kueri scope. Jika pengguna belum menyetujui izin tersebut, pengguna akan diminta untuk menyetujui izin yang diperlukan. Untuk informasi selengkapnya, lihat izin, persetujuan, dan aplikasi multi-penyewa.

Setelah pengguna mengautentikasi dan memberikan persetujuan, platform identitas Microsoft mengembalikan respons ke aplikasi Anda di redirect_uri yang ditunjukkan, menggunakan metode yang ditentukan dalam parameter response_mode.

Respons berhasil

Respons berhasil yang menggunakan response_mode=fragment dan response_type=id_token+code terlihat seperti berikut ini (dengan pembatas baris untuk memperjelas):

GET https://localhost/myapp/#
code=0.AgAAktYV-sfpYESnQynylW_UKZmH-C9y_G1A
&id_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...
&state=12345
Parameter Deskripsi
code Disertakan jika response_type menyertakan code. Ini adalah kode otorisasi yang cocok untuk digunakan dalam alur kode otorisasi.
access_token Disertakan jika response_type menyertakan token. Token akses yang diminta aplikasi. Token akses tidak boleh dikodekan atau diperiksa, harus diperlakukan sebagai untai (karakter) buram.
token_type Disertakan jika response_type menyertakan token. Bearer akan selalu digunakan.
expires_in Disertakan jika response_type menyertakan token. Menunjukkan jumlah detik token valid, untuk tujuan penembolokan.
scope Disertakan jika response_type menyertakan token. Menunjukkan cakupan tempat access_token akan valid. Mungkin tidak menyertakan semua cakupan yang diminta jika tidak berlaku untuk pengguna. Misalnya, cakupan khusus Microsoft Entra yang diminta saat masuk menggunakan akun pribadi.
id_token JSON Web Token (JWT) yang ditandatangani. Aplikasi dapat mendekodekan segmen token ini untuk meminta informasi tentang pengguna yang masuk. Aplikasi dapat menyimpan nilai dan menampilkannya, tetapi tidak boleh bergantung padanya untuk batas otorisasi atau keamanan apa pun. Untuk informasi selengkapnya tentang token ID, lihat id_token reference.
Catatan: Hanya disediakan jika cakupan openid diminta dan response_type disertakan id_tokens.
state Jika parameter status disertakan dalam permintaan, nilai yang sama akan muncul dalam respons. Aplikasi harus memverifikasi bahwa nilai status dalam permintaan dan respons adalah identik.

Peringatan

Jangan mencoba memvalidasi atau membaca token untuk API apa pun yang tidak Anda miliki, termasuk token dalam contoh ini, dalam kode Anda. Token untuk layanan Microsoft dapat menggunakan format khusus yang tidak akan divalidasi sebagai JWT, dan juga dapat dienkripsi untuk pengguna konsumen (akun Microsoft). Meskipun membaca token adalah alat penelusuran kesalahan dan pembelajaran yang berguna, jangan mengambil dependensi terhadapnya dalam kode Anda atau asumsikan hal-hal yang spesifik tentang token yang bukan untuk API yang Anda kontrol.

Respons kesalahan

Respons kesalahan juga dapat dikirim ke redirect_uri sehingga aplikasi dapat menanganinya dengan tepat:

GET https://localhost/myapp/#
error=access_denied
&error_description=the+user+canceled+the+authentication
Parameter Deskripsi
error String kode kesalahan yang dapat digunakan untuk mengklasifikasikan jenis kesalahan yang terjadi, dan dapat digunakan untuk bereaksi terhadap kesalahan.
error_description Pesan kesalahan tertentu yang dapat membantu Anda mengidentifikasi akar penyebab kesalahan autentikasi.

Memperoleh token akses secara diam-diam

Penting

Bagian dari alur implisit ini mungkin tidak berfungsi untuk aplikasi Anda karena digunakan di berbagai browser akibat penghapusan cookie pihak ketiga secara default. Meskipun masih berfungsi di browser berbasis Chromium yang tidak ada di Incognito, pengembang harus mempertimbangkan kembali penggunaan bagian alur ini. Di browser yang tidak mendukung cookie pihak ketiga, Anda akan menerima kesalahan yang menunjukkan bahwa tidak ada pengguna masuk, karena cookie sesi halaman masuk dihapus oleh browser.

Sekarang setelah menandatangani pengguna ke aplikasi halaman tunggal Anda, Anda dapat dengan senyap mendapatkan token akses untuk memanggil API web yang diamankan oleh platform identitas Microsoft, seperti Microsoft Graph. Bahkan jika Anda telah menerima token menggunakan response_type token, Anda dapat menggunakan metode ini untuk memperoleh token sebagai sumber daya tambahan tanpa mengalihkan pengguna untuk masuk lagi.

Dalam alur OpenID Connect/OAuth normal, Anda akan melakukan ini dengan membuat permintaan ke titik akhir /token platform identitas Microsoft. Anda dapat membuat permintaan di iframe tersembunyi agar mendapatkan token baru untuk API web lainnya:

// Line breaks for legibility only

https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?
client_id=535fb089-9ff3-47b6-9bfb-4f1264799865
&response_type=token
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&scope=https%3A%2F%2Fgraph.microsoft.com%2Fuser.read
&response_mode=fragment
&state=12345
&nonce=678910
&prompt=none
&login_hint=myuser@mycompany.com

Untuk detail tentang parameter kueri di URL, lihat mengirim permintaan masuk.

Tip

Coba salin & tempel permintaan di bawah ini ke tab browser! (Jangan lupa untuk mengganti nilai login_hint dengan nilai yang benar bagi pengguna)

https://login.microsoftonline.com/common/oauth2/v2.0/authorize?client_id=535fb089-9ff3-47b6-9bfb-4f1264799865&response_type=token&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F&scope=https%3A%2F%2Fgraph.microsoft.com%2Fuser.read&response_mode=fragment&state=12345&nonce=678910&prompt=none&login_hint={your-username}

Perhatikan bahwa ini akan berfungsi bahkan di browser tanpa dukungan cookie pihak ketiga, karena Anda memasukkan ini langsung ke bilah browser dibandingkan dengan membukanya dalam iframe.

Berkat parameter prompt=none, permintaan ini akan segera berhasil atau gagal dan kembali ke aplikasi Anda. Respons akan dikirim ke aplikasi Anda pada redirect_uri yang ditunjukkan, menggunakan metode yang ditentukan dalam parameter response_mode.

Respons berhasil

Respons berhasil yang menggunakan response_mode=fragment akan terlihat seperti:

GET https://localhost/myapp/#
access_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...
&state=12345
&token_type=Bearer
&expires_in=3599
&scope=https%3A%2F%2Fgraph.microsoft.com%2Fdirectory.read
Parameter Deskripsi
access_token Disertakan jika response_type menyertakan token. Token akses yang diminta aplikasi, dalam kasus ini untuk Microsoft Graph. Token akses tidak boleh dikodekan atau diperiksa, harus diperlakukan sebagai untai (karakter) buram.
token_type Bearer akan selalu digunakan.
expires_in Menunjukkan jumlah detik token valid, untuk tujuan penembolokan.
scope Menunjukkan cakupan yang token aksesnya akan valid. Mungkin tidak menyertakan semua cakupan yang diminta, jika tidak berlaku untuk pengguna (dalam kasus cakupan khusus Microsoft Entra diminta saat akun pribadi digunakan untuk masuk).
id_token JSON Web Token (JWT) yang ditandatangani. Disertakan jika response_type menyertakan id_token. Aplikasi dapat mendekodekan segmen token ini untuk meminta informasi tentang pengguna yang masuk. Aplikasi dapat menyimpan nilai dan menampilkannya, tetapi tidak boleh bergantung padanya untuk batas otorisasi atau keamanan apa pun. Untuk informasi selengkapnya tentang id_tokens, lihat id_token referensi.
Catatan: Hanya disediakan jika openid ruang lingkup diminta.
state Jika parameter status disertakan dalam permintaan, nilai yang sama akan muncul dalam respons. Aplikasi harus memverifikasi bahwa nilai status dalam permintaan dan respons adalah identik.

Respons kesalahan

Respons kesalahan juga dapat dikirim ke redirect_uri sehingga aplikasi dapat menanganinya dengan sesuai. Dalam kasus prompt=none, kesalahan yang diharapkan adalah:

GET https://localhost/myapp/#
error=user_authentication_required
&error_description=the+request+could+not+be+completed+silently
Parameter Deskripsi
error String kode kesalahan yang dapat digunakan untuk mengklasifikasikan jenis kesalahan yang terjadi, dan dapat digunakan untuk bereaksi terhadap kesalahan.
error_description Pesan kesalahan tertentu yang dapat membantu Anda mengidentifikasi akar penyebab kesalahan autentikasi.

Jika Anda menerima pesan kesalahan ini dalam permintaan iframe, maka pengguna harus masuk lagi secara interaktif untuk mengambil token baru. Anda dapat memilih untuk menangani kasus ini dengan cara apa pun masuk akal untuk aplikasi Anda.

Menyegarkan token

Hibah yang tersirat tidak menyediakan token refresh. Token ID dan token akses akan kedaluwarsa setelah waktu yang singkat, sehingga aplikasi Anda harus siap untuk merefresh token ini secara berkala. Untuk menyegarkan salah satu jenis token, Anda dapat melakukan permintaan iframe tersembunyi yang sama dari yang di atas menggunakan parameter prompt=none untuk mengontrol perilaku platform identitas. Jika Anda ingin menerima token ID baru, pastikan untuk menggunakan id_token dalam response_type dan scope=openid, serta nonce parameter.

Di browser yang tidak mendukung cookie pihak ketiga, ini akan mengakibatkan kesalahan yang menunjukkan bahwa tidak ada pengguna yang masuk.

Mengirim permintaan keluar

OpenID Connect end_session_endpoint memungkinkan aplikasi Anda untuk mengirim permintaan ke platform identitas Microsoft guna mengakhiri sesi pengguna dan menghapus cookie yang ditetapkan oleh platform identitas Microsoft. Untuk sepenuhnya mengeluarkan pengguna dari aplikasi web, aplikasi Anda harus mengakhiri sesinya sendiri dengan pengguna tersebut (biasanya dengan menghapus cache token atau menghilangkan cookie), lalu mengalihkan browser ke:

https://login.microsoftonline.com/{tenant}/oauth2/v2.0/logout?post_logout_redirect_uri=https://localhost/myapp/
Parameter Jenis Deskripsi
tenant diperlukan Nilai {tenant} di jalur permintaan dapat digunakan untuk mengontrol siapa yang dapat masuk ke aplikasi. Nilai yang diizinkan adalah common, organizations, consumers, dan pengidentifikasi penyewa. Untuk detail selengkapnya, lihat dasar protokol.
post_logout_redirect_uri Disarankan URL yang harus dikembalikan pengguna setelah menyelesaikan proses keluar. Nilai ini harus cocok dengan salah satu URI pengalihan yang terdaftar untuk aplikasi. Jika tidak disertakan, pengguna akan ditunjukkan pesan generik oleh platform identitas Microsoft.

Langkah berikutnya