Tutorial: Autentikasi Azure SignalR Service dengan Azure Functions

Dalam tutorial langkah demi langkah ini, Anda membangun ruang obrolan dengan autentikasi dan olahpesan privat dengan menggunakan teknologi ini:

• Azure Functions: API back-end untuk mengautentikasi pengguna dan mengirim pesan obrolan.
• Azure SignalR Service: Layanan untuk menyiarkan pesan baru ke klien obrolan yang terhubung.
• Azure Storage: Layanan penyimpanan yang diperlukan Azure Functions.
• Azure App Service: Layanan yang menyediakan autentikasi pengguna.

Model v4

Catatan

Anda bisa mendapatkan kode yang disebutkan dalam artikel ini dari GitHub.

Model v3

Catatan

Anda bisa mendapatkan kode yang disebutkan dalam artikel ini dari GitHub.

Penting

String koneksi mentah muncul dalam artikel ini hanya untuk tujuan demonstrasi.

string koneksi menyertakan informasi otorisasi yang diperlukan aplikasi Anda untuk mengakses Azure SignalR Service. Kunci akses di dalam string koneksi mirip dengan kata sandi root untuk layanan Anda. Di lingkungan produksi, selalu lindungi kunci akses Anda. Gunakan Azure Key Vault untuk mengelola dan memutar kunci Anda dengan aman dan mengamankan string koneksi Anda menggunakan ID Microsoft Entra dan mengotorisasi akses dengan ID Microsoft Entra.

Hindari mendistribusikan kunci akses ke pengguna lain, melakukan hard-coding, atau menyimpannya di mana saja dalam teks biasa yang dapat diakses orang lain. Putar kunci Anda jika Anda yakin bahwa kunci tersebut mungkin telah disusupi.

Prasyarat

• Akun Azure dengan langganan aktif. Jika Anda tidak memilikinya, Anda dapat membuatnya secara gratis.
• Node.js (versi 20.x).
• Azure Functions Core Tools (versi 4).

Mengalami masalah? Beri tahu kami.

Membuat sumber daya penting di Azure

Membuat sumber daya Azure SignalR Service

Aplikasi Anda akan mengakses instans Azure SignalR Service. Gunakan langkah-langkah berikut untuk membuat instans Azure SignalR Service dengan menggunakan portal Azure:

1. Di portal Azure, pilih tombol Buat sumber daya (+).

2. Cari dan pilih SignalR Service.

3. Pilih Buat.

4. Masukkan informasi berikut.

   Nama	Nilai
   Grup sumber daya	Buat grup sumber daya baru dengan nama unik.
   Nama sumber daya	Masukkan nama unik untuk instans Azure SignalR Service.
   Wilayah	Pilih wilayah yang dekat dengan Anda.
   Tingkatan harga	Pilih Gratis.
   Mode layanan	Pilih Tanpa Server.

5. Pilih Tinjau + Buat.

6. Pilih Buat.

Mengalami masalah? Beri tahu kami.

Membuat aplikasi fungsi Azure dan akun penyimpanan Azure

1. Dari beranda di portal Azure, pilih Buat sumber daya (+).

2. Cari Aplikasi Fungsi dan pilih.

3. Pilih Buat.

4. Masukkan informasi berikut.

   Nama	Nilai
   Grup sumber daya	Gunakan grup sumber daya yang sama dengan instans Azure SignalR Service Anda.
   Nama Aplikasi Fungsi	Masukkan nama unik untuk aplikasi fungsi.
   Tumpukan runtime	Pilih Node.js.
   Wilayah	Pilih wilayah yang dekat dengan Anda.

5. Secara default, akun penyimpanan Azure baru dibuat dalam grup sumber daya yang sama bersama dengan aplikasi fungsi Anda. Jika Anda ingin menggunakan akun penyimpanan lain di aplikasi fungsi, beralihlah ke tab Hosting untuk memilih akun.

6. Pilih Tinjauan + Buat, kemudian pilih Buat.

Membuat proyek Azure Functions secara lokal

Menginisialisasi aplikasi fungsi

1. Dari baris perintah, buat folder akar untuk proyek Anda dan ubah ke folder .

2. Jalankan perintah berikut di terminal Anda untuk membuat proyek JavaScript Functions baru:

Model v4

func init --worker-runtime node --language javascript --name my-app --model V4

Model v3

func init --worker-runtime node --language javascript --name my-app --model V3

Secara default, proyek yang dihasilkan menyertakan file host.json yang berisi bundel ekstensi yang menyertakan ekstensi SignalR. Untuk informasi selengkapnya, lihat Bundel ekstensi Azure Functions.

