Gunakan OAuth 2.0 JSON Web Tokens (JWT) untuk mengautentikasi dengan namespace

Artikel ini memperlihatkan cara mengautentikasi dengan namespace Layanan Azure Event Grid menggunakan Token Web JSON OAuth 2.0.

Broker MQTT Azure Event Grid mendukung autentikasi JWT OAuth 2.0, yang memungkinkan klien untuk terhubung dan mengautentikasi dengan namespace Event Grid menggunakan JSON Web Token yang dikeluarkan oleh penyedia identitas apa pun, selain Microsoft Entra ID.

Prasyarat

Untuk menggunakan autentikasi JWT OAuth 2.0 untuk namespace, Anda harus memiliki prasyarat berikut:

Penyedia identitas yang dapat mengeluarkan JSON Web Token.
Sertifikat CA yang menyertakan kunci publik Anda yang digunakan untuk memvalidasi token klien (Key Vault) atau file PEM sertifikat kunci publik Anda (unggahan langsung).

Langkah-langkah tingkat tinggi

Untuk menggunakan autentikasi JWT OAuth 2.0 untuk namespace, ikuti langkah-langkah berikut:

Buat namespace dan konfigurasikan subresourcenya.
Aktifkan identitas terkelola di namespace Layanan Event Grid Anda.
Konfigurasikan pengaturan autentikasi OAuth 2.0 di namespace Layanan Event Grid Anda dengan mengikuti langkah-langkah berikut:
1. Buat akun Azure Key Vault yang menghosting sertifikat CA yang menyertakan kunci publik Anda dan menambahkan penetapan peran di Key Vault untuk identitas terkelola namespace.
2. Atau unggah file PEM sertifikat kunci publik Anda ke namespace.
Klien Anda dapat terhubung ke namespace Layanan Event Grid menggunakan token yang disediakan oleh penyedia identitas Anda.

Membuat namespace dan mengonfigurasi subsumber dayanya

Ikuti instruksi dari Quickstart: Menerbitkan dan berlangganan pesan MQTT di Namespace Event Grid dengan portal Azure untuk membuat namespace dan mengonfigurasi subsumber dayanya. Lewati langkah-langkah pembuatan 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 pada namespace Event Grid Anda

Namespace menggunakan identitas terkelola untuk mengakses instans Azure Key Vault Anda untuk mendapatkan sertifikat server untuk domain kustom Anda. Gunakan perintah berikut untuk mengaktifkan identitas terkelola yang ditetapkan sistem di namespace Layanan Event Grid Anda:

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

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

Mengonfigurasi pengaturan autentikasi JWT OAuth 2.0 di namespace layanan Event Grid Anda -Key Vault

Pertama, buat akun Azure Key Vault, unggah sertifikat server Anda, dan tetapkan peran identitas terkelola namespace yang sesuai pada brankas kunci. Kemudian, Anda mengonfigurasi pengaturan autentikasi kustom di namespace Layanan Event Grid Anda menggunakan portal Microsoft Azure atau Azure CLI. Anda perlu membuat namespace terlebih dahulu lalu memperbaruinya menggunakan langkah-langkah berikut.

Membuat akun Azure Key Vault dan mengunggah sertifikat server Anda

Gunakan perintah berikut untuk membuat akun Azure Key Vault:

az keyvault create --name "<your-unique-keyvault-name>" --resource-group "<resource group name>" --location "centraluseuap"

Gunakan perintah berikut untuk mengimpor sertifikat ke Azure Key Vault
```
az keyvault certificate import --vault-name "<your-key-vault-name>" -n "<cert name>" -f "<path to your certificate pem file> " 
```
Catatan

Sertifikat Anda harus menyertakan nama domain dalam Nama alternatif subjek untuk DNS. Untuk informasi selengkapnya, lihat Tutorial: Mengimpor sertifikat di Azure Key Vault.

Menambahkan penetapan peran di Azure Key Vault untuk identitas terkelola namespace

Anda perlu menyediakan akses ke namespace layanan untuk mengakses akun Azure Key Vault Anda menggunakan langkah-langkah berikut:

Dapatkan ID prinsipal identitas terkelola sistem namespace Event Grid menggunakan perintah berikut

$principalId=(az eventgrid namespace show --resource-group <resource group name> --name <namespace name> --query identity.principalId -o tsv)

Dapatkan ID sumber daya Azure Key Vault Anda.

$keyVaultResourceId=(az keyvault show --resource-group <resource group name> --name <your key vault name> --query id -o tsv)

Tambahkan penetapan peran di Key Vault untuk identitas terkelola namespace.
```
az role assignment create --role "Key Vault Certificate User" --assignee $principalId --scope $keyVaultResourceId 
```
Untuk informasi selengkapnya tentang akses Key Vault dan pengalaman portal, lihat Menyediakan akses ke kunci, sertifikat, dan rahasia Key Vault dengan kontrol akses berbasis peran Azure.

Menggunakan portal Microsoft Azure untuk mengonfigurasi autentikasi

