Kerangka dan batasan URI pengalihan (URL balasan)
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.
Dalam aplikasi web produksi, misalnya, URI pengalihan sering kali merupakan titik akhir publik tempat aplikasi Anda berjalan, seperti https://contoso.com/auth-response
. Selama pengembangan, biasanya juga menambahkan titik akhir tempat Anda menjalankan aplikasi secara lokal, seperti https://127.0.0.1/auth-response
atau http://localhost/auth-response
. Pastikan bahwa lingkungan pengembangan/URI pengalihan yang tidak perlu tidak terekspos di aplikasi produksi. Ini dapat dilakukan dengan memiliki pendaftaran aplikasi terpisah untuk pengembangan dan produksi.
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:
- Alur kode otorisasi OAuth 2.0
- Alur kredensial klien OAuth 2.0
- Alur pemberian izin implisit OAuth 2.0
- OpenID Connect
- Protokol SAML Single sign-on
Anda tidak perlu menambahkan URI pengalihan ke pendaftaran aplikasi jika aplikasi Anda menggunakan protokol atau fitur otorisasi berikut.
- Autentikasi Asli
- Alur kode perangkat OAuth 2.0
- Alur Atas Nama OAuth 2.0
- Alur kredensial kata sandi pemilik sumber daya OAuth 2.0
- Windows Integrated Auth Flow
- Penyedia Identitas (IdP) SAML 2.0 untuk Satu Kali Masuk
Ke platform apa saya harus menambahkan 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 | Aplikasi satu halaman (SPA) |
Konfigurasi URI pengalihan untuk aplikasi mobile dan desktop
Jenis aplikasi Anda | Bahasa/Kerangka Kerja umum | Platform untuk menambahkan URI pengalihan di Registrasi 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 Electron, 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 memakai teknologi lintas platform 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 yang terkait |
---|---|---|
Aplikasi yang berjalan pada perangkat yang tidak memiliki keyboard | Aplikasi yang berjalan di smart TV, perangkat IoT, atau printer | Alur kode perangkat pelajari 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
.../abc/response-oidc
sebagai bagian dari jalur, jangan cantumkan.../ABC/response-oidc
dalam URI pengalihan. Karena browser web menganggap jalur sebagai peka terhadap huruf besar/kecil, cookie yang terkait dengan.../abc/response-oidc
mungkin tidak digunakan jika dialihkan ke URL.../ABC/response-oidc
dengan perbedaan format huruf besar/kecil.
- Jika aplikasi Anda menyertakan
URI pengalihan yang tidak dikonfigurasi dengan segmen jalur dikembalikan dengan garis miring akhir ('
/
') dalam tanggapan. Ini hanya berlaku jika mode respons adalahquery
ataufragment
.Contoh:
-
https://contoso.com
dikembalikan sebagaihttps://contoso.com/
-
http://localhost:7071
dikembalikan sebagaihttp://localhost:7071/
-
URI pengalihan yang berisi segmen jalur tidak diberikan garis miring di akhir dalam respons.
Contoh:
-
https://contoso.com/abc
dikembalikan sebagaihttps://contoso.com/abc
-
https://contoso.com/abc/response-oidc
dikembalikan sebagaihttps://contoso.com/abc/response-oidc
-
URI tidak mendukung pengalihan karakter khusus -
! $ ' ( ) , ;
URI Pengalihan tidak mendukung Nama Domain Internasional
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 masuk | Jumlah maksimum URI pengalihan | Deskripsi |
---|---|---|
Akun kerja atau sekolah Microsoft di penyewa Microsoft Entra mana pun dalam organisasi | 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 disetel ke AzureADandPersonalMicrosoftAccount |
Anda dapat menggunakan maksimal 256 karakter untuk setiap URI pengalihan yang Anda tambahkan ke pendaftaran aplikasi.
Alihkan URI dalam aplikasi vs. objek pokok 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 pada 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 |
---|---|
Akun dalam direktori organisasi ini saja (hanya Contoso - Penyewa tunggal) | ![]() |
Akun di direktori organisasi apa pun (Direktori Microsoft Entra apa pun - Multi-tenant) | ![]() |
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, URI pengalihan "loopback" atau "localhost" 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 acak dan menggunakan perilaku yang terkait dengan URI pengalihan tersebut (misalnya, apakah itu
web
-,native
-, atau jenisspa
-pengalihan).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 denganhttp://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 skema http
.
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 wildcard seperti https://*.contoso.com
mungkin terlihat praktis, tetapi sebaiknya 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 wildcard yang dikonfigurasi cocok dengan URI pengalihan, string kueri dan fragmen dalam URI pengalihan dihilangkan.
Wildcard URI saat ini tidak didukung pada registrasi aplikasi yang dikonfigurasi untuk masuk menggunakan akun pribadi Microsoft dan akun kerja atau sekolah. URI wildcard diperbolehkan, namun, hanya untuk aplikasi yang dikonfigurasi agar masuk ke akun kerja atau sekolah di penyewa Microsoft Entra organisasi.
Untuk menambah URI pengalihan dengan wildcard ke pendaftaran aplikasi yang mengautentikasi akun kantor atau sekolah, gunakan editor manifes aplikasi di Pendaftaran aplikasi di portal Azure. Meskipun Anda dapat mengonfigurasi URI pengalihan dengan wildcard menggunakan editor manifes, kami sangat menyarankan Anda mematuhi bagian 3.1.2 dari RFC 6749. dan hanya menggunakan URI absolut.
Jika skenario Anda memerlukan lebih banyak URI pengalihan daripada batas maksimum yang diizinkan, pertimbangkan pendekatan parameter state berikut alih-alih menambah URI pengalihan wildcard.
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 mengirimkan respons ke URI pengalihan "bersama pakai", itu akan mengirimkan kembali parameter status 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 pendaftaran aplikasi manifes aplikasi.