Mengonfigurasi pengaturan aplikasi

Saat Anda menjalankan dan men-debug runtime Azure Functions secara lokal, aplikasi fungsi membaca pengaturan aplikasi dari local.settings.json. Perbarui file ini dengan string koneksi instans Azure SignalR Service dan akun penyimpanan yang Anda buat sebelumnya.

String koneksi mentah muncul dalam artikel ini hanya untuk tujuan demonstrasi. Di lingkungan produksi, selalu lindungi kunci akses Anda. Gunakan Azure Key Vault untuk mengelola dan memutar kunci Anda dengan aman dan mengamankan string koneksi Anda menggunakan ID Microsoft Entra dan mengotorisasi akses dengan ID Microsoft Entra.

Ganti konten local.settings.json dengan kode berikut:

{
  "IsEncrypted": false,
  "Values": {
    "FUNCTIONS_WORKER_RUNTIME": "node",
    "AzureWebJobsStorage": "<your-storage-account-connection-string>",
    "AzureSignalRConnectionString": "<your-Azure-SignalR-connection-string>"
  }
}

Dalam kode sebelumnya:

• Masukkan string koneksi Azure SignalR Service ke AzureSignalRConnectionString dalam pengaturan.

  Untuk mendapatkan string, buka instans Azure SignalR Service Anda di portal Azure. Di bagian Pengaturan , temukan pengaturan Kunci . Pilih tombol Salin di sebelah kanan string koneksi untuk menyalinnya ke clipboard Anda. Anda dapat menggunakan string koneksi primer atau sekunder.

• Masukkan akun penyimpanan string koneksi ke AzureWebJobsStorage pengaturan.

  Untuk mendapatkan string, buka akun penyimpanan Anda di portal Azure. Di bagian Keamanan + jaringan, temukan pengaturan Kunci akses. Pilih tombol Salin di sebelah kanan string koneksi untuk menyalinnya ke clipboard Anda. Anda dapat menggunakan string koneksi primer atau sekunder.

Mengalami masalah? Beri tahu kami.

Membuat fungsi untuk mengautentikasi pengguna ke Azure SignalR Service

Saat aplikasi obrolan pertama kali dibuka di browser, aplikasi ini memerlukan info masuk koneksi yang valid untuk terhubung ke Azure SignalR Service. Buat fungsi pemicu HTTP bernama negotiate di aplikasi fungsi Anda untuk mengembalikan informasi koneksi ini.

Catatan

Fungsi ini harus dinamai negotiate karena klien SignalR memerlukan titik akhir yang berakhiran /negotiate.

Model v4

1. Dari folder proyek akar, buat negotiate fungsi dari templat bawaan dengan menggunakan perintah berikut:

   func new --template "HTTP trigger" --name negotiate
   

2. Buka src/functions/negotiate.js, perbarui konten sebagai berikut:

   const { app, input } = require('@azure/functions');
   
   const inputSignalR = input.generic({
       type: 'signalRConnectionInfo',
       name: 'connectionInfo',
       hubName: 'default',
       connectionStringSetting: 'AzureSignalRConnectionString',
   });
   
   app.post('negotiate', {
       authLevel: 'anonymous',
       handler: (request, context) => {
           return { body: JSON.stringify(context.extraInputs.get(inputSignalR)) }
       },
       route: 'negotiate',
       extraInputs: [inputSignalR],
   });
   

   Fungsi ini berisi pengikatan pemicu HTTP untuk menerima permintaan dari klien SignalR. Fungsi ini juga berisi pengikatan input SignalR untuk menghasilkan kredensial yang valid bagi klien untuk terhubung ke hub Azure SignalR Service bernama default.

   Fungsi ini mengambil informasi koneksi SignalR dari pengikatan input dan mengembalikannya ke klien di isi respons HTTP..

   Tidak ada userId properti dalam pengikatan signalRConnectionInfo untuk pengembangan lokal. Anda akan menambahkannya nanti untuk mengatur nama pengguna koneksi SignalR saat Anda menyebarkan aplikasi fungsi ke Azure.

Model v3

1. Dari folder proyek akar, buat negotiate fungsi dari templat bawaan dengan menggunakan perintah berikut:

   func new --template "SignalR negotiate HTTP trigger" --name negotiate
   