Navigasikan ke namespace Layanan Event Grid Anda di portal Azure.
Pada halaman Namespace Event Grid, pilih Konfigurasi di menu sebelah kiri.
Di bagian Autentikasi JWT kustom, tentukan nilai untuk properti berikut ini:
1. Pilih Aktifkan autentikasi JWT kustom.
2. Penerbit Token: Masukkan nilai klaim penerbit JWT, yang disajikan oleh klien MQTT.
3. Untuk Sertifikat penerbit, pilih Dari Azure Key Vault.
4. Di halaman baru, tentukan nilai untuk properti berikut ini.
  1. URL Sertifikat: Pengidentifikasi Sertifikat dari sertifikat penerbit di Azure Key Vault yang Anda buat. Anda dapat memilih Pilih sertifikat menggunakan Key Vault sebagai gantinya untuk memilih sertifikat dan Key Vault dari langganan Anda.
  2. Identitas: identitas yang digunakan untuk mengautentikasi dengan Key Vault untuk mengakses sertifikat penerbit yang dibuat.
  3. Pilih Tambahkan.
Kembali ke halaman Konfigurasi , pilih Terapkan.

Catatan

Anda dapat menambahkan hingga dua iss sertifikat untuk tujuan rotasi sertifikat/kunci.

Gunakan Azure CLI

Gunakan perintah berikut untuk memperbarui namespace Anda dengan konfigurasi autentikasi JWT kustom.

az resource update \
  --resource-type Microsoft.EventGrid/namespaces \
  --api-version 2024-06-01-preview \
  --ids /subscriptions/1111a1a1-bb2b-cc3c-dd4d-ffffee5e5e5e/resourceGroups/sample-rg/providers/Microsoft.EventGrid/namespaces/sample-namespace \
  --set properties.topicSpacesConfiguration.clientAuthentication='{
    \"customJwtAuthentication\":{
      \"tokenIssuer\":\"sample-issuer\",
      \"issuerCertificates\":[
        {
          \"certificateUrl\":\"https://sample-vault.vault.azure.net/certificates/sample-cert/12345abcdef67890\",
          \"identity\":{
            \"type\":\"UserAssigned\",
            \"userAssignedIdentity\":\"/subscriptions/1111a1a1-bb2b-cc3c-dd4d-ffffee5e5e5e/resourceGroups/sample-rg/providers/Microsoft.ManagedIdentity/userAssignedIdentities/sample-identity\"
          }
        }
      ]
    }
  }'

Format JSON Web Token

JSON Web Token harus memiliki bagian JWT Header, payload JWT, dan tanda tangan JWT.

JWT Header

Header harus berisi setidaknya typ dan alg bidang.  typ harus selalu JWS dan alg harus selalu RS256. Header token harus sebagai berikut:

{
    "typ": "JWT",
    "alg": "RS256"
}

Beban Data JWT

Event Grid memerlukan klaim berikut: iss, , sub, aud, expnbf.

Nama	Deskripsi
`iss`	Penerbit. Nilai di JWT harus cocok dengan pengeluar dalam konfigurasi namespace Event Grid untuk autentikasi JWT kustom.
`sub`	Subjek. Nilai digunakan sebagai nama identitas autentikasi.
`aud`	Audiens. Nilai adalah array string. Nilai harus berisi nama host namespace Layanan Event Grid standar dan/atau domain kustom untuk namespace Layanan Event Grid tersebut (jika dikonfigurasi). Audiens dapat berisi string lain, tetapi kami mengharuskan setidaknya salah satu string ini menjadi nama host namespace Event Grid standar atau domain kustom untuk namespace ini.
`exp`	Kedaluwarsa. Waktu Unix ketika JWT kedaluwarsa.
`nbf`	Tidak dulu. Satuan waktu saat JWT menjadi valid.

Event Grid memetakan semua klaim ke atribut klien jika mereka memiliki salah satu jenis berikut: int32, , stringarray of strings. Klaim standar iss, sub, aud, exp, nbf dikecualikan dari atribut klien. Dalam contoh JWT berikut, hanya tiga klaim yang dikonversi ke atribut klien, num_attr, , str_attrstr_list_attr, karena mereka memiliki jenis int32yang benar , , stringarray of strings.  incorrect_attr_1, incorrect_attr_2, incorrect_attr_3 tidak dikonversi ke atribut klien, karena memiliki jenis yang salah: float, , array of integersobject.

{
    "iss": "correct_issuer",
    "sub": "d1",
    "aud": "testns.mqtt-broker-int.azure.net",
    "exp": 1712876224,
    "nbf": 1712869024,
    "num_attr": 1,
    "str_attr": "some string",
    "str_list_attr": [
        "string 1",
        "string 2"
    ],
    "incorrect_attr_1": 1.23,
    "incorrect_attr_2": [
        1,
        2,
        3
    ],
    "incorrect_attr_3": {
        "field": "value"
    }
}

Konfigurasikan pengaturan autentikasi JWT OAuth 2.0 di namespace Event Grid - Mengunggah secara langsung

Dalam langkah ini, Anda mengonfigurasi pengaturan autentikasi JWT kustom di namespace Layanan Event Grid menggunakan portal Microsoft Azure dan Azure CLI. Anda perlu membuat namespace terlebih dahulu lalu memperbaruinya menggunakan langkah-langkah berikut.

