Kerangka dan batasan URI pengalihan (URL balasan)

Artikel
06/25/2024

Untuk memasukkan pengguna, aplikasi Anda harus mengirim permintaan masuk ke titik akhir otorisasi Microsoft Entra, dengan URI pengalihan yang ditentukan sebagai parameter. URI pengalihan adalah fitur keamanan penting yang memastikan server autentikasi Microsoft Entra hanya mengirim kode otorisasi dan token akses ke penerima yang dimaksudkan. Artikel ini menguraikan fitur dan pembatasan URI pengalihan di platform identitas Microsoft.

Apa itu URI pengalihan?

URI pengalihan, atau URL balasan, adalah lokasi di mana server autentikasi Microsoft Entra mengirim pengguna setelah mereka berhasil mengotorisasi dan diberi token akses. Untuk memasukkan pengguna, aplikasi Anda harus mengirim permintaan masuk dengan URI pengalihan yang ditentukan sebagai parameter, jadi setelah pengguna berhasil masuk, server autentikasi akan mengalihkan pengguna dan mengeluarkan token akses ke URI pengalihan yang ditentukan dalam permintaan masuk.

Mengapa URI pengalihan perlu ditambahkan ke pendaftaran aplikasi?

Untuk alasan keamanan, server autentikasi tidak akan mengalihkan pengguna atau mengirim token ke URI yang tidak ditambahkan ke pendaftaran aplikasi. Server masuk Microsoft Entra hanya mengalihkan pengguna dan mengirim token untuk mengalihkan URI yang telah ditambahkan ke pendaftaran aplikasi. Jika URI pengalihan yang ditentukan dalam permintaan masuk tidak cocok dengan URI pengalihan yang telah Anda tambahkan di aplikasi, Anda menerima pesan kesalahan seperti AADSTS50011: The reply URL specified in the request does not match the reply URLs configured for the application.

Untuk informasi selengkapnya tentang kode kesalahan, lihat Kode kesalahan autentikasi dan otorisasi Microsoft Entra.

Haruskah saya menambahkan URI pengalihan ke pendaftaran aplikasi?

Apakah Anda harus menambahkan URI pengalihan ke pendaftaran aplikasi bergantung pada protokol otorisasi yang digunakan aplikasi Anda. Anda harus menambahkan URI pengalihan yang sesuai ke pendaftaran aplikasi jika aplikasi Anda menggunakan protokol otorisasi berikut:

Anda tidak perlu menambahkan URI pengalihan ke pendaftaran aplikasi jika aplikasi Anda menggunakan protokol atau fitur otorisasi berikut.

Platform apa yang harus saya tambahkan URI pengalihan saya?

Jika aplikasi yang Anda buat berisi satu atau beberapa URI pengalihan dalam pendaftaran aplikasi, Anda perlu mengaktifkan konfigurasi alur klien publik. Tabel berikut memberikan panduan tentang jenis URI pengalihan yang harus atau tidak boleh Anda tambahkan berdasarkan platform tempat Anda membangun aplikasi.

Konfigurasi URI pengalihan aplikasi web

Jenis aplikasi Anda	Bahasa/Kerangka Kerja umum	Platform untuk menambahkan URI pengalihan di Pendaftaran Aplikasi
Aplikasi web tradisional tempat sebagian besar logika aplikasi dilakukan di server	Node.js, web, ASP.NET, Python, Java, ASP.NET Core, PHP, Ruby, Blazor Server	Web
Aplikasi satu halaman di mana sebagian besar logika antarmuka pengguna dilakukan di browser web yang berkomunikasi dengan server web terutama menggunakan API web	JavaScript, Angular, React, Blazor WebAssembly, Vue.js	Single-page application (SPA)

Konfigurasi URI pengalihan aplikasi seluler dan desktop

Jenis aplikasi Anda	Bahasa/Kerangka Kerja umum	Platform untuk menambahkan URI pengalihan di Pendaftaran Aplikasi
Aplikasi iOS atau macOS tidak termasuk skenario yang tercantum di bawah tabel ini	Swift, Objective-C, Xamarin	IOS/macOS
Aplikasi Android	Java, Kotlin, Xamarin	Android
Aplikasi yang berjalan secara asli di perangkat seluler atau komputer desktop	Node.js elektron, desktop Windows, UWP, React Native, Xamarin, Android, iOS/macOS	Aplikasi seluler dan desktop

