Mengautentikasi dengan broker MQTT dengan menggunakan autentikasi webhook kustom

Artikel ini memperlihatkan kepada Anda cara mengautentikasi dengan namespace Azure Event Grid dengan menggunakan webhook atau fungsi Azure.

Autentikasi webhook memungkinkan titik akhir HTTP eksternal (webhook atau fungsi) untuk mengautentikasi koneksi Message Queuing Telemetry Transport (MQTT) secara dinamis. Metode ini menggunakan validasi Microsoft Entra ID JSON Web Token untuk memastikan akses yang aman.

Ketika klien mencoba untuk terhubung, broker memanggil titik akhir HTTP yang ditentukan pengguna yang memvalidasi kredensial, seperti token Tanda Tangan Akses Bersama, nama pengguna, dan kata sandi, atau bahkan melakukan pemeriksaan Daftar Pencabutan Sertifikat. Webhook mengevaluasi permintaan dan mengembalikan keputusan untuk mengizinkan atau menolak koneksi, bersama dengan metadata opsional untuk otorisasi halus. Pendekatan ini mendukung kebijakan autentikasi yang fleksibel dan terpusat di berbagai armada perangkat dan kasus penggunaan.

Prasyarat

  • Namespace Event Grid dengan identitas terkelola yang ditetapkan oleh sistem atau oleh pengguna.
  • Webhook eksternal atau fungsi di Azure.
  • Akses yang diberikan ke identitas terkelola namespace Event Grid ke fungsi Azure atau webhook.

Langkah-langkah tingkat tinggi

Untuk menggunakan autentikasi webhook kustom untuk namespace, ikuti langkah-langkah berikut:

  1. Buat namespace dan konfigurasikan subresourcenya.
  2. Aktifkan identitas terkelola di namespace Layanan Event Grid Anda.
  3. Berikan akses identitas terkelola ke fungsi atau webhook Azure Anda.
  4. Konfigurasikan pengaturan webhook kustom di namespace Event Grid Anda.
  5. Sambungkan klien Anda ke namespace Layanan Event Grid dan dapatkan autentikasi melalui webhook atau fungsi.

Membuat namespace dan mengonfigurasi subsumber dayanya

Untuk membuat namespace layanan dan mengonfigurasi sub-sumber dayanya, ikuti instruksi di Mulai Cepat: Menerbitkan dan berlangganan pesan MQTT pada namespace Layanan Event Grid dengan portal Microsoft Azure. Lewati langkah-langkah untuk membuat sertifikat dan klien karena identitas klien berasal dari token yang disediakan. Atribut klien didasarkan pada klaim kustom dalam token klien. Atribut klien digunakan dalam kueri grup klien, variabel templat topik, dan konfigurasi pengayaan perutean.

Mengaktifkan identitas terkelola di namespace Event Grid Anda

Untuk mengaktifkan identitas terkelola yang ditetapkan sistem di namespace Layanan Event Grid Anda, gunakan perintah berikut:

az eventgrid namespace update --resource-group <resource group name> --name <namespace name> --identity "{type:systemassigned}"

Untuk informasi tentang cara mengonfigurasi identitas yang ditetapkan sistem dan pengguna dengan menggunakan portal Microsoft Azure, lihat Mengaktifkan identitas terkelola untuk namespace Layanan Event Grid.

Implementasi

Opsi 1: Implementasi Webhook melalui Azure Functions (Aplikasi Microsoft Entra)

Azure Functions dapat menghosting logika webhook dengan menggunakan Microsoft.Identity.Web untuk memvalidasi token secara otomatis. Anda memerlukan pendaftaran aplikasi Microsoft Entra untuk API webhook untuk memvalidasi token pemanggil Event Grid. Pendaftaran aplikasi memiliki URI ID Aplikasi untuk penerbitan token. Sisi klien (Event Grid) sudah memiliki identitas terkelola.

Keuntungan:

  • Tidak ada infrastruktur untuk dikelola
  • Pembantu autentikasi bawaan (Microsoft.Identity.Web)
  • Tahan lama, dapat diskalakan, hemat biaya

