Autentikasi dan otorisasi di Azure App Service dan Azure Functions

Azure App Service menyediakan kemampuan autentikasi bawaan (pengguna masuk) dan otorisasi (menyediakan akses ke data yang aman). Kemampuan ini terkadang disebut Easy Auth. Anda dapat menggunakannya untuk memasukkan pengguna dan mengakses data dengan menulis sedikit atau tanpa kode di aplikasi web, RESTful API, server seluler, dan fungsi Anda.

Artikel ini menjelaskan bagaimana Azure App Service membantu menyederhanakan autentikasi dan otorisasi untuk aplikasi Anda.

Alasan untuk menggunakan autentikasi bawaan

Untuk menerapkan autentikasi dan otorisasi, Anda dapat menggunakan fitur keamanan yang dibundel dalam kerangka kerja web pilihan Anda, atau Anda dapat menulis alat Anda sendiri. Menerapkan solusi yang aman untuk autentikasi dan otorisasi dapat mengambil upaya yang signifikan. Anda perlu mengikuti praktik dan standar terbaik industri. Anda juga perlu memastikan bahwa solusi Anda tetap terbarui dengan pembaruan keamanan, protokol, dan browser terbaru.

Kemampuan bawaan App Service dan Azure Functions dapat menghemat waktu dan upaya Anda dengan menyediakan autentikasi siap pakai dengan penyedia identitas federasi, sehingga Anda dapat fokus pada sisa aplikasi Anda.

Dengan App Service, Anda dapat mengintegrasikan kemampuan autentikasi ke dalam aplikasi web atau API Anda tanpa menerapkannya sendiri. Fitur ini dibangun langsung ke dalam platform dan tidak memerlukan bahasa, SDK, keahlian keamanan, atau kode tertentu. Anda dapat mengintegrasikannya dengan beberapa penyedia masuk, seperti Microsoft Entra, Facebook, Google, dan X.

Aplikasi Anda mungkin perlu mendukung skenario yang lebih kompleks, seperti integrasi Visual Studio atau persetujuan inkremental. Beberapa solusi autentikasi tersedia untuk mendukung skenario ini. Untuk mempelajari selengkapnya, lihat Skenario dan rekomendasi autentikasi.

Penyedia Identitas

App Service menggunakan identitas federasi. Penyedia identitas Microsoft atau non-Microsoft mengelola identitas pengguna dan alur autentikasi untuk Anda. Penyedia identitas berikut ini sudah secara otomatis tersedia:

Penyedia	Titik akhir untuk masuk	Panduan cara kerja
Microsoft Entra	/.auth/login/aad	Rincian masuk platform Microsoft Entra App Service
Facebook	/.auth/login/facebook	Masuk dengan Facebook di App Service
Google	/.auth/login/google	Masuk App Service dengan Google
X	/.auth/login/x	Rincian masuk App Service X
GitHub	/.auth/login/github	Masuk dengan GitHub pada App Service
Apel	/.auth/login/apple	Masuk App Service melalui Masuk dengan Apple (pratinjau)
Setiap penyedia OpenID Connect	/.auth/login/<providerName>	Masuk ke OpenID Connect App Service

Saat Anda mengonfigurasi fitur ini dengan salah satu penyedia ini, titik akhir masuknya tersedia untuk autentikasi pengguna dan untuk validasi token autentikasi dari penyedia. Anda dapat memberi pengguna Anda sejumlah opsi masuk ini.

Pertimbangan untuk menggunakan autentikasi bawaan

Mengaktifkan autentikasi bawaan menyebabkan semua permintaan ke aplikasi Anda dialihkan secara otomatis ke HTTPS, terlepas dari pengaturan konfigurasi App Service untuk memberlakukan HTTPS. Anda dapat menonaktifkan pengalihan otomatis ini dengan menggunakan requireHttps pengaturan dalam konfigurasi V2. Namun, kami sarankan Anda tetap menggunakan HTTPS dan memastikan bahwa tidak ada token keamanan yang pernah ditransmisikan melalui koneksi HTTP yang tidak aman.

Anda dapat menggunakan App Service untuk autentikasi dengan atau tanpa membatasi akses ke konten situs dan API Anda. Atur pembatasan akses di bagian> PengaturanPengaturan Autentikasi>Autentikasi aplikasi web Anda:

• Untuk membatasi akses aplikasi hanya ke pengguna terautentikasi, atur Tindakan yang harus diambil saat permintaan tidak diautentikasi untuk masuk dengan salah satu penyedia identitas yang dikonfigurasi.
• Untuk mengautentikasi tetapi tidak membatasi akses, atur Tindakan yang harus diambil saat permintaan tidak diautentikasi ke Izinkan permintaan anonim (tanpa tindakan).

Penting

Anda harus memberikan setiap pendaftaran aplikasi izin dan persetujuannya sendiri. Hindari berbagi izin antar lingkungan dengan menggunakan pendaftaran aplikasi terpisah untuk slot penyebaran terpisah. Saat Anda menguji kode baru, praktik ini dapat membantu mencegah masalah memengaruhi aplikasi produksi.

Cara kerjanya

Arsitektur fitur

Komponen middleware autentikasi dan otorisasi adalah fitur platform yang berjalan pada komputer virtual yang sama dengan aplikasi Anda. Saat Anda mengaktifkannya, setiap permintaan HTTP masuk melewati komponen tersebut sebelum aplikasi Anda menanganinya.

Platform middleware menangani beberapa hal untuk aplikasi Anda:

• Mengautentikasi pengguna dan klien dengan penyedia identitas yang ditentukan
• Mengonfirmasi, menyimpan, dan memperbarui token OAuth yang dikeluarkan oleh penyedia identitas yang dikonfigurasi.
• Mengelola sesi yang terautentikasi
• Masukkan informasi identitas ke header permintaan HTTP

Modul berjalan secara terpisah dari kode aplikasi Anda. Anda dapat mengonfigurasinya dengan menggunakan pengaturan Azure Resource Manager atau dengan menggunakan file konfigurasi. Tidak diperlukan SDK, bahasa pemrograman tertentu, atau perubahan pada kode aplikasi Anda.

Arsitektur fitur pada Windows (penyebaran non-kontainer)

Modul autentikasi dan otorisasi berjalan sebagai modul IIS dalam lingkungan pemrosesan yang sama dengan aplikasi Anda. Saat Anda mengaktifkannya, setiap permintaan HTTP masuk melewatinya sebelum aplikasi Anda menanganinya.

Arsitektur fitur di Linux dan kontainer

Modul autentikasi dan otorisasi berjalan dalam kontainer terpisah yang diisolasi dari kode aplikasi Anda. Modul ini menggunakan pola Duta Besar untuk berinteraksi dengan lalu lintas masuk untuk melakukan fungsionalitas serupa seperti pada Windows. Karena tidak berjalan dalam proses, tidak ada integrasi langsung dengan kerangka kerja bahasa tertentu yang bisa dilakukan. Namun, informasi relevan yang dibutuhkan aplikasi Anda diteruskan di header permintaan.

Proses autentikasi

Alur autentikasi sama untuk semua penyedia. Ini berbeda tergantung pada apakah Anda ingin masuk dengan SDK penyedia:

• Tanpa penyedia SDK: Aplikasi mendelegasikan masuk federasi ke App Service. Delegasi ini biasanya dilakukan pada aplikasi browser, yang dapat menyajikan halaman masuk penyedia layanan kepada pengguna. Kode server mengelola proses masuk, sehingga juga disebut alur yang diarahkan server atau alur server.

  Kasus ini berlaku untuk aplikasi browser dan aplikasi seluler yang menggunakan browser yang disematkan untuk autentikasi.

• Dengan penyedia SDK: Aplikasi menanda-tangani pengguna ke penyedia secara manual. Kemudian mengirimkan token autentikasi ke App Service untuk validasi. Proses ini biasanya terjadi pada aplikasi tanpa browser, yang tidak dapat menyajikan halaman masuk penyedia kepada pengguna. Kode aplikasi mengelola proses masuk, sehingga juga disebut alur yang diarahkan klien atau alur klien.

  Kasus ini berlaku untuk REST API, Azure Functions, dan klien browser JavaScript, selain aplikasi browser yang membutuhkan lebih banyak fleksibilitas dalam proses masuk. Ini juga berlaku untuk aplikasi seluler asli yang memasukkan pengguna dengan menggunakan SDK penyedia.

