|
| 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) |
0 commit comments