使用 JSON Web 權杖搭配命名空間進行驗證

本文說明如何使用 JSON Web 權杖，搭配 Azure 事件方格命名空間進行驗證。

Azure 事件方格的 MQTT 代理支援自訂 JWT 驗證，其可讓用戶端使用任何識別提供者 (但 Microsoft Entra ID 之外) 所發出的 JSON Web 權杖，搭配事件方格命名空間進行連線和驗證。

必要條件

若要針對命名空間使用自訂 JWT 驗證，您必須具備下列必要條件：

• 可發出 Json Web 權杖的識別提供者。
• CA 憑證，其中包含您用來驗證用戶端權杖的公開金鑰。
• Azure Key Vault 帳戶，用來裝載包含公開金鑰的 CA 憑證。

高階步驟

若要針對命名空間使用自訂 JWT 驗證，請遵循下列步驟：

1. 建立命名空間並設定其子資源。
2. 在事件方格命名空間上啟用受控識別。
3. 建立 Azure Key Vault 帳戶，其會裝載包含公開金鑰的 CA 憑證。
4. 在 Azure Key Vault 中為命名空間的受控識別新增角色指派。
5. 在事件方格命名空間上設定自訂驗證設定
6. 用戶端可以使用識別提供者所提供的權杖，連線到事件方格命名空間。

建立命名空間並設定其子資源

遵循快速入門：使用 Azure 入口網站在事件方格命名空間上發佈和訂閱 MQTT 訊息中的指示，建立命名空間並設定其子資源。 當用戶端身分識別來自提供的權杖時，請略過憑證和用戶端建立步驟。 用戶端屬性是以用戶端權杖中的自訂宣告為基礎。 用戶端屬性用於用戶端群組查詢、主題範本變數和路由擴充設定中。

在事件方格命名空間上啟用受控識別

命名空間會使用受控識別來存取 Azure Key Vault 執行個體，為自訂網域取得伺服器憑證。 請使用下列命令，在事件方格命名空間上啟用系統指派的受控識別：

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

如需使用 Azure 入口網站設定系統和使用者指派身分識別的相關資訊，請參閱啟用事件方格命名空間的受控識別。

建立 Azure Key Vault 帳戶並上傳伺服器憑證

1. 請使用下列命令來建立 Azure Key Vault 帳戶：

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

2. 使用下列命令將憑證匯入至 Azure Key Vault

   az keyvault certificate import --vault-name "<your-key-vault-name>" -n "<cert name>" -f "<path to your certificate pem file> " 
   

   注意

   您的憑證必須在 DNS 的主體別名中包含網域名稱。 如需詳細資訊，請參閱教學課程：在 Azure Key Vault 中匯入憑證。

在 Azure Key Vault 中為命名空間的受控識別新增角色指派

您必須提供命名空間的存取權，才能使用下列步驟來存取 Azure Key Vault 帳戶：

1. 使用下列命令取得事件方格命名空間系統受控識別主體識別碼

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

2. 取得 Azure Key Vault 資源識別碼。

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

3. 在 Key Vault 中為命名空間的受控識別新增角色指派。

   az role assignment create --role "Key Vault Certificate User" --assignee $principalId --scope $keyVaultResourceId 
   

   如需 Key Vault 存取和入口網站體驗的詳細資訊，請參閱透過 Azure 角色型存取控制，提供 Key Vault 金鑰、憑證和祕密的存取權。

在事件方格命名空間上設定自訂驗證設定

在此步驟中，您會使用 Azure 入口網站和 Azure CLI，在事件方格命名空間上設定自訂驗證設定。 您必須先建立命名空間，然後使用下列步驟將其更新。

使用 Azure 入口網站

1. 在 Azure 入口網站中，瀏覽到您的事件方格命名空間。

2. 在 [事件方格命名空間] 頁面上，選取左側功能表上的 [設定]。

3. 在 [自訂 JWT 驗證] 區段中，指定下列屬性的值：

   1. 選取 [啟用自訂 JWT 驗證]。

   2. 權杖簽發者：輸入 JWT 權杖的簽發者宣告值，這些權杖是由 MQTT 用戶端提供的。

   3. 選取 [新增簽發者憑證]

      

   4. 在新的頁面中，指定下列屬性的值。

      1. 憑證 URL：Azure Key Vault 中您所建立簽發者憑證的憑證識別碼。 您可以改為選擇 [使用金鑰保存庫選取憑證]，從您的訂用帳戶選取憑證和金鑰保存庫。

      2. 身分識別：用來搭配 Key Vault 進行驗證的身分識別，用來存取已建立的簽發者憑證。

      3. 選取 [新增]。

         

4. 回到 [設定] 頁面上，選取 [套用]。

   注意

   您最多可以基於憑證/金鑰輪替目的新增兩個 iss 憑證。

使用 Azure CLI

使用下列命令，搭配自訂 JWT 驗證設定來更新命名空間。

az resource update --resource-type Microsoft.EventGrid/namespaces --api-version 2024-06-01-preview --ids /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/dummy-cd-test/providers/Microsoft.EventGrid/namespaces/dummy-cd-test2 --set properties.topicSpacesConfiguration.clientAuthentication='{\"customJwtAuthentication\":{\"tokenIssuer\":\"dmpypin-issuer\",\"issuerCertificates\":[{\"certificateUrl\":\"https://dummyCert-cd-test.vault.azure.net/certificates/dummy-cd-test/4f844b284afd487e9bba0831191087br1\",\"identity\":{\"type\":\"SystemAssigned\"}}]}}' 

JSON Web 權杖格式

Json Web 權杖分成 JWT 標頭和 JWT 承載區段。

JWT 標頭

標頭必須至少包含 typ 和 alg 欄位。 typ 必須一律為 JWS，而 alg 必須一律為 RS256。 權杖標頭必須如下所示：

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

JWT 承載

事件方格需要下列宣告：iss、sub、aud、exp、nbf。

名稱	描述
iss	簽發者。 JWT 中的值必須符合事件方格命名空間設定中的簽發者，才能進行自訂 JWT 驗證。
sub	主旨。 值會用作驗證身分識別名稱。
aud	對象。 值可以是字串或字串陣列。 值必須包含該事件方格命名空間的標準事件方格命名空間主機名稱和/或自訂網域 (如果已設定)。 對象可以包含其他字串，但我們需要其中至少一個字串成為此命名空間的標準事件方格命名空間主機名稱或自訂網域。
exp	到期。 JWT 到期的 Unix 時間。
nbf	生效時間。 JWT 生效的單位時間。

如果事件方格具有下列其中一種類型，則其會將所有宣告對應至用戶端屬性：int32、string、array of strings。 標準宣告 iss、sub、aud、exp、nbf 排除在客戶端屬性之外。 在下列 JWT 範例中，只有三個宣告 (num_attr、str_attr、str_list_attr) 會轉換成用戶端屬性，因為其具有正確的類型 int32、string、array of strings。 incorrect_attr_1、incorrect_attr_2、incorrect_attr_3 不會轉換成用戶端屬性，因為其具有類型錯誤：float、array of integers、object。

{
    "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"
    }
}

相關內容

• MQTT 用戶端驗證