Panggilan dari aplikasi browser tepercaya di App Service ke REST API lain di App Service atau Azure Functions dapat diautentikasi melalui alur yang diarahkan server. Untuk informasi selengkapnya, lihat Mengkustomisasi masuk dan keluar dalam autentikasi Azure App Service.

Tabel berikut ini memperlihatkan langkah-langkah alur autentikasi.

Langkah	Tanpa penyedia SDK	Dengan SDK dari penyedia
1. Masuk pengguna	Penyedia mengalihkan klien ke /.auth/login/<provider>.	Kode klien langsung masuk sebagai pengguna dengan menggunakan SDK penyedia dan menerima token autentikasi. Untuk informasi selengkapnya, lihat dokumentasi penyedia.
2. Melakukan pasca-autentikasi	Penyedia mengalihkan klien ke /.auth/login/<provider>/callback.	Kode klien memposting token dari penyedia ke /.auth/login/<provider> untuk validasi.
3. Buat sesi terautentikasi	App Service menambahkan cookie terautentikasi ke respons.	App Service mengembalikan token autentikasinya sendiri ke kode klien.
4. Menyajikan konten yang diautentikasi	Klien menyertakan cookie autentikasi dalam permintaan berikutnya (ditangani secara otomatis oleh browser).	Kode klien menyajikan token autentikasi di X-ZUMO-AUTH header.

Untuk browser klien, App Service dapat secara otomatis mengarahkan semua pengguna yang tidak diautentikasi ke /.auth/login/<provider>. Anda juga dapat menyajikan pengguna dengan satu atau beberapa /.auth/login/<provider> tautan untuk masuk ke aplikasi Anda dengan menggunakan penyedia pilihan mereka.

Perilaku otorisasi

Di portal Microsoft Azure, Anda dapat mengonfigurasi App Service dengan berbagai perilaku saat permintaan masuk tidak diautentikasi. Bagian berikut ini menjelaskan opsi.

Penting

Secara default, fitur ini hanya menyediakan autentikasi, bukan otorisasi. Aplikasi Anda mungkin masih perlu membuat keputusan otorisasi, selain pemeriksaan apa pun yang Anda konfigurasi di sini.

Akses terbatas

• Izinkan permintaan tanpa otentikasi: Opsi ini menyerahkan otorisasi lalu lintas tanpa otentikasi kepada kode aplikasi Anda. Untuk permintaan terautentikasi, App Service juga meneruskan informasi autentikasi di header HTTP.

  Opsi ini memberikan lebih banyak fleksibilitas dalam menangani permintaan anonim. Misalnya, ini memungkinkan Anda menyajikan beberapa penyedia masuk kepada pengguna Anda. Namun, Anda harus menulis kode.

• Memerlukan autentikasi: Opsi ini akan menolak lalu lintas apa pun yang tidak diautentikasi ke aplikasi Anda. Tindakan khusus yang harus diambil ditentukan di bagian Permintaan yang tidak diautentikasi nanti di artikel ini.

  Dengan opsi ini, Anda tidak perlu menulis kode autentikasi apa pun di aplikasi Anda. Anda dapat menangani otorisasi yang lebih halus, seperti otorisasi khusus peran, dengan memeriksa klaim pengguna.

  Perhatian

  Membatasi akses dengan cara ini berlaku untuk semua panggilan ke aplikasi Anda, yang mungkin tidak diinginkan untuk aplikasi yang menginginkan halaman beranda yang tersedia untuk umum, seperti dalam banyak aplikasi satu halaman. Jika pengecualian diperlukan, Anda perlu mengonfigurasi jalur yang dikecualikan dalam file konfigurasi.

  Catatan

  Saat menggunakan Penyedia Identitas Microsoft untuk pengguna di organisasi Anda, perilaku defaultnya adalah setiap pengguna di penyewa Microsoft Entra Anda dapat meminta token untuk aplikasi Anda. Anda dapat mengonfigurasi aplikasi di Microsoft Entra jika Anda ingin membatasi akses ke aplikasi Anda ke sekumpulan pengguna yang ditentukan. App Service juga menawarkan beberapa pemeriksaan otorisasi bawaan dasar yang dapat membantu beberapa validasi. Untuk mempelajari selengkapnya tentang otorisasi di Microsoft Entra, lihat Dasar-dasar otorisasi Microsoft Entra.