Jika Anda membangun aplikasi iOS menggunakan salah satu metode berikut, gunakan platform Aplikasi seluler dan desktop untuk menambahkan URI pengalihan:

Aplikasi iOS menggunakan SDK warisan (ADAL)
Aplikasi iOS menggunakan SDK sumber terbuka (AppAuth)
Aplikasi iOS yang menggunakan teknologi lintas plat yang tidak kami dukung (Flutter)
Aplikasi iOS yang menerapkan protokol OAuth kami secara langsung
Aplikasi macOS menggunakan teknologi lintas plat yang tidak kami dukung (Electron)

Aplikasi yang tidak memerlukan URI pengalihan

Jenis aplikasi	Contoh/catatan	Alur OAuth terkait
Aplikasi yang berjalan pada perangkat yang tidak memiliki keyboard	Aplikasi yang berjalan di smart TV, perangkat IoT, atau printer	Alur kode perangkat mempelajari lebih lanjut
Aplikasi yang menangani kata sandi yang dimasukkan pengguna secara langsung, alih-alih mengalihkan pengguna ke situs web login yang dihosting Entra dan membiarkan Entra menangani kata sandi pengguna dengan cara yang aman.	Anda hanya boleh menggunakan alur ini ketika alur lain yang lebih aman seperti alur kode Otorisasi tidak layak karena tidak seaman.	Alur kredensial kata sandi pemilik sumber daya pelajari selengkapnya
Aplikasi desktop atau seluler yang berjalan di Windows atau pada komputer yang terhubung ke domain Windows (gabungan AD atau Azure AD) menggunakan Windows Integrated Auth Flow alih-alih pengelola akun Web	Aplikasi desktop atau seluler yang harus secara otomatis masuk setelah pengguna masuk ke sistem PC windows dengan kredensial Entra	Windows Integrated Auth Flow mempelajari lebih lanjut

Apa batasan URI pengalihan untuk aplikasi Microsoft Entra?

Model aplikasi Microsoft Entra menentukan batasan berikut untuk mengalihkan URI:

URI pengalihan harus dimulai dengan skema https, dengan pengecualian untuk beberapa URI pengalihan localhost .
URI pengalihan sensitif terhadap kasus dan harus sesuai dengan kasus jalur URL aplikasi yang Anda jalankan.

Contoh:
- Jika aplikasi Anda menyertakan sebagai bagian dari jalurnya .../abc/response-oidc, jangan tentukan .../ABC/response-oidc di URI pengalihan. Karena browser web memperlakukan jalur sebagai peka huruf besar/kecil, cookie yang terkait dengan .../abc/response-oidc dapat dikecualikan jika dialihkan ke URL .../ABC/response-oidc yang ukuran hurufnya tidak cocok.
URI pengalihan tidak dikonfigurasi dengan segmen jalur dikembalikan dengan garis miring ('/') sebagai tanggapan. Ini hanya berlaku jika mode respons adalah query atau fragment.

Contoh:
- https://contoso.com dikembalikan sebagai https://contoso.com/
- http://localhost:7071 dikembalikan sebagai http://localhost:7071/
URI pengalihan yang berisi segmen jalur tidak ditambahkan dengan garis miring di respons.

Contoh:
- https://contoso.com/abc dikembalikan sebagai https://contoso.com/abc
- https://contoso.com/abc/response-oidc dikembalikan sebagai https://contoso.com/abc/response-oidc
URI pengalihan tidak mendukung karakter khusus - ! $ ' ( ) , ;

Jumlah maksimum URI pengalihan dan panjang URI

Jumlah maksimum URI pengalihan tidak dapat dinaikkan karena alasan keamanan. Jika skenario Anda memerlukan lebih banyak URI pengalihan daripada jumlah maksimum yang diizinkan, pertimbangkan pendekatan parameter status berikut sebagai solusinya. Tabel berikut menunjukkan jumlah maksimum URI pengalihan yang dapat Anda tambahkan ke pendaftaran aplikasi di platform identitas Microsoft.

Akun yang sedang dimasuki	Jumlah maksimum URI pengalihan	Deskripsi
Akun kerja atau sekolah Microsoft di penyewa Microsoft Entra organisasi mana pun	256	Bidang `signInAudience` dalam manifes aplikasi diatur ke AzureADMyOrg atau AzureADMultipleOrgs
Akun Microsoft pribadi dan akun kantor dan sekolah	100	Bidang `signInAudience` dalam manifes aplikasi diatur ke AzureADandPersonalMicrosoftAccount