2. Buka negosiasi/function.json untuk melihat konfigurasi pengikatan fungsi.

   Fungsi ini berisi pengikatan pemicu HTTP untuk menerima permintaan dari klien SignalR. Fungsi ini juga berisi pengikatan input SignalR untuk menghasilkan kredensial yang valid bagi klien untuk terhubung ke hub Azure SignalR Service bernama default.

   {
     "disabled": false,
     "bindings": [
       {
         "authLevel": "anonymous",
         "type": "httpTrigger",
         "direction": "in",
         "methods": ["post"],
         "name": "req",
         "route": "negotiate"
       },
       {
         "type": "http",
         "direction": "out",
         "name": "res"
       },
       {
         "type": "signalRConnectionInfo",
         "name": "connectionInfo",
         "hubName": "default",
         "connectionStringSetting": "AzureSignalRConnectionString",
         "direction": "in"
       }
     ]
   }
   

   Tidak ada userId properti dalam pengikatan signalRConnectionInfo untuk pengembangan lokal. Anda akan menambahkannya nanti untuk mengatur nama pengguna koneksi SignalR saat Anda menyebarkan aplikasi fungsi ke Azure.

3. Tutup file negosiasi/function.json.

4. Buka negosiasi/index.js untuk melihat isi fungsi:

   module.exports = async function (context, req, connectionInfo) {
     context.res.body = connectionInfo;
   };
   

   Fungsi ini mengambil informasi koneksi SignalR dari pengikatan input dan mengembalikannya ke klien dalam isi respons HTTP. Klien SignalR menggunakan informasi ini untuk menyambungkan ke instans Azure SignalR Service.

Mengalami masalah? Beri tahu kami.

Membuat fungsi untuk mengirim pesan obrolan

Aplikasi web juga memerlukan HTTP API untuk mengirim pesan obrolan. Buat fungsi pemicu HTTP yang mengirim pesan ke semua klien yang terhubung yang menggunakan Azure SignalR Service:

Model v4

1. Dari folder proyek akar, buat fungsi pemicu HTTP bernama sendMessage dari templat dengan menggunakan perintah berikut:

   func new --name sendMessage --template "Http trigger"
   

2. Buka file src/functions/sendMessage.js, perbarui konten sebagai berikut:

   const { app, output } = require('@azure/functions');
   
   const signalR = output.generic({
       type: 'signalR',
       name: 'signalR',
       hubName: 'default',
       connectionStringSetting: 'AzureSignalRConnectionString',
   });
   
   app.http('messages', {
       methods: ['POST'],
       authLevel: 'anonymous',
       extraOutputs: [signalR],
       handler: async (request, context) => {
           const message = await request.json();
           message.sender = request.headers && request.headers.get('x-ms-client-principal-name') || '';
   
           let recipientUserId = '';
           if (message.recipient) {
               recipientUserId = message.recipient;
               message.isPrivate = true;
           }
           context.extraOutputs.set(signalR,
               {
                   'userId': recipientUserId,
                   'target': 'newMessage',
                   'arguments': [message]
               });
       }
   });
   

   Fungsi ini berisi pemicu HTTP dan pengikatan output SignalR. Dibutuhkan isi dari permintaan HTTP dan mengirimkannya ke klien yang terhubung ke Azure SignalR Service. Ini memanggil fungsi newMessage bernama pada setiap klien.

   Fungsi ini dapat membaca identitas pengirim dan dapat menerima recipient nilai dalam isi pesan untuk memungkinkan Anda mengirim pesan secara privat ke satu pengguna. Anda akan menggunakan fungsionalitas ini nanti dalam tutorial.

3. Simpan file.

Model v3

1. Dari folder proyek akar, buat fungsi pemicu HTTP bernama sendMessage dari templat dengan menggunakan perintah berikut:

   func new --name sendMessage --template "Http trigger"
   

2. Untuk mengonfigurasi pengikatan untuk fungsi, ganti konten sendMessage/function.json dengan kode berikut:

   {
     "disabled": false,
     "bindings": [
       {
         "authLevel": "anonymous",
         "type": "httpTrigger",
         "direction": "in",
         "name": "req",
         "route": "messages",
         "methods": ["post"]
       },
       {
         "type": "http",
         "direction": "out",
         "name": "res"
       },
       {
         "type": "signalR",
         "name": "$return",
         "hubName": "default",
         "direction": "out"
       }
     ]
   }
   

   Kode sebelumnya membuat dua perubahan pada file asli:

   • Ini mengubah rute ke messages dan membatasi pemicu HTTP ke POST metode HTTP.
   • Ini menambahkan pengikatan output Azure SignalR Service yang mengirim pesan yang dikembalikan oleh fungsi ke semua klien yang terhubung ke hub Azure SignalR Service bernama default.

3. Ganti konten sendMessage/index.js dengan kode berikut:

   module.exports = async function (context, req) {
     const message = req.body;
     message.sender =
       (req.headers && req.headers["x-ms-client-principal-name"]) || "";
   
     let recipientUserId = "";
     if (message.recipient) {
       recipientUserId = message.recipient;
       message.isPrivate = true;
     }
   
     return {
       userId: recipientUserId,
       target: "newMessage",
       arguments: [message],
     };
   };
   

   Fungsi ini mengambil isi dari permintaan HTTP dan mengirimkannya ke klien yang terhubung ke Azure SignalR Service. Ini memanggil fungsi newMessage bernama pada setiap klien.

   Fungsi ini dapat membaca identitas pengirim dan dapat menerima recipient nilai dalam isi pesan untuk memungkinkan Anda mengirim pesan secara privat ke satu pengguna. Anda akan menggunakan fungsionalitas ini nanti dalam tutorial.

4. Simpan file.

Mengalami masalah? Beri tahu kami.

Menghosting antarmuka pengguna web klien obrolan

UI aplikasi obrolan adalah aplikasi satu halaman sederhana (SPA) yang dibuat dengan kerangka kerja JavaScript Vue dengan menggunakan klien ASP.NET Core SignalR JavaScript. Untuk kesederhanaan, aplikasi fungsi menghosting halaman web. Di lingkungan produksi, Anda dapat menggunakan Static Web Apps untuk menghosting halaman web.

Model v4

1. Buat file bernama index.html di direktori akar proyek fungsi Anda.

2. Salin dan tempel konten index.html ke file Anda. Simpan file.

3. Dari folder proyek akar, buat fungsi pemicu HTTP bernama index dari templat dengan menggunakan perintah ini:

   func new --name index --template "Http trigger"
   

4. Ubah konten src/functions/index.js ke kode berikut:

   const { app } = require('@azure/functions');
   const { readFile } = require('fs/promises');
   
   app.http('index', {
       methods: ['GET'],
       authLevel: 'anonymous',
       handler: async (context) => {
           const content = await readFile('index.html', 'utf8', (err, data) => {
               if (err) {
                   context.err(err)
                   return
               }
           });
   
           return {
               status: 200,
               headers: {
                   'Content-Type': 'text/html'
               },
               body: content,
           };
       }
   });
   

   Fungsi membaca halaman web statis dan mengembalikannya kepada pengguna.

5. Uji aplikasi Anda secara lokal. Mulai aplikasi fungsi dengan menggunakan perintah ini:

   func start
   

6. Buka http://localhost:7071/api/index di browser web Anda. Halaman web obrolan akan muncul.

   

7. Masukkan pesan di kotak obrolan.

   Setelah Anda memilih tombol Enter, pesan muncul di halaman web. Karena nama pengguna klien SignalR tidak diatur, Anda mengirim semua pesan secara anonim.

Model v3

1. Buat folder bernama konten di direktori akar proyek fungsi Anda.

2. Di folder konten, buat file bernama index.html.

3. Salin dan tempel konten index.html ke file Anda. Simpan file.

4. Dari folder proyek akar, buat fungsi pemicu HTTP bernama index dari templat dengan menggunakan perintah ini:

   func new --name index --template "Http trigger"
   

5. Ubah konten index/index.js ke kode berikut:

   const fs = require("fs");
   
   module.exports = async function (context, req) {
     const fileContent = fs.readFileSync("content/index.html", "utf8");
   
     context.res = {
       // status: 200, /* Defaults to 200 */
       body: fileContent,
       headers: {
         "Content-Type": "text/html",
       },
     };
   };
   

   Fungsi membaca halaman web statis dan mengembalikannya kepada pengguna.

6. Buka indeks/function.json, dan ubah authLevel nilai pengikatan menjadi anonymous. Sekarang seluruh file terlihat seperti contoh ini:

   {
     "bindings": [
       {
         "authLevel": "anonymous",
         "type": "httpTrigger",
         "direction": "in",
         "name": "req",
         "methods": ["get", "post"]
       },
       {
         "type": "http",
         "direction": "out",
         "name": "res"
       }
     ]
   }
   

7. Uji aplikasi Anda secara lokal. Mulai aplikasi fungsi dengan menggunakan perintah ini:

   func start
   

8. Buka http://localhost:7071/api/index di browser web Anda. Halaman web obrolan akan muncul.

   

9. Masukkan pesan di kotak obrolan.

   Setelah Anda memilih tombol Enter, pesan muncul di halaman web. Karena nama pengguna klien SignalR tidak diatur, Anda mengirim semua pesan secara anonim.

Mengalami masalah? Beri tahu kami.

Sebarkan ke Azure dan aktifkan autentikasi