Permintaan yang tidak terautentikasi

• Pengalihan HTTP 302 Found: direkomendasikan untuk situs web: Mengalihkan tindakan ke salah satu penyedia identitas yang telah dikonfigurasi. Dalam kasus ini, klien browser dialihkan ke /.auth/login/<provider> penyedia yang Anda pilih.
• HTTP 401 Tidak Sah: direkomendasikan untuk API: Mengembalikan HTTP 401 Unauthorized respons jika permintaan anonim berasal dari aplikasi mobile asli. Anda juga dapat mengonfigurasi penolakan HTTP 401 Unauthorized untuk semua permintaan.
• HTTP 403 Terlarang: Mengonfigurasi penolakan HTTP 403 Forbidden untuk semua permintaan.
• HTTP 404 Tidak ditemukan: Mengonfigurasi penolakan HTTP 404 Not found untuk semua permintaan.

Toko token

App Service menyediakan penyimpanan token bawaan. Penyimpanan token adalah repositori token yang terkait dengan pengguna aplikasi web, API, atau aplikasi seluler asli Anda. Saat Anda mengaktifkan autentikasi dengan penyedia mana pun, penyimpanan token ini segera tersedia untuk aplikasi Anda.

Jika kode aplikasi Anda perlu mengakses data dari penyedia ini atas nama pengguna, Anda biasanya harus menulis kode untuk mengumpulkan, menyimpan, dan merefresh token ini di aplikasi Anda. Tindakan mungkin mencakup:

• Posting ke linimasa Facebook pengguna terautentikasi.
• Baca data perusahaan pengguna dengan menggunakan Microsoft Graph API.

Dengan penyimpanan token, Anda cukup mengambil token ketika Anda membutuhkannya dan memberi tahu App Service untuk memperbaruinya ketika kadaluarsa.

Token ID, token akses, dan token refresh di-cache untuk sesi yang terautentikasi. Hanya pengguna terkait yang dapat mengaksesnya.

Jika Anda tidak perlu bekerja dengan token di aplikasi, Anda dapat menonaktifkan penyimpanan token di halamanAutentikasi> aplikasi.

Pencatatan dan pelacakan

Jika Anda mengaktifkan pengelogan aplikasi, jejak autentikasi dan otorisasi muncul langsung di file log Anda. Jika Anda melihat kesalahan autentikasi yang tidak Anda harapkan, Anda dapat dengan mudah menemukan semua detail dengan melihat log aplikasi yang ada.

Jika Anda mengaktifkan pelacakan permintaan yang gagal, Anda dapat melihat dengan tepat peran apa yang mungkin dimainkan modul autentikasi dan otorisasi dalam permintaan yang gagal. Dalam catatan jejak, cari referensi ke modul bernama EasyAuthModule_32/64.

Mitigasi pemalsuan permintaan lintas situs

Autentikasi App Service mengurangi pemalsuan permintaan lintas situs dengan memeriksa permintaan klien untuk kondisi berikut:

• Ini adalah permintaan yang diautentikasi melalui POST cookie sesi.
• Permintaan berasal dari browser yang diketahui, seperti yang ditentukan oleh header HTTP User-Agent .
• Header HTTP Origin atau HTTP Referer hilang atau tidak ada dalam daftar domain eksternal yang disetujui yang dikonfigurasi untuk pengalihan.
• Header HTTP Origin hilang atau tidak termasuk dalam daftar asal pembagian sumber daya lintas asal (CORS) yang dikonfigurasi.

Ketika permintaan memenuhi semua kondisi ini, autentikasi App Service secara otomatis menolaknya. Anda dapat mengatasi logika mitigasi ini dengan menambahkan domain eksternal Anda ke daftar pengalihan di Pengaturan>Autentikasi Edit Autentikasi>pengaturan>URL pengalihan eksternal yang diizinkan.

Metadata sumber daya yang dilindungi (pratinjau)

App Service dapat melayani metadata sumber daya yang dilindungi OAuth 2.0, seperti yang didefinisikan dalam RFC 9728. Ini dapat membantu klien OAuth 2.0 memahami cara berinteraksi dengan aplikasi Anda. Ini diperlukan untuk otorisasi server Model Context Protocol (MCP).

Catatan