Anda dapat menggunakan maksimal 256 karakter untuk setiap URI pengalihan yang Anda tambahkan ke pendaftaran aplikasi.

Alihkan URI dalam aplikasi vs. objek perwakilan layanan

Selalu tambahkan URI pengalihan ke objek aplikasi saja.
Jangan pernah menambahkan nilai URI pengalihan ke perwakilan layanan karena nilai-nilai ini dapat dihapus ketika objek perwakilan layanan disinkronkan dengan objek aplikasi. Ini bisa terjadi karena operasi pembaruan apa pun yang memicu sinkronisasi antara dua objek.

Dukungan parameter kueri dalam URI pengalihan

Parameter kueri diizinkan dalam URI pengalihan untuk aplikasi yang hanya memasukkan pengguna dengan akun kerja atau sekolah.

Parameter kueri tidak diizinkan dalam URI pengalihan untuk pendaftaran aplikasi apa pun yang dikonfigurasi untuk memasukkan pengguna dengan akun Microsoft pribadi seperti Outlook.com (Hotmail), Messenger, OneDrive, MSN, Xbox Live, atau Microsoft 365.

Audiens kredensial masuk pendaftaran aplikasi	Mendukung parameter kueri dalam URI pengalihan
Khusus akun dalam direktori organisasi (khusus Contoso - Penyewa tunggal)
Akun di direktori organisasi apa pun (Direktori Microsoft Entra apa pun - Multipenyewa)
Akun di direktori organisasi apa pun (Direktori Microsoft Entra apa pun - Multipenyewa) dan akun Microsoft pribadi (seperti Skype dan Xbox)
Khusus akun Microsoft pribadi

Skema yang didukung