Menggunakan portal Microsoft Azure

Navigasikan ke namespace Layanan Event Grid Anda di portal Microsoft Azure.
Pada halaman Namespace Layanan Event Grid, pilih Konfigurasi di menu sebelah kiri.
Di bagian Autentikasi JWT kustom, tentukan nilai untuk properti berikut ini:
1. Pilih Aktifkan autentikasi JWT kustom.
2. Penerbit Token: Masukkan nilai klaim penerbit JWT, yang disajikan oleh klien MQTT.
3. Pilih opsi sertifikat penerbit – Unggah Langsung.
Di halaman baru, tentukan nilai untuk properti berikut ini.
1. Sertifikat: unggah sertifikat server Anda dalam Format PEM.
2. Kid: Pengidentifikasi kunci unik untuk sertifikat.
3. Pilih Tambahkan.
Kembali ke halaman Konfigurasi , pilih Terapkan.

Gunakan Azure CLI

Gunakan perintah berikut untuk memperbarui namespace Anda dengan konfigurasi autentikasi JWT OAuth 2.0.

az eventgrid namespace update \ 
    --resource-group <resource-group-name> \ 
    --name <namespace-name> \ 
    --api-version 2024-12-15-preview \ 
    --set customJwtAuthenticationSettings='{ 
        "tokenIssuer": "issuer-name", 
        "encodedIssuerCertificates": [
            { 
                "kid": "key1", 
                "encodedCertificate": "-----BEGIN CERTIFICATE-----\n<certificate-in-PEM-format>\n-----END CERTIFICATE-----" 
            } 
        ] 
    }

Ganti <resource-group-name>, , <namespace-name><location>, <key-vault-name>, <certificate-name>, dan <certificate-in-PEM-format> dengan nilai aktual Anda.
Nilai encodedCertificate harus menyertakan sertifikat lengkap dan kunci publik dalam format PEM, termasuk header ( "-----BEGIN CERTIFICATE-----", "-----END CERTIFICATE----, ``-----BEGIN PUBLIC KEY----- and -----END PUBLIC KEY-----).
Pastikan sertifikat kunci publik yang disediakan valid dan dipercaya oleh penyedia identitas Anda.
Perbarui sertifikatIssuerTertanam secara teratur jika sertifikat diganti atau kedaluwarsa.

Format JSON Web Token

JSON Web Token harus memiliki bagian JWT Header, payload JWT, dan tanda tangan JWT.

Event Grid memerlukan klaim berikut: iss, , sub, aud, expnbf.

kid bersifat opsional. Jika ada, sertifikat dengan pencocokan kid digunakan untuk validasi.
Daftar klaim standar yang tidak digunakan sebagai atribut - iss, , sub, audexp, nbf, iat, jti.
Semua klaim yang memiliki jenis data yang benar (angka yang sesuai dengan int32, string, array string) digunakan sebagai atribut. Dalam contoh num_attr_pos, , num_attr_negstr_attr, str_list_attr klaim memiliki jenis data yang benar dan digunakan sebagai atribut.
Dalam contoh bool_attr, , num_attr_to_bignum_attr_float, obj_attr klaim memiliki jenis data yang salah dan tidak digunakan sebagai atribut.

{ 
  "typ": "JWT", 
  "alg": "RS256", 
  "kid": "keyId1" 
}.{ 
  "iss": "some-issuer", 
  "sub": "device1", 
  "aud": "event-grid-namespace.ts.eventgrid.azure.net", 
  "exp": 1770426501, 
  "nbf": 1738886901, 
  "bool_attr": true, 
  "num_attr_pos": 1, 
  "num_attr_neg": -1, 
  "num_attr_to_big": 9223372036854775807, 
  "num_attr_float": 1.23, 
  "str_attr": "str_value", 
  "str_list_attr": [ 
    "str_value_1", 
    "str_value_2" 
  ], 
  "obj_attr": { 
      "key": "value" 
  } 
}

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2025-06-05

Bagikan melalui

Gunakan OAuth 2.0 JSON Web Tokens (JWT) untuk mengautentikasi dengan namespace

Prasyarat

Langkah-langkah tingkat tinggi

Membuat namespace dan mengonfigurasi subsumber dayanya

Mengaktifkan identitas terkelola pada namespace Event Grid Anda

Mengonfigurasi pengaturan autentikasi JWT OAuth 2.0 di namespace layanan Event Grid Anda -Key Vault

Membuat akun Azure Key Vault dan mengunggah sertifikat server Anda

Menambahkan penetapan peran di Azure Key Vault untuk identitas terkelola namespace

Menggunakan portal Microsoft Azure untuk mengonfigurasi autentikasi

Gunakan Azure CLI

Format JSON Web Token

JWT Header

Beban Data JWT

Konfigurasikan pengaturan autentikasi JWT OAuth 2.0 di namespace Event Grid - Mengunggah secara langsung

Menggunakan portal Microsoft Azure

Gunakan Azure CLI

Format JSON Web Token

Konten terkait

Saran dan Komentar

Sumber Daya Tambahan: