使用自訂 Webhook 驗證對 MQTT 代理程式進行驗證

本文說明如何使用 Webhook 或 Azure 函式對 Azure 事件方格命名空間進行驗證。

Webhook 驗證可讓外部 HTTP 端點 (Webhook 或函式) 動態驗證訊息佇列遙測傳輸 (MQTT) 連線。 此方法會使用 Microsoft Entra ID JSON Web 權杖驗證來確保存取安全性。

當用戶端嘗試連線時，代理程式會叫用使用者定義的 HTTP 端點以驗證認證，例如共用存取簽章權杖、使用者名稱和密碼，甚或執行憑證撤銷清單檢查。 Webhook 會評估要求，並傳回允許或拒絕連線的決策，以及微調授權的選擇性元數據。 此方法支援跨各種裝置機群和使用案例的彈性和集中式驗證原則。

先決條件

• 具有系統指派或使用者指派受控識別的事件方格命名空間。
• 外部 Webhook 或 Azure 函式。
• 授與事件方格命名空間的受控識別對 Azure 函式或 Webhook 的存取權。

高階步驟

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

1. 建立命名空間並設定其子資源。
2. 在事件方格命名空間上啟用受控識別。
3. 授與受控識別對 Azure 函式或 Webhook 的存取權。
4. 在事件方格命名空間上設定自訂 Webhook 設定。
5. 將客戶端連線到事件方格命名空間，並透過 Webhook 或函式進行驗證。

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

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

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

若要在事件方格命名空間上啟用系統指派的受控識別，請使用下列命令：

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

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

授與受控識別對函式或 Webhook 的適當存取權

為事件方格命名空間的受控識別授與對目標 Azure 函式或 Webhook 的適當存取權。

若要設定 Azure 函式的自訂驗證，請遵循下列步驟。

建立 Microsoft Entra 應用程式

1. 在 Microsoft Entra ID 中建立 Microsoft Entra 應用程式。

2. 在應用程式的 [概觀] 頁面上，記下 [應用程式 (用戶端) 識別碼] 值。

   

3. 在左側功能表上，選取 [公開 API]。 選取 [應用程式識別碼 URI] 旁邊的 [新增]。

4. 記下 [編輯應用程式識別碼 URI] 窗格上的 [應用程式識別碼 URI] 值，然後選取 [儲存]。

   

設定 Azure 函式的驗證

如果您有從 Azure 入口網站建立的基本 Azure 函式，請設定驗證，並驗證使用受控識別所建立的 Microsoft Entra ID 權杖。

1. 移至您的 Azure Functions 應用程式。

2. 在左側功能表上，選取 [ 驗證]，然後選取 [新增識別提供者]。

   

3. 在 [新增識別提供者] 頁面上，針對 [識別提供者]，從下拉式清單中選取 [Microsoft]。

4. 在 [應用程式註冊] 區段中，指定下列屬性的值：

   1. 應用程式 (用戶端) 識別碼：輸入您先前記下的 Microsoft Entra 應用程式的用戶端識別碼。

   2. 簽發者 URL：在表單 https://login.microsoftonline.com/<tenantid>/v2.0 中新增簽發者 URL。

      

5. 針對 [允許的權杖物件]，新增您先前記下的 Microsoft Entra 應用程式的 [應用程式識別碼 URI] 值。

6. 在 [其他檢查] 區段中，針對 [用戶端應用程式開發]，選取 [允許來自特定用戶端應用程式的要求]。

7. 在 [允許的用戶端應用程式] 窗格中，輸入用來產生權杖的系統指派受控識別的用戶端識別碼。 您可以在 Microsoft Entra ID 資源的企業應用程式中找到此識別碼。

8. 根據您的特定需求選擇其他設定，然後選取 [新增]。

現在，產生並使用 Microsoft Entra ID 令牌。

1. 使用受控識別與應用程式識別碼 URI 作為資源，產生 Microsoft Entra ID 權杖。
2. 使用此令牌來叫用 Azure 函式，方法是將它包含在要求標頭中。

在您的事件方格命名空間上設定自定義 Webhook 驗證設定

使用 Azure 入口網站和 Azure CLI，在事件方格命名空間上設定自訂 Webhook 驗證設定。 您可以先建立命名空間，再加以更新。

使用 Azure 入口網站

1. 在 Azure 入口網站中移至事件方格命名空間。

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

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

   1. 受控識別類型：選取 [使用者指派]。
   2. Webhook URL：輸入事件方格服務使用指定的受控識別傳送已驗證 Webhook 要求的 URL 端點值。
   3. 權杖物件 URI：輸入 Microsoft Entra 應用程式識別碼或 URI 的值，以取得要在傳遞要求中包含作為持有人權杖的存取權杖。
   4. Microsoft Entra ID 租用戶識別碼：輸入 Microsoft Entra 租用戶識別碼的值，用來取得已驗證 Webhook 傳遞的持有人權杖。

4. 選取 ，然後套用。

   

使用 Azure CLI

若要使用自訂 Webhook 驗證設定來更新您的命名空間，請使用下列命令：

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" 

將 <NAMESPACE_NAME> 和 <RESOURCE_GROUP_NAME> 取代為您的實際值。 填入訂用帳戶、資源群組、身分識別、應用程式識別碼、URL 和租用戶識別碼中的預留位置。 若要讓事件方格 MQTT 代理程式的 Webhook 型驗證更加高效和可靠，強烈建議您為 Webhook 端點啟用 HTTP/2 支援。

Webhook API 詳細數據

要求標頭

授權：持有人權杖

權杖是設定為呼叫 Webhook 之受控識別的 Microsoft Entra 權杖。

要求承載

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

承載欄位描述

領域	必要/選擇性	說明
clientId	為必填項目	來自 MQTT CONNECT 封包的用戶端識別碼。
userName	可選	來自 MQTT CONNECT 封包的用戶名稱。
password	可選	MQTT CONNECT 封包中的密碼，採用 Base64 編碼。
authenticationMethod	可選	來自 MQTT CONNECT 封包的驗證方法（僅限 MQTT5）。
authenticationData	可選	MQTT CONNECT 封包中的驗證資料，採用 Base64 編碼 (僅限 MQTT5)。
clientCertificate	可選	PEM 格式的客戶端憑證。
clientCertificateChain	可選	用戶端提供的其他憑證，用來建置從用戶端憑證到憑證授權單位憑證的鏈結。
userProperties	可選	來自 CONNECT 封包的用戶屬性（僅限 MQTT5）。

回應負載

成功回應

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

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

拒絕回應

HTTP/1.1 400 Bad Request 
Content-Type: application/json 

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

回應欄位描述

領域	說明
decision (必要)	驗證決策為 allow 或 deny。
clientAuthenticationName	用戶端驗證名稱（身分識別名稱）。 (decision 設定為 allow 時為必要項目。)
attributes	具有屬性的字典。 索引鍵為屬性名稱，值為 int/string/array。 (decision 設定為 allow 時為選用。)
expiration	Unix 時間格式的到期日。 (decision 設定為 allow 時為選用。)
errorReason	decision 設定為 deny 時為錯誤訊息。 記錄此錯誤。 (decision 設定為 deny 時為選用。)

支援的屬性類型範例

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

所有正確的資料類型 (符合 <int32/string/array_of_strings> 的數字) 都會作為屬性。 在此範例中，num_attr_pos、num_attr_neg、str_attr 和 str_list_attr 宣告具有正確的資料類型，因而作為屬性。

相關內容

• MQTT 用戶端驗證
• 使用自訂 JWT 驗證用戶端