HTTPS: Skema HTTPS (https://) didukung untuk semua URI pengalihan berbasis HTTP.

HTTP: Skema HTTP (http://) didukung hanya untuk localhost URI dan hanya boleh digunakan selama pengembangan dan pengujian aplikasi lokal aktif.

Contoh URI pengalihan	Validitas
`https://contoso.com`	Sah
`https://contoso.com/abc/response-oidc`	Sah
`https://localhost`	Sah
`http://contoso.com/abc/response-oidc`	Tidak valid
`http://localhost`	Sah
`http://localhost/abc`	Sah

Pengecualian localhost

Per RFC 8252 bagian 8.3 dan 7.3, "loopback" atau "localhost" URI pengalihan dilengkapi dengan dua pertimbangan khusus:

Skema URI http dapat diterima karena pengalihan tidak pernah meninggalkan perangkat. Dengan demikian, kedua URI ini dapat diterima:
- http://localhost/myApp
- https://localhost/myApp
Karena rentang port sementara yang sering diperlukan oleh aplikasi asli, komponen port (misalnya, :5001 atau :443) diabaikan untuk tujuan mencocokkan URI pengalihan. Akibatnya, semua URI ini dianggap setara:
- http://localhost/MyApp
- http://localhost:1234/MyApp
- http://localhost:5000/MyApp
- http://localhost:8080/MyApp

Dari sudut pandang pengembangan, ini berarti beberapa hal:

Jangan mendaftarkan beberapa URI pengalihan saat hanya port yang berbeda. Server login memilih satu secara semena-mena dan menggunakan perilaku yang terkait dengan URI pengalihan tersebut (misalnya, apakah itu webpengalihan -, native-, atau spa-type).

Ini sangat penting ketika Anda ingin menggunakan alur autentikasi yang berbeda dalam pendaftaran aplikasi yang sama, misalnya pemberian kode otorisasi dan alur implisit. Untuk mengaitkan perilaku respons yang benar dengan setiap URI pengalihan, server login harus dapat membedakan antara URI pengalihan dan tidak dapat melakukannya ketika hanya port yang berbeda.
Untuk mendaftarkan beberapa URI pengalihan pada localhost untuk menguji alur yang berbeda selama pengembangan, bedakan menggunakan komponen jalur dari URI. Misalnya, http://localhost/MyWebApp tidak cocok dengan http://localhost/MyNativeApp.
Alamat loopback IPv6 ([::1]) saat ini tidak didukung.

Lebih menyukai 127.0.0.1 daripada localhost

Untuk mencegah aplikasi Anda rusak karena firewall yang salah dikonfigurasi atau antarmuka jaringan yang diganti namanya, gunakan alamat 127.0.0.1 loopback literal IP di URI pengalihan Anda alih-alih localhost. Contohnya,https://127.0.0.1.

Namun, Anda tidak dapat menggunakan kotak teks URI Pengalihan di portal Azure untuk menambahkan URI pengalihan berbasis loopback yang menggunakan http skema:

Dialog kesalahan di portal Microsoft Azure yang memperlihatkan URI pengalihan loopback berbasis http yang tidak diizinkan

Untuk menambah URI pengalihan yang menggunakan skema http dengan alamat loopback 127.0.0.1, Anda saat ini harus memodifikasi atribut replyUrlsWithType dalam manifes aplikasi.

Pembatasan kartubebas dalam URI pengalihan

URI kartubebas seperti https://*.contoso.com mungkin tampak nyaman, tetapi harus dihindari karena implikasi keamanan. Menurut spesifikasi OAuth 2.0 (bagian 3.1.2 dari RFC 6749), URI titik akhir pengalihan harus merupakan URI absolut. Dengan demikian, ketika URI kartubebas yang dikonfigurasi cocok dengan URI pengalihan, string kueri dan fragmen dalam URI pengalihan dilucuti.

Kartubebas URI saat ini tidak didukung dalam pendaftaran aplikasi yang dikonfigurasi untuk masuk ke akun Microsoft pribadi dan akun kantor atau sekolah. URI wildcard diizinkan, namun, untuk aplikasi yang dikonfigurasi untuk masuk hanya ke akun kerja atau sekolah di penyewa Microsoft Entra organisasi.

Untuk menambah UEI pengalihan dengan kartubebas ke pendaftaran aplikasi yang membawa masuk ke akun kantor atau sekolah, gunakan editor manifes aplikasi di Pendaftaran aplikasi di portal Microsoft Azure. Meskipun memungkinkan untuk mengatur URI pengalihan dengan kartubebas menggunakan editor manifes, kami sangat menyarankan Anda mematuhi bagian 3.1.2 RFC 6749. dan hanya menggunakan URI absolut.

Jika skenario Anda memerlukan lebih banyak URI pengalihan daripada batas maksimum yang diizinkan, pertimbangkan pendekatan parameter status berikut alih-alih menambah URI pengalihan kartubebas.

Menggunakan parameter status

Jika Anda memiliki beberapa subdomain dan skenario Anda mengharuskan bahwa, setelah autentikasi berhasil, Anda mengalihkan pengguna ke halaman yang sama dari tempanya memulai, menggunakan parameter status mungkin berguna.

Dalam pendekatan ini:

Buat URI pengalihan "bersama" per aplikasi untuk memproses token keamanan yang Anda terima dari titik akhir otorisasi.
Aplikasi Anda dapat mengirim parameter khusus aplikasi (seperti URL subdomain tempat pengguna berasal atau apa pun seperti informasi branding) di dalam parameter status. Saat menggunakan parameter status, jaga terhadap perlindungan CSRF seperti yang ditentukan dalam bagian 10.12 RFC 6749.
Parameter khusus aplikasi mencakup semua informasi yang diperlukan aplikasi untuk merender pengalaman yang benar bagi pengguna, yaitu, membangun status aplikasi yang sesuai. Titik akhir otorisasi Microsoft Entra menghapus HTML dari parameter status jadi pastikan Anda tidak meneruskan konten HTML dalam parameter ini.
Ketika MICROSOFT Entra ID mengirim respons ke URI pengalihan "bersama", ID tersebut akan mengirim parameter status kembali ke aplikasi.
Aplikasi kemudian dapat menggunakan nilai dalam parameter status untuk menentukan URL mana yang akan dikirim lebih lanjut kepada pengguna. Pastikan Anda memvalidasi perlindungan CSRF.

Peringatan

Pendekatan ini memungkinkan klien yang disusupi untuk memodifikasi parameter tambahan yang dikirim dalam parameter status, sehingga mengarahkan pengguna ke URL yang berbeda, yang merupakan ancaman pengalihan terbuka yang dijelaskan dalam RFC 6819. Oleh karena itu, klien harus melindungi parameter ini dengan mengenkripsi keadaan atau memverifikasinya dengan cara lain, seperti memvalidasi nama domain di URI pengalihan terhadap token.

Langkah berikutnya

Pelajari Manifes aplikasi pendaftaran aplikasi.

Bagikan melalui