Skip to content

Commit db860f8

Browse files
ktoliverktoliver
authored
Merge pull request #51673 from batrived/patch-2
EventSubscription validation troubleshooting section
2 parents a440255 + cfe9f4e commit db860f8

File tree

1 file changed

+52
-38
lines changed

1 file changed

+52
-38
lines changed

‎articles/event-grid/security-authentication.md

Lines changed: 52 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -10,66 +10,69 @@ ms.topic: conceptual
1010
ms.date: 03/06/2020
1111
ms.author: babanisa
1212
---
13+
1314
# Authenticating access to Event Grid resources
1415

1516
Azure Event Grid has three types of authentication:
1617

17-
* WebHook event delivery
18-
* Event subscriptions
19-
* Custom topic publishing
18+
- WebHook event delivery
19+
- Event subscriptions
20+
- Custom topic publishing
2021

2122
## WebHook Event delivery
2223

2324
Webhooks are one of the many ways to receive events from Azure Event Grid. When a new event is ready, Event Grid service POSTs an HTTP request to the configured endpoint with the event in the request body.
2425

2526
Like many other services that support webhooks, Event Grid requires you to prove ownership of your Webhook endpoint before it starts delivering events to that endpoint. This requirement prevents a malicious user from flooding your endpoint with events. When you use any of the three Azure services listed below, the Azure infrastructure automatically handles this validation:
2627