Fungsi harus melakukan operasi berikut:

  • Validasi token pemanggil dari identitas terkelola Event Grid.
  • Validasi Token JSON Web (JWT) untuk klien.
  • Mengembalikan respons JSON izinkan atau tolak.

Opsi 2: Implementasi titik akhir HTTPS eksternal

Implementasi ini dapat berupa Endpoint HTTPS eksternal (backend apa pun, cloud apa pun), menggunakan validasi Microsoft Entra ID JWT dengan pustaka Microsoft.IdentityModel.

Gunakan runtime apa pun: .NET, Node.js, Java, atau Python.

Persyaratan utama:

  • Titik akhir harus HTTPS.

  • Ini harus memvalidasi penelepon JWT.

  • Ini harus memvalidasi perangkat JWT.

  • Harus merespons dalam batas waktu yang direkomendasikan (sekitar 5 detik).

    Diagram yang memperlihatkan implementasi webhook kustom.

Memberikan identitas terkelola akses yang sesuai ke fungsi atau webhook

Berikan akses yang tepat kepada identitas terkelola dari namespace Event Grid Anda ke fungsi atau webhook Azure yang dituju.

Untuk menyiapkan autentikasi kustom untuk fungsi Azure, ikuti langkah-langkah berikutnya.

Membuat aplikasi Microsoft Entra

  1. Buat aplikasi Microsoft Entra di ID Microsoft Entra.

  2. Pada halaman Gambaran Umum aplikasi, catat nilai ID Aplikasi (klien).

    Cuplikan layar yang memperlihatkan halaman Gambaran Umum aplikasi ID Microsoft Entra dengan ID aplikasi (klien) disorot.

  3. Di menu sebelah kiri, pilih Ekspos API. Di samping URI ID Aplikasi, pilih Tambahkan.

  4. Catat nilai URI ID Aplikasi pada panel Edit URI ID aplikasi , lalu pilih Simpan.

    Cuplikan layar yang memperlihatkan URI ID aplikasi aplikasi Microsoft Entra.

Menyiapkan autentikasi untuk fungsi Azure

Jika Anda memiliki fungsi Azure dasar yang dibuat dari portal Microsoft Azure, siapkan autentikasi dan validasi token ID Microsoft Entra yang dibuat dengan menggunakan identitas terkelola.

  1. Buka aplikasi Azure Functions Anda.

  2. Di menu sebelah kiri, pilih Autentikasi, lalu pilih Tambahkan IdP.

    Cuplikan layar yang memperlihatkan halaman Autentikasi.

  3. Pada halaman Tambahkan IdP , untuk Penyedia Identitas, pilih Microsoft dari daftar dropdown.

  4. Di bagian Pendaftaran aplikasi , tentukan nilai untuk properti berikut:

    1. ID Aplikasi (klien): Masukkan ID klien aplikasi Microsoft Entra yang Anda catat sebelumnya.

    2. URL Penerbit: Tambahkan URL penerbit dalam formulir https://login.microsoftonline.com/<tenantid>/v2.0.

      Cuplikan layar yang memperlihatkan Tambahkan penyedia identitas dengan Microsoft sebagai penyedia identitas.

  5. Di bagian Audiens token yang diizinkan , masukkan audiens token yang diizinkan. Untuk spesifiknya, masukkan URI ID Aplikasi aplikasi Microsoft Entra yang Anda catat sebelumnya. Audiens token digunakan untuk memvalidasi token masuk dari Event Grid.

  6. Di bagian Pemeriksaan tambahan , ikuti langkah-langkah berikut:

    1. Untuk Persyaratan aplikasi klien, pilih Permintaan yang diizinkan dari aplikasi klien tertentu, lalu masukkan ID aplikasi yang Anda catat sebelumnya.

    2. Untuk Persyaratan identitas, pilih Izinkan permintaan dari identitas apa pun.

      Cuplikan layar yang menunjukkan penambahan penyedia identitas dengan audiens token dan pemeriksaan tambahan.

  7. Di bagian Pengaturan autentikasi App Service , ikuti langkah-langkah berikut:

    1. Untuk Membatasi akses, pilih Memerlukan autentikasi.

    2. Untuk Permintaan yang tidak diautentikasi, pilih Mengembalikan HTTP 401 Tidak Sah.

      Cuplikan layar yang memperlihatkan pengaturan autentikasi App Service.

  8. Pilih pengaturan lain berdasarkan persyaratan spesifik Anda, lalu pilih Tambahkan.

Membuat dan menggunakan token ID Microsoft Entra

Sekarang, buat dan gunakan token ID Microsoft Entra.

  1. Hasilkan token ID Microsoft Entra dengan menggunakan identitas terkelola dengan URI ID aplikasi (api://<ClientID>) sebagai sumber daya.
  2. Gunakan token ini untuk memanggil fungsi Azure dengan menyertakannya di header permintaan.

Mengonfigurasi pengaturan autentikasi webhook kustom di namespace Layanan Event Grid Anda

Konfigurasikan pengaturan autentikasi webhook kustom di namespace Layanan Event Grid Anda dengan menggunakan portal Microsoft Azure dan Azure CLI. Anda membuat namespace terlebih dahulu lalu memperbaruinya.

Menggunakan portal Azure

  1. Buka namespace Layanan Event Grid Anda di portal Microsoft Azure.

  2. Pada halaman Namespace Event Grid, pilih Konfigurasi di menu sebelah kiri.

  3. Di bagian Autentikasi Webhook Kustom , tentukan nilai untuk properti berikut ini:

    1. Jenis identitas terkelola: Pilih Pengguna yang ditetapkan.
    2. URL Webhook: Masukkan nilai titik akhir URL tempat layanan Event Grid mengirim permintaan webhook yang diautentikasi dengan menggunakan identitas terkelola yang ditentukan.
    3. Token audience URI: Masukkan nilai dari ID aplikasi Microsoft Entra atau URI untuk mendapatkan token akses yang akan disertakan sebagai token pembawa dalam permintaan pengiriman.
    4. ID penyewa Microsoft Entra: Masukkan nilai ID penyewa Microsoft Entra yang digunakan untuk memperoleh token otentikasi untuk pengiriman webhook terotentikasi.

  4. Pilih Terapkan.

    Cuplikan layar yang memperlihatkan konfigurasi autentikasi webhook untuk namespace Layanan Event Grid.

Gunakan Azure CLI

Untuk memperbarui namespace Anda dengan konfigurasi autentikasi webhook kustom, gunakan perintah berikut:

az eventgrid namespace update \ 
    --resource-group <resource-group-name> \ 
    --name <namespace-name> \ 
    --api-version 2025-04-01-preview \ 
    --identity-type UserAssigned \ 
    --identity-user-assigned-identities "/subscriptions/XXXXXXXXXXX/resourcegroups/XXXXXXXXXXX/providers/Microsoft.ManagedIdentity/userAssignedIdentities/XXXXXXXXXXX={}" \ 
    --set properties.isZoneRedundant=true \ 
        properties.topicSpacesConfiguration.state=Enabled \ 
        properties.topicSpacesConfiguration.clientAuthentication.webHookAuthentication.identity.type=UserAssigned \ 
        properties.topicSpacesConfiguration.clientAuthentication.webHookAuthentication.identity.userAssignedIdentity="/subscriptions/XXXXXXXXXXX/resourcegroups/XXXXXXXXXXX/providers/Microsoft.ManagedIdentity/userAssignedIdentities/XXXXXXXXXXX" \ 
        properties.topicSpacesConfiguration.clientAuthentication.webHookAuthentication.endpointUrl="https://XXXXXXXXXXX" \ 
        properties.topicSpacesConfiguration.clientAuthentication.webHookAuthentication.azureActiveDirectoryApplicationIdOrUri="api://XXXXXXXXXXX/.default" \ 
        properties.topicSpacesConfiguration.clientAuthentication.webHookAuthentication.azureActiveDirectoryTenantId="XXXXXXXXXXX"

Ganti <NAMESPACE_NAME> dan <RESOURCE_GROUP_NAME> dengan nilai aktual Anda. Isi placeholder di langganan, grup sumber daya, ID aplikasi, identitas, URL, dan ID penyewa. Untuk meningkatkan performa dan keandalan autentikasi berbasis webhook untuk broker Event Grid MQTT, kami sarankan Anda mengaktifkan dukungan HTTP/2 untuk titik akhir webhook Anda.

Detail-detail Webhook API

Tajuk permintaan

Azure Event Grid mengirimkan header berikut dalam permintaan ke webhook:

Authorization: Bearer <token>

Token adalah token Microsoft Entra untuk identitas terkelola yang dikonfigurasi untuk memanggil webhook.

Permintaan muatan

{
    "clientId": "<string>",
    "userName": "<string>",
    "password": "<base64 encoded bytes>",
    "authenticationMethod": "<string>",
    "authenticationData": "<base64 encoded bytes>",
    "clientCertificate": "<certificate in PEM format>",
    "clientCertificateChain": "<certificates from chain in PEM format>"
}

Deskripsi kolom payload

Bidang Diperlukan/Opsional Deskripsi
clientId Diperlukan ID klien dari paket MQTT CONNECT.
userName Fakultatif Nama pengguna dari paket MQTT CONNECT.
password Fakultatif Kata sandi dari paket MQTT CONNECT dalam pengodean Base64.
authenticationMethod Fakultatif Metode autentikasi dari paket MQTT CONNECT (hanya MQTT5).
authenticationData Fakultatif Data autentikasi dari paket MQTT CONNECT dalam pengodean Base64 (hanya MQTT5).
clientCertificate Fakultatif Sertifikat klien dalam format Privacy-Enhanced Mail (PEM).
clientCertificateChain Fakultatif Sertifikat lain yang disediakan oleh klien diperlukan untuk membangun rantai dari sertifikat klien ke sertifikat Otoritas Sertifikat.

Isi Muatan Respons

Respons berhasil

HTTP/1.1 200 OK 
Content-Type: application/json 

{ 
    "decision": "allow", 
    "clientAuthenticationName": "<string>", 
    "attributes": { 
        "attr": "<int/string/array_of_strings>", 
        ... 
    }, 
    "expiration": "<unix time format>" 
}

Respons ditolak

HTTP/1.1 200 OK 
Content-Type: application/json 

{ 
    "decision": "deny", 
    "errorReason": "<string>" 
}

Kode kesalahan:

Hasil autentikasi Respons fungsi Kode alasan Event Grid MQTT
Penolakan otorisasi eksplisit "decision": "deny" Tidak berwenang
Token tidak valid / kedaluwarsa "decision": "deny" Tidak berwenang
Batas waktu fungsi N/A Server tidak tersedia
Pengecualian fungsi / crash N/A Server tidak tersedia
Kegagalan platform sementara N/A Server tidak tersedia
Kesalahan pemrosesan broker internal N/A Server tidak tersedia

Deskripsi bidang respons

Bidang Jenis Diperlukan Ketika Deskripsi
decision string (allow | deny) Selalu diperlukan Keputusan autentikasi yang dikembalikan oleh layanan. Nilai yang diizinkan adalah: allow atau deny.
clientAuthenticationName string Diperlukan jika decision = allow Nama identitas klien (misalnya, ID perangkat atau ID klien).
attributes objek (kamus) Opsional jika decision = allow Pasangan kunci-nilai yang mewakili atribut tambahan. Nilai dapat berupa int, string, atau array string.
expiration bilangan bulat (tanda waktu Unix, detik) Opsional jika decision = allow Waktu kedaluwarsa untuk keputusan otorisasi, dinyatakan dalam bentuk waktu Unix (detik sejak epoch). Contoh: 1713782400.
errorReason string Opsional jika decision = deny Pesan kesalahan yang menjelaskan mengapa permintaan ditolak. Nilai ini dicatat untuk diagnostik.

Contoh jenis atribut yang didukung

"num_attr_pos": 1, 
"num_attr_neg": -1, 
"str_attr": "str_value", 
"str_list_attr": [ 
    "str_value_1", 
    "str_value_2" 
]

Semua jenis data yang benar (angka yang pas <int32/string/array_of_strings>) digunakan sebagai atribut. Dalam contoh, num_attr_posklaim , num_attr_neg, str_attr, dan str_list_attr memiliki jenis data yang benar dan digunakan sebagai atribut.

Konten terkait

  • Last updated on