Dukungan untuk metadata sumber daya yang dilindungi saat ini dalam pratinjau, dan cara Anda mengonfigurasinya dapat berubah sebelum fitur tersedia secara umum.

Selama periode pratinjau, Anda dapat mengaktifkan dokumen metadata sumber daya yang dilindungi default dengan mengonfigurasi WEBSITE_AUTH_PRM_DEFAULT_WITH_SCOPESpengaturan aplikasi dengan daftar cakupan yang dipisahkan koma yang diperlukan oleh aplikasi. Misalnya, ketika Anda membiarkan App Service mengonfigurasi penyedia Microsoft Entra untuk Anda, app Service akan menyiapkan cakupan seperti api://<client-id>/user_impersonation, mengganti <client-id> dengan ID klien aktual pendaftaran aplikasi Anda.

Dokumen metadata sumber daya default yang dilindungi mencakup properti berikut:

Harta benda	Description
resource	URI sumber daya yang sesuai dengan titik akhir tempat metadata sumber daya yang dilindungi diakses.
authorization_servers	Daftar server otorisasi untuk penyedia identitas yang telah Anda konfigurasi.
scopes_supported	Daftar cakupan yang Anda tentukan dalam WEBSITE_AUTH_PRM_DEFAULT_WITH_SCOPES pengaturan aplikasi.

Properti tambahan tidak didukung saat menggunakan konfigurasi default.

Mengonfigurasi dokumen metadata sumber daya yang dilindungi default juga mengubah cara App Service menangani permintaan api yang tidak diautentikasi. Saat aplikasi mengeluarkan tantangan otorisasi, aplikasi menyertakan URL metadata sumber daya yang dilindungi, yang kemudian dapat diambil dan diproses klien. Tantangan ini juga mencakup cakupan yang Anda konfigurasikan WEBSITE_AUTH_PRM_DEFAULT_WITH_SCOPES dalam pengaturan aplikasi.

Pertimbangan untuk menggunakan Azure Front Door

Saat Anda menggunakan Azure App Service dengan autentikasi di belakang Azure Front Door atau proksi terbalik lainnya, harap pertimbangkan langkah-langkah berikut.

Menonaktifkan penyimpanan cache Azure Front Door

Nonaktifkan cache Azure Front Door untuk alur kerja otentikasi.

Gunakan titik akhir Azure Front Door untuk pengalihan

App Service biasanya tidak dapat diakses secara langsung saat diekspos oleh Azure Front Door. Anda dapat mencegah perilaku ini, misalnya, dengan mengekspos App Service dengan menggunakan Azure Private Link di Azure Front Door Premium. Untuk mencegah alur kerja autentikasi mengalihkan lalu lintas kembali ke App Service secara langsung. Untuk informasi selengkapnya, lihat Mengalihkan URI.

Pastikan App Service menggunakan URI pengalihan yang tepat

Dalam beberapa konfigurasi, App Service menggunakan nama domain yang sepenuhnya memenuhi syarat (FQDN) sebagai URI pengalihan, bukan Azure Front Door FQDN. Konfigurasi ini menyebabkan masalah ketika klien dialihkan ke App Service alih-alih Azure Front Door. Untuk mengubahnya, atur forwardProxy ke Standard agar App Service dapat mematuhi header X-Forwarded-Host yang ditetapkan oleh Azure Front Door.

Proksi terbalik lainnya, seperti Azure Application Gateway atau produk non-Microsoft, mungkin menggunakan header yang berbeda dan memerlukan pengaturan forwardProxy yang berbeda.

Anda tidak dapat mengubah forwardProxy konfigurasi dengan menggunakan portal Microsoft Azure. Anda perlu menggunakan az rest.

Ekspor pengaturan

az rest --uri /subscriptions/REPLACE-ME-SUBSCRIPTIONID/resourceGroups/REPLACE-ME-RESOURCEGROUP/providers/Microsoft.Web/sites/REPLACE-ME-APPNAME/config/authsettingsV2?api-version=2020-09-01 --method get > auth.json

Perbarui pengaturan

Cari:

"httpSettings": {
  "forwardProxy": {
    "convention": "Standard"
  }
}

Pastikan convention diatur menjadi Standard untuk menghormati header X-Forwarded-Host yang digunakan oleh Azure Front Door.