27-
* Azure Logic Apps with [Event Grid Connector](https://docs.microsoft.com/connectors/azureeventgrid/)
28-
* Azure Automation via [webhook](../event-grid/ensure-tags-exists-on-new-virtual-machines.md)
29-
* Azure Functions with [Event Grid Trigger](../azure-functions/functions-bindings-event-grid.md)
28+
- Azure Logic Apps with [Event Grid Connector](https://docs.microsoft.com/connectors/azureeventgrid/)
29+
- Azure Automation via [webhook](../event-grid/ensure-tags-exists-on-new-virtual-machines.md)
30+
- Azure Functions with [Event Grid Trigger](../azure-functions/functions-bindings-event-grid.md)
3031

3132
If you're using any other type of endpoint, such as an HTTP trigger based Azure function, your endpoint code needs to participate in a validation handshake with Event Grid. Event Grid supports two ways of validating the subscription.
3233

33-
1. **ValidationCode handshake (programmatic)**: If you control the source code for your endpoint, this method is recommended. At the time of event subscription creation, Event Grid sends a subscription validation event to your endpoint. The schema of this event is similar to any other Event Grid event. The data portion of this event includes a `validationCode` property. Your application verifies that the validation request is for an expected event subscription, and echoes the validation code to Event Grid. This handshake mechanism is supported in all Event Grid versions.
34+
1. **Synchronous handshake**: At the time of event subscription creation, Event Grid sends a subscription validation event to your endpoint. The schema of this event is similar to any other Event Grid event. The data portion of this event includes a `validationCode` property. Your application verifies that the validation request is for an expected event subscription, and returns the validation code in the reponse synchronously. This handshake mechanism is supported in all Event Grid versions.
3435

35-
2. **ValidationURL handshake (manual)**: In certain cases, you can't access the source code of the endpoint to implement the ValidationCode handshake. For example, if you use a third-party service (like [Zapier](https://zapier.com) or [IFTTT](https://ifttt.com/)), you can't programmatically respond with the validation code.
36+
2. **Asynchronous handshake**: In certain cases, you can't return the ValidationCode in response synchronously. For example, if you use a third-party service (like [Zapier](https://zapier.com) or [IFTTT](https://ifttt.com/)), you can't programmatically respond with the validation code.
3637

37-
Starting with version 2018-05-01-preview, Event Grid supports a manual validation handshake. If you're creating an event subscription with an SDK or tool that uses API version 2018-05-01-preview or later, Event Grid sends a `validationUrl` property in the data portion of the subscription validation event. To complete the handshake, find that URL in the event data and manually send a GET request to it. You can use either a REST client or your web browser.
38+
Starting with version 2018-05-01-preview, Event Grid supports a manual validation handshake. If you're creating an event subscription with an SDK or tool that uses API version 2018-05-01-preview or later, Event Grid sends a `validationUrl` property in the data portion of the subscription validation event. To complete the handshake, find that URL in the event data and do a GET request to it. You can use either a REST client or your web browser.
3839

39-
The provided URL is valid for 5 minutes. During that time, the provisioning state of the event subscription is `AwaitingManualAction`. If you don't complete the manual validation within 5 minutes, the provisioning state is set to `Failed`. You'll have to create the event subscription again before starting the manual validation.
40+
The provided URL is valid for **5 minutes**. During that time, the provisioning state of the event subscription is `AwaitingManualAction`. If you don't complete the manual validation within 5 minutes, the provisioning state is set to `Failed`. You'll have to create the event subscription again before starting the manual validation.
4041

41-
This authentication mechanism also requires the webhook endpoint to return an HTTP status code of 200 so that it knows that the POST for the validation event was accepted before it can be put in the manual validation mode. In other words, if the endpoint returns 200 but doesn't return back a validation response programmatically, the mode is transitioned to the manual validation mode. If there's a GET on the validation URL within 5 minutes, the validation handshake is considered to be successful.
42+
This authentication mechanism also requires the webhook endpoint to return an HTTP status code of 200 so that it knows that the POST for the validation event was accepted before it can be put in the manual validation mode. In other words, if the endpoint returns 200 but doesn't return back a validation response synchronously, the mode is transitioned to the manual validation mode. If there's a GET on the validation URL within 5 minutes, the validation handshake is considered to be successful.
4243

4344
> [!NOTE]
4445
> Using self-signed certificates for validation isn't supported. Use a signed certificate from a certificate authority (CA) instead.
4546
4647
### Validation details
4748

48-
* At the time of event subscription creation/update, Event Grid posts a subscription validation event to the target endpoint.
49-
* The event contains a header value "aeg-event-type: SubscriptionValidation".
50-
* The event body has the same schema as other Event Grid events.
51-
* The eventType property of the event is `Microsoft.EventGrid.SubscriptionValidationEvent`.
52-
* The data property of the event includes a `validationCode` property with a randomly generated string. For example, "validationCode: acb13…".
53-
* The event data also includes a `validationUrl` property with a URL for manually validating the subscription.
54-
* The array contains only the validation event. Other events are sent in a separate request after you echo back the validation code.
55-
* The EventGrid DataPlane SDKs have classes corresponding to the subscription validation event data and subscription validation response.
49+
- At the time of event subscription creation/update, Event Grid posts a subscription validation event to the target endpoint.
50+
- The event contains a header value "aeg-event-type: SubscriptionValidation".
51+
- The event body has the same schema as other Event Grid events.
52+
- The eventType property of the event is `Microsoft.EventGrid.SubscriptionValidationEvent`.
53+
- The data property of the event includes a `validationCode` property with a randomly generated string. For example, "validationCode: acb13…".
54+
- The event data also includes a `validationUrl` property with a URL for manually validating the subscription.
55+
- The array contains only the validation event. Other events are sent in a separate request after you echo back the validation code.
56+
- The EventGrid DataPlane SDKs have classes corresponding to the subscription validation event data and subscription validation response.
5657

5758
An example SubscriptionValidationEvent is shown in the following example:
5859

5960
```json
60-
[{
61-
"id": "2d1781af-3a4c-4d7c-bd0c-e34b19da4e66",
62-
"topic": "/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
63-
"subject": "",
64-
"data": {
65-
"validationCode": "512d38b6-c7b8-40c8-89fe-f46f9e9622b6",
66-
"validationUrl": "https://rp-eastus2.eventgrid.azure.net:553/eventsubscriptions/estest/validate?id=512d38b6-c7b8-40c8-89fe-f46f9e9622b6&t=2018-04-26T20:30:54.4538837Z&apiVersion=2018-05-01-preview&token=1A1A1A1A"
67-
},
68-
"eventType": "Microsoft.EventGrid.SubscriptionValidationEvent",
69-
"eventTime": "2018-01-25T22:12:19.4556811Z",
70-
"metadataVersion": "1",
71-
"dataVersion": "1"
72-
}]
61+
[
62+
{
63+
"id": "2d1781af-3a4c-4d7c-bd0c-e34b19da4e66",
64+
"topic": "/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
65+
"subject": "",
66+
"data": {
67+
"validationCode": "512d38b6-c7b8-40c8-89fe-f46f9e9622b6",
68+
"validationUrl": "https://rp-eastus2.eventgrid.azure.net:553/eventsubscriptions/estest/validate?id=512d38b6-c7b8-40c8-89fe-f46f9e9622b6&t=2018-04-26T20:30:54.4538837Z&apiVersion=2018-05-01-preview&token=1A1A1A1A"
69+
},
70+
"eventType": "Microsoft.EventGrid.SubscriptionValidationEvent",
71+
"eventTime": "2018-01-25T22:12:19.4556811Z",
72+
"metadataVersion": "1",
73+
"dataVersion": "1"
74+
}
75+
]
7376
```
7477

7578
To prove endpoint ownership, echo back the validation code in the validationResponse property, as shown in the following example:
@@ -86,14 +89,24 @@ Or, you can manually validate the subscription by sending a GET request to the v
8689

8790
For an example of handling the subscription validation handshake, see a [C# sample](https://github.com/Azure-Samples/event-grid-dotnet-publish-consume-events/blob/master/EventGridConsumer/EventGridConsumer/Function1.cs).
8891

89-
### Checklist
92+
## Troubleshooting EventSubsciption Validation
9093

9194
During event subscription creation, if you're seeing an error message such as "The attempt to validate the provided endpoint https:\//your-endpoint-here failed. For more details, visit https:\//aka.ms/esvalidation", it indicates that there's a failure in the validation handshake. To resolve this error, verify the following aspects:
9295

93-
* Do you control of the application code running in the target endpoint? For example, if you're writing an HTTP trigger based Azure Function, do you have access to the application code to make changes to it?
94-
* If you have access to the application code, implement the ValidationCode based handshake mechanism as shown in the sample above.
96+
- Do a HTTP POST to your webhook url with a [sample SubscriptionValidationEvent](#validation-details) request body using Postman or curl or similar tool.
97+
- If your webhook is implementing synchronous validation handshake mechanism, verify that the ValidationCode is returned as part of the response.
98+
- If your webhook is implementing asynchronous validation handshake mechanism, verify that you are the HTTP POST is returning 200 OK.
99+
- If your webhook is returning 403 (Forbidden) in the response, check if your webhook is behind an Azure Application Gateway or Web Application Firewall. If it is, then your need to disable these firewall rules and do a HTTP POST again:
100+
101+
920300 (Request Missing an Accept Header, we can fix this)
102+
103+
942430 (Restricted SQL Character Anomaly Detection (args): # of special characters exceeded (12))
95104

96-
* If you don't have access to the application code (for example, if you're using a third-party service that supports webhooks), you can use the manual handshake mechanism. Make sure you're using the 2018-05-01-preview API version or later (install Event Grid Azure CLI extension) to receive the validationUrl in the validation event. To complete the manual validation handshake, get the value of the `validationUrl` property and visit that URL in your web browser. If validation is successful, you should see a message in your web browser that validation is successful. You'll see that event subscription's provisioningState is "Succeeded".
105+
920230 (Multiple URL Encoding Detected)
106+
107+
942130 (SQL Injection Attack: SQL Tautology Detected.)
108+
109+
931130 (Possible Remote File Inclusion (RFI) Attack = Off-Domain Reference/Link)
97110

98111
### Event delivery security
99112

@@ -102,6 +115,7 @@ During event subscription creation, if you're seeing an error message such as "T
102115
You can secure your webhook endpoint by using Azure Active Directory to authenticate and authorize Event Grid to publish events to your endpoints. You'll need to create an Azure Active Directory Application, create a role and service principle in your application authorizing Event Grid, and configure the event subscription to use the Azure AD Application. [Learn how to configure AAD with Event Grid](secure-webhook-delivery.md).
103116

104117
#### Query parameters
118+
105119
You can secure your webhook endpoint by adding query parameters to the webhook URL when creating an Event Subscription. Set one of these query parameters to be a secret such as an [access token](https://en.wikipedia.org/wiki/Access_token). The webhook can use the secret to recognize the event is coming from Event Grid with valid permissions. Event Grid will include these query parameters in every event delivery to the webhook.
106120

107121
When editing the Event Subscription, the query parameters aren't displayed or returned unless the [--include-full-endpoint-url](https://docs.microsoft.com/cli/azure/eventgrid/event-subscription?view=azure-cli-latest#az-eventgrid-event-subscription-show) parameter is used in Azure [CLI](https://docs.microsoft.com/cli/azure?view=azure-cli-latest).
@@ -132,7 +146,7 @@ For example, to subscribe to a custom topic named **mytopic**, you need the Micr
132146

133147
## Custom topic publishing
134148

135-
Custom topics use either Shared Access Signature (SAS) or key authentication. We recommend SAS, but key authentication provides simple programming, and is compatible with many existing webhook publishers.
149+
Custom topics use either Shared Access Signature (SAS) or key authentication. We recommend SAS, but key authentication provides simple programming, and is compatible with many existing webhook publishers.
136150

137151
You include the authentication value in the HTTP header. For SAS, use **aeg-sas-token** for the header value. For key authentication, use **aeg-sas-key** for the header value.
138152

@@ -191,4 +205,4 @@ All events or data written to disk by the Event Grid service is encrypted by a M
191205

192206
## Next steps
193207

194-
* For an introduction to Event Grid, see [About Event Grid](overview.md)
208+
- For an introduction to Event Grid, see [About Event Grid](overview.md)

0 commit comments

Comments
 (0)