Skip to content

Commit 5c3cad5

Browse files
spelluruspelluru
committed
New: Authenticate with webhook auth
1 parent 1465230 commit 5c3cad5

File tree

2 files changed

+228
-2
lines changed

2 files changed

+228
-2
lines changed

‎articles/event-grid/authenticate-with-namespaces-using-webhook-authentication.md

Lines changed: 224 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,224 @@
1+
---
2+
title: Authenticate with namespaces using webhook auth
3+
description: This article shows you how to authenticate with Azure Event Grid namespace using webhook or Azure function.
4+
ms.topic: how-to
5+
ms.custom: build-2025
6+
ms.date: 04/30/2025
7+
author: Connected-Seth
8+
ms.author: seshanmugam
9+
---
10+
11+
# Authenticate with MQTT broker using custom webhook authentication (Preview)
12+
This article shows how to authenticate with Azure Event Grid namespace using webhook or Azure function.
13+
14+
Webhook authentication allows external HTTP endpoints (webhooks or functions) to authenticate MQTT connections dynamically. This method uses Microsoft Entra ID JWT validation to ensure secure access.
15+
16+
When a client attempts to connect, the broker invokes a user-defined HTTP endpoint that validates credentials such SAS tokens, usernames/passwords, or even performs Certificate Revocation List (CRL) checks. The webhook evaluates the request and returns a decision to allow or deny the connection, along with optional metadata for fine-grained authorization. This approach supports flexible and centralized authentication policies across diverse device fleets and use cases.
17+
18+
> [!NOTE]
19+
> This feature is currently in preview.
20+
21+
## Prerequisites
22+
23+
To use custom webhook authentication for namespaces, you need to have the following prerequisites:
24+
25+
- An Event Grid namespace with either system-assigned or user-assigned managed identity.
26+
- The External Webhook or Azure function.
27+
- Grant access to the Event Grid Namespace’s Managed identity to Azure function /Webhook.
28+
29+
## High-level steps
30+
31+
To use custom webhook authentication for namespaces, follow these steps:
32+
33+
1. Create a namespace and configure its subresources.
34+
1. Enable managed identity on your Event Grid namespace.
35+
1. Grant the managed identity access to your Azure function or Webhook.
36+
1. Configure custom webhook settings on your Event Grid namespace
37+
1. Connect your clients to the Event Grid namespace and get authenticated via the webhook or function.
38+
39+
## Create a namespace and configure its subresources
40+
Follow instructions from [Quickstart: Publish and subscribe to MQTT messages on Event Grid Namespace with Azure portal](mqtt-publish-and-subscribe-portal.md) to create a namespace and configure its subresources. Skip the certificate and client creation steps as the client identities come from the provided token. Client attributes are based on the custom claims in the client token. The client attributes are used in the client group query, topic template variables, and routing enrichment configuration.
41+
42+
## Enable managed identity on your Event Grid namespace
43+
Use the following command to enable system-assigned managed identity on your Event Grid namespace:
44+
45+
```azurecli-interactive
46+
az eventgrid namespace update --resource-group <resource group name> --name <namespace name> --identity "{type:systemassigned}"
47+
```
48+
49+
For information on configuring system and user-assigned identities using the Azure portal, see [Enable managed identity for an Event Grid namespace](event-grid-namespace-managed-identity.md).
50+
51+
## Grant the managed identity appropriate access to function or webhook
52+
Grant the managed identity of your Event Grid namespace the appropriate access to the target Azure function or webhook.
53+
54+
### Use Azure portal
55+
56+
1. Identify the managed identity.
57+
1. Navigate to your **Event Grid namespace** in the [Azure portal](https://portal.azure.com).
58+
1. On the **Event Grid namespace** page, select **Identity** on the left menu.
59+
1. Copy the **object ID** of the managed identity.
60+
1. Navigate to your **Azure function app** or the **app service hosting the Webhook**.
61+
1. Assign appropriate role to the managed identity.
62+
1. On the **Function App** page, select **Access Control (IAM)** on the left menu, and then select **Add Role Assignment**.
63+
1. Choose a role like **Contributor** or **Function App Contributor** (or a custom role with required permissions).
64+
1. Scope it appropriately (for example, at the resource or resource group level).
65+
1. Select **Assign access to**, and then select user, group, or service principal.
66+
1. Paste the object ID of the managed identity for your Event Grid namespace.
67+
1. **Save** and **Confirm** access. Complete the role assignment and confirm access is reflected under the **Role assignments** tab.
68+
69+
### Use Azure CLI
70+
71+
1. Get the object ID of the managed identity for your Event Grid namespace.
72+
73+
```azurecli
74+
az eventgrid namespace identity show \
75+
--name <eventgrid-namespace-name> \
76+
--resource-group <eventgrid-resource-group> \
77+
--query principalId \
78+
--output tsv
79+
```
80+
81+
Save the output (let’s call it EG_MI_ID).
82+
2. Assign a role (for example, Contributor) to the managed identity on the Azure function or Webhook resource.
83+
84+
```azurecli
85+
az role assignment create \
86+
--assignee-object-id <EG_MI_ID> \
87+
--assignee-principal-type ServicePrincipal \
88+
--role "Contributor" \ # or use a least-privileged custom role
89+
--scope $(az functionapp show \
90+
--name <function-app-name> \
91+
--resource-group <function-app-resource-group> \
92+
--query id --output tsv)
93+
```
94+
You can replace **Contributor** with a custom role name that grants only required permissions (for example, **Azure Event Grid Event Subscription Contributor** for webhooks).
95+
96+
## Configure custom webhook authentication settings on your Event Grid namespace
97+
In this step, you configure custom webhook authentication settings on your Event Grid namespace using Azure portal and Azure CLI. You need to create the namespace first and then update it using the following steps.
98+
99+
### Use Azure portal
100+
101+
1. Navigate to your Event Grid namespace in the [Azure portal](https://portal.azure.com).
102+
1. On the **Event Grid Namespace** page, select **Configuration** on the left menu.
103+
1. In the **Custom Webhook authentication** section, specify values for the following properties:
104+
1. Select **Managed identity** type.
105+
1. For **Webhook URL**, enter the value of the URL endpoint where the Event Grid service sends authenticated webhook requests using the specified managed identity.
106+
1. For **Token audience URI**, enter the value of Microsoft Entra application ID or URI to get the access token that will be included as the bearer token in delivery requests.
107+
1. For **Microsoft Entra tenant ID**, enter the value of Microsoft Entra tenant ID used to acquire the bearer token for authenticated webhook delivery.
108+
1. Select **Apply**.
109+
110+
### Use Azure CLI
111+
112+
Use the following command to update your namespace with the custom webhook authentication configuration.
113+
114+
```azurecli
115+
az eventgrid namespace update \
116+
--resource-group <resource-group-name> \
117+
--name <namespace-name> \
118+
--api-version 2025-04-01-preview \
119+
--identity-type UserAssigned \
120+
--identity-user-assigned-identities "/subscriptions/XXXXXXXXXXX/resourcegroups/XXXXXXXXXXX/providers/Microsoft.ManagedIdentity/userAssignedIdentities/XXXXXXXXXXX={}" \
121+
--set properties.isZoneRedundant=true \
122+
properties.topicSpacesConfiguration.state=Enabled \
123+
properties.topicSpacesConfiguration.clientAuthentication.webHookAuthentication.identity.type=UserAssigned \
124+
properties.topicSpacesConfiguration.clientAuthentication.webHookAuthentication.identity.userAssignedIdentity="/subscriptions/XXXXXXXXXXX/resourcegroups/XXXXXXXXXXX/providers/Microsoft.ManagedIdentity/userAssignedIdentities/XXXXXXXXXXX" \
125+
properties.topicSpacesConfiguration.clientAuthentication.webHookAuthentication.endpointUrl="https://XXXXXXXXXXX" \
126+
properties.topicSpacesConfiguration.clientAuthentication.webHookAuthentication.azureActiveDirectoryApplicationIdOrUri="api://XXXXXXXXXXX/.default" \
127+
properties.topicSpacesConfiguration.clientAuthentication.webHookAuthentication.azureActiveDirectoryTenantId="XXXXXXXXXXX"
128+
```
129+
130+
Replace <NAMESPACE_NAME> and <RESOURCE_GROUP_NAME> with your actual values, and fill in the placeholders in the subscription/resource group/identity/app ID/URL/tenant ID. To enhance the performance and reliability of webhook-based authentication for Azure Event Grid MQTT Broker, we strongly recommend enabling HTTP/2 support for your webhook endpoint.
131+
132+
## Webhook API details
133+
134+
### Request Headers
135+
136+
- Authorization: Bearer <token>
137+
- <token> is an Entra ID token for the managed identity configured to call the webhook.
138+
139+
### Request payload
140+
141+
```json
142+
{
143+
"clientId": "<string>",
144+
"userName": "<string>",
145+
"password": "<base64 encoded bytes>",
146+
"authenticationMethod": "<string>",
147+
"authenticationData": "<base64 encoded bytes>",
148+
"clientCertificate": "<certificate in PEM format>",
149+
"clientCertificateChain": "<certificates from chain in PEM format>"
150+
}
151+
```
152+
153+
### Payload field descriptions
154+
155+
| Field | Required/Optional | Description |
156+
|-----------------|------------------|---------|
157+
| clientId | Required | Client ID from MQTT CONNECT packet. |
158+
| userName | Optional | Username from MQTT CONNECT packet. |
159+
| password | Optional | Password from MQTT CONNECT packet in base64 encoding. |
160+
| authenticationMethod | Optional | Authentication method from MQTT CONNECT packet (MQTT5 only). |
161+
| authenticationData | Optional | Authentication data from MQTT CONNECT packet in base64 encoding (MQTT5 only). |
162+
| clientCertificate | Optional | Client certificate in PEM format. |
163+
| clientCertificateChain| Optional | Additional certificates provided by the client required for building the chain from the client certificate to the CA certificate. |
164+
| userProperties | Optional | User properties from CONNECT packet (MQTT5 only). |
165+
166+
### Response payload
167+
168+
#### Successful response
169+
170+
```json
171+
HTTP/1.1 200 OK
172+
Content-Type: application/json
173+
174+
{
175+
"decision": "allow",
176+
"clientAuthenticationName": "<string>",
177+
"attributes": {
178+
"attr": "<int/string/array_of_strings>",
179+
...
180+
},
181+
"expiration": "<unix time format>"
182+
}
183+
```
184+
185+
#### Denied response
186+
187+
```json
188+
HTTP/1.1 400 Bad Request
189+
Content-Type: application/json
190+
191+
{
192+
"decision": "deny",
193+
"errorReason": "<string>"
194+
}
195+
```
196+
197+
### Response field descriptions
198+
199+
200+
| Field | Description |
201+
|---------------------------|------------------------------------|
202+
| Decision (required) | Authentication decision. Can be either **allow** or **deny**. |
203+
| clientAuthenticationName | Client authentication name (identity name). (Required when Decision is set to allow). |
204+
| attributes | Dictionary with attributes. Key is the attribute name, and the value can be an int/string/array. (Optional when Decision is set to allow). |
205+
| expiration | Expiration date in Unix time format. (Optional when Decision is set to allow) |
206+
| errorReason | Error message if decision is set to deny. This error is logged. (Optional when Decision is set to deny) |
207+
208+
### Examples of supported attribute types:
209+
210+
```json
211+
"bool_attr": true,
212+
  "num_attr_pos": 1,
213+
  "num_attr_neg": -1,
214+
  "num_attr_to_big": 9223372036854775807,
215+
  "num_attr_float": 1.23,
216+
  "str_attr": "str_value",
217+
  "str_list_attr": [
218+
    "str_value_1",
219+
    "str_value_2"]
220+
```
221+
222+
## Related content
223+
- [MQTT client authentication](mqtt-client-authentication.md)
224+
- [Authenticate client using custom JWT](mqtt-client-custom-jwt.md)

‎articles/event-grid/toc.yml

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -118,8 +118,6 @@ items:
118118
href: mqtt-request-response-messages.md
119119
- name: Assign custom domain name to a namespace
120120
href: assign-custom-domain-name.md
121-
- name: Authenticate with MQTT broker using OAuth 2.0 authentication
122-
href: authenticate-with-namespaces-using-json-web-tokens.md
123121
- name: Monitor
124122
items:
125123
- name: Monitor Event Grid namespaces
@@ -140,6 +138,10 @@ items:
140138
href: event-grid-namespace-managed-identity.md
141139
- name: MQTT client authentication using certificate chain
142140
href: mqtt-certificate-chain-client-authentication.md
141+
- name: Authenticate with MQTT broker using OAuth 2.0 authentication
142+
href: authenticate-with-namespaces-using-json-web-tokens.md
143+
- name: Authenticate with MQTT broker using webhook authentication
144+
href: authenticate-with-namespaces-using-webhook-authentication.md
143145
- name: Namespace topics
144146
items:
145147
- name: Pull delivery overview

0 commit comments

Comments
 (0)