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

Konfigurasi URI pengalihan untuk aplikasi mobile 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

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.

• URI pengalihan yang tidak dikonfigurasi dengan segmen jalur dikembalikan dengan garis miring akhir ('/') dalam 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 diberikan garis miring di akhir dalam 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 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.

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.

Pengecualian localhost

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

1. Skema URI http dapat diterima karena pengalihan tidak pernah meninggalkan perangkat. Dengan demikian, kedua URI ini dapat diterima:
   • http://localhost/myApp
   • https://localhost/myApp
2. 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 jenis spa-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 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 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:

1. Buat URI pengalihan "bersama" per aplikasi untuk memproses token keamanan yang Anda terima dari titik akhir otorisasi.
2. 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.
3. 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.
4. Ketika Microsoft Entra ID mengirimkan respons ke URI pengalihan "bersama pakai", itu akan mengirimkan kembali parameter status ke aplikasi.
5. Aplikasi kemudian dapat menggunakan nilai dalam parameter status untuk menentukan URL mana yang akan dikirim lebih lanjut kepada pengguna. Pastikan Anda memvalidasi perlindungan CSRF.

Langkah berikutnya

Pelajari pendaftaran aplikasi manifes aplikasi.