Pengaturan impor

az rest --uri /subscriptions/REPLACE-ME-SUBSCRIPTIONID/resourceGroups/REPLACE-ME-RESOURCEGROUP/providers/Microsoft.Web/sites/REPLACE-ME-APPNAME/config/authsettingsV2?api-version=2020-09-01 --method put --body @auth.json

Jenis klien dan perilaku alur OAuth

Klien rahasia vs. publik

Ketika rahasia klien dikonfigurasi untuk penyedia identitas, autentikasi App Service (Easy Auth) bertindak sebagai klien tepercaya. Untuk ID Microsoft Entra khususnya:

• Dengan rahasia klien yang dikonfigurasi: App Service menggunakan aliran hibrid (response_type=code id_token). Dalam alur ini, App Service menukar kode otorisasi dengan token menggunakan sandi rahasia, yang menjamin sandi rahasia tersebut tetap aman di sisi server.
• Tanpa rahasia klien yang dikonfigurasi: App Service kembali ke alur implisit (response_type=id_token). Dalam alur ini, token ID dikembalikan langsung di pengalihan tanpa pertukaran kode.

Jika skenario Anda memerlukan alur klien rahasia dengan pertukaran token aman, pastikan rahasia klien dikonfigurasi untuk penyedia identitas di pengaturan autentikasi App Service Anda.

Dukungan PKCE (Proof Key for Code Exchange)

Autentikasi App Service tidak menghasilkan parameter PKCE (code_verifier dan code_challenge) sendiri. Namun, ini mendukung PKCE jika klien menyediakan parameter saat memulai alur masuk.

Untuk menggunakan PKCE, sertakan kedua parameter code_challenge dan code_challenge_method saat Anda mengarahkan pengguna ke endpoint sign-in.

https://<your-app>.azurewebsites.net/.auth/login/<provider>?code_challenge=<value>&code_challenge_method=<method>

Kedua parameter harus disediakan bersama-sama. Jika hanya satu parameter yang disediakan, App Service menolak permintaan.

Untuk mengetahui nilai code_challenge_method yang didukung server otorisasi, lihat code_challenge_methods_supported di Metadata Server Otorisasi yang berisi metode tantangan PKCE yang didukung.

RFC 7636 mendefinisikan dua metode untuk menghasilkan code_challenge dari code_verifier:

• plain code_challenge: sama dengan code_verifier (code_challenge = code_verifier). Metode ini mengirimkan nilai pemverifikasi secara langsung tanpa transformasi apa pun. Gunakan plain hanya jika klien tidak dapat mendukung SHA-256 karena alasan teknis.
• S256 (disarankan): code_challenge adalah hash SHA-256 yang dikodekan Base64url dari code_verifier (code_challenge = BASE64URL(SHA256(ASCII(code_verifier)))). Metode ini lebih aman karena aslinya code_verifier tidak pernah diekspos selama permintaan otorisasi.

code_verifier harus berupa string acak kriptografis antara 43 dan 128 karakter, hanya menggunakan karakter yang tidak dipesan: A-Z, a-z, 0-9, -, ., _, dan ~.

Untuk informasi selengkapnya tentang cara kerja alur kode otorisasi dengan PKCE, lihat Platform identitas Microsoft dan alur kode otorisasi OAuth 2.0.

Konten terkait

Untuk informasi selengkapnya tentang autentikasi App Service, lihat:

• Konfigurasikan App Service atau aplikasi Azure Functions Anda untuk menggunakan autentikasi Microsoft Entra
• Mengkustomisasi masuk dan keluar di autentikasi Azure App Service
• Bekerja dengan token OAuth di autentikasi Azure App Service
• Bekerja dengan identitas pengguna di autentikasi Azure App Service
• Konfigurasi berbasis file dalam autentikasi Azure App Service

Untuk sampel, lihat:

• Mulai cepat: Menambahkan autentikasi aplikasi ke aplikasi web Anda yang berjalan di Azure App Service
• Tutorial: Mengautentikasi dan mengotorisasi pengguna secara end to end di Azure App Service
• Integrasi .NET Core dari Azure AppService Easy Auth (konten GitHub non-Microsoft)
• Membuat autentikasi Azure App Service berfungsi dengan .NET Core (konten GitHub non-Microsoft)