Anda telah menjalankan aplikasi fungsi dan aplikasi obrolan secara lokal. Sekarang, sebarkan ke Azure dan aktifkan autentikasi dan olahpesan privat.

Mengonfigurasi aplikasi fungsi untuk autentikasi

Sejauh ini, aplikasi obrolan berfungsi secara anonim. Di Azure, Anda akan menggunakan autentikasi App Service untuk mengautentikasi pengguna. ID pengguna atau nama pengguna pengguna yang diautentikasi diteruskan ke SignalRConnectionInfo pengikatan untuk menghasilkan informasi koneksi yang diautentikasi sebagai pengguna.

Model v4

1. Buka file src/functions/negotiate.js .

2. userId Sisipkan properti ke dalam pengikatan inputSignalR dengan nilai {headers.x-ms-client-principal-name}. Nilai ini adalah ekspresi pengikatan yang mengatur nama pengguna klien SignalR ke nama pengguna yang diautentikasi. Pengikatan sekarang akan terlihat seperti contoh ini:

   const inputSignalR = input.generic({
       type: 'signalRConnectionInfo',
       name: 'connectionInfo',
       hubName: 'default',
       connectionStringSetting: 'AzureSignalRConnectionString',
       userId: '{headers.x-ms-client-principal-name}'
   });
   

3. Simpan file.

Model v3

1. Buka negosiasi/function.json.

2. userId Sisipkan properti ke dalam pengikatan SignalRConnectionInfo dengan nilai {headers.x-ms-client-principal-name}. Nilai ini adalah ekspresi pengikatan yang mengatur nama pengguna klien SignalR ke nama pengguna yang diautentikasi. Pengikatan sekarang akan terlihat seperti contoh ini:

   {
     "type": "signalRConnectionInfo",
     "name": "connectionInfo",
     "userId": "{headers.x-ms-client-principal-name}",
     "hubName": "default",
     "direction": "in"
   }
   

3. Simpan file.

Menyebarkan aplikasi fungsi ke Azure

Sebarkan aplikasi fungsi ke Azure dengan menggunakan perintah berikut:

func azure functionapp publish <your-function-app-name> --publish-local-settings

Opsi menerbitkan --publish-local-settings pengaturan lokal Anda dari file local.settings.json ke Azure, sehingga Anda tidak perlu mengonfigurasinya lagi di Azure.

Mengaktifkan autentikasi App Service

Azure Functions mendukung autentikasi dengan ID Microsoft Entra, Facebook, X, akun Microsoft, dan Google. Anda akan menggunakan Microsoft sebagai penyedia identitas untuk tutorial ini.

1. Di portal Azure, buka halaman sumber daya aplikasi fungsi Anda.

2. Pilih Pengaturan>Autentikasi.

3. Pilih Tambahkan penyedia identitas .

   

4. Di daftar Penyedia identitas, pilih Microsoft. Kemudian pilih Tambahkan.

   

Pengaturan yang telah selesai membuat pendaftaran aplikasi yang mengaitkan penyedia identitas Anda dengan aplikasi fungsi Anda.

Untuk informasi selengkapnya tentang penyedia identitas yang didukung, lihat artikel berikut ini:

• Microsoft Entra ID
• Facebook
• X
• Akun Microsoft
• Google

Coba aplikasi

1. Buka https://<YOUR-FUNCTION-APP-NAME>.azurewebsites.net/api/index.
2. Pilih Masuk untuk mengautentikasi dengan penyedia autentikasi pilihan Anda.
3. Kirim pesan publik dengan memasukkannya di kotak obrolan utama.
4. Kirim pesan privat dengan memilih nama pengguna dalam riwayat obrolan. Hanya penerima terpilih yang menerima pesan ini.

Selamat! Anda menyebarkan aplikasi obrolan tanpa server real time.

Mengalami masalah? Beri tahu kami.

Membersihkan sumber daya

Untuk membersihkan sumber daya yang Anda buat dalam tutorial ini, hapus grup sumber daya dengan menggunakan portal Azure.

Perhatian

Menghapus grup sumber daya akan menghapus semua sumber daya yang ada di dalamnya. Jika grup sumber daya berisi sumber daya di luar cakupan tutorial ini, grup sumber daya juga akan dihapus.

Mengalami masalah? Beri tahu kami.

Langkah berikutnya

Dalam tutorial ini, Anda mempelajari cara menggunakan Azure Functions dengan Azure SignalR Service. Baca selengkapnya tentang membangun aplikasi tanpa server real time dengan pengikatan Azure SignalR Service untuk Azure Functions:

Aplikasi real time dengan Azure SignalR Service dan Azure Functions

Mengalami masalah? Beri tahu kami.