Udostępnij za pośrednictwem

Dostarczanie zdarzeń elementów webhook

  • Artykuł

Elementy webhook są jednym z wielu sposobów odbierania zdarzeń z usługi Azure Event Grid. Gdy nowe zdarzenie jest gotowe, usługa Event Grid poSTs żądanie HTTP do skonfigurowanego punktu końcowego z informacjami o zdarzeniu w treści żądania.

Podobnie jak wiele innych usług obsługujących elementy webhook, usługa Event Grid wymaga potwierdzenia własności punktu końcowego elementu webhook przed rozpoczęciem dostarczania zdarzeń do tego punktu końcowego. To wymaganie uniemożliwia złośliwemu użytkownikowi zalanie punktu końcowego zdarzeniami.

Walidacja punktu końcowego ze zdarzeniami usługi Event Grid

Jeśli używasz dowolnej z następujących trzech usług platformy Azure, infrastruktura platformy Azure automatycznie obsługuje tę walidację:

Jeśli używasz dowolnego innego typu punktu końcowego, takiego jak funkcja platformy Azure oparta na wyzwalaczu HTTP, kod punktu końcowego musi uczestniczyć w uzgadnianiu walidacji za pomocą usługi Event Grid. Usługa Event Grid obsługuje dwa sposoby weryfikowania subskrypcji.

  • Synchroniczne uzgadnianie: w momencie tworzenia subskrypcji zdarzeń usługa Event Grid wysyła zdarzenie weryfikacji subskrypcji do punktu końcowego. Schemat tego zdarzenia jest podobny do każdego innego zdarzenia usługi Event Grid. Część danych tego zdarzenia zawiera validationCode właściwość. Aplikacja sprawdza, czy żądanie weryfikacji dotyczy oczekiwanej subskrypcji zdarzeń i zwraca kod weryfikacji w odpowiedzi synchronicznie. Ten mechanizm uzgadniania jest obsługiwany we wszystkich wersjach usługi Event Grid.

  • Asynchroniczne uzgadnianie: w niektórych przypadkach nie można synchronicznie zwrócić validationCode w odpowiedzi. Jeśli na przykład używasz usługi innej firmy (takiej jak Zapier lub IFTTT), nie możesz programowo odpowiedzieć przy użyciu kodu weryfikacji.

    Usługa Event Grid obsługuje uzgadnianie ręcznej weryfikacji. Jeśli tworzysz subskrypcję zdarzeń przy użyciu zestawu SDK lub narzędzia korzystającego z interfejsu API w wersji 2018-05-01-preview lub nowszej, usługa Event Grid wysyła validationUrl właściwość w części danych zdarzenia weryfikacji subskrypcji. Aby ukończyć uzgadnianie, znajdź ten adres URL w danych zdarzenia i wykonaj do niego żądanie GET. Możesz użyć klienta REST lub przeglądarki internetowej.

    Podany adres URL jest ważny przez 10 minut. W tym czasie stan aprowizacji subskrypcji zdarzeń to AwaitingManualAction. Jeśli nie ukończysz ręcznej weryfikacji w ciągu 10 minut, stan aprowizacji zostanie ustawiony na Failedwartość . Przed rozpoczęciem ręcznej weryfikacji należy ponownie utworzyć subskrypcję zdarzeń.

    Ten mechanizm uwierzytelniania wymaga również, aby punkt końcowy elementu webhook zwrócił kod stanu HTTP 200, aby wiedział, że post dla zdarzenia weryfikacji został zaakceptowany, zanim będzie można go umieścić w trybie ręcznej weryfikacji. Innymi słowy, jeśli punkt końcowy zwraca wartość 200, ale nie zwraca odpowiedzi weryfikacji synchronicznie, tryb zostanie przeniesiony do trybu ręcznego sprawdzania poprawności. Jeśli adres URL weryfikacji znajduje się w adresie URL weryfikacji w ciągu 10 minut, uzgadnianie weryfikacji jest uznawane za pomyślne.

Uwaga

Używanie certyfikatów z podpisem własnym do weryfikacji nie jest obsługiwane. Zamiast tego użyj podpisanego certyfikatu z komercyjnego urzędu certyfikacji.

Szczegóły weryfikacji

  • W momencie tworzenia/aktualizowania subskrypcji zdarzeń usługa Event Grid publikuje zdarzenie weryfikacji subskrypcji do docelowego punktu końcowego.
  • Zdarzenie zawiera wartość aeg-event-type: SubscriptionValidationnagłówka .
  • Treść zdarzenia ma ten sam schemat co inne zdarzenia usługi Event Grid.
  • Właściwość eventType zdarzenia to Microsoft.EventGrid.SubscriptionValidationEvent.
  • Właściwość data zdarzenia zawiera validationCode właściwość z losowo wygenerowanym ciągiem. Na przykład validationCode: acb13….
  • Dane zdarzenia zawierają validationUrl również właściwość z adresem URL umożliwiającym ręczne weryfikowanie subskrypcji.
  • Tablica zawiera tylko zdarzenie weryfikacji. Inne zdarzenia są wysyłane w osobnym żądaniu po powtórzeniu kodu weryfikacji.
  • Zestawy SDK płaszczyzny danych EventGrid mają klasy odpowiadające danym zdarzenia weryfikacji subskrypcji i odpowiedzi na walidację subskrypcji.

Przykład SubscriptionValidationEvent jest pokazany w poniższym przykładzie:

[
  {
    "id": "2d1781af-3a4c-4d7c-bd0c-e34b19da4e66",
    "topic": "/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "subject": "",
    "data": {
      "validationCode": "512d38b6-c7b8-40c8-89fe-f46f9e9622b6",
      "validationUrl": "https://rp-eastus2.eventgrid.azure.net:553/eventsubscriptions/myeventsub/validate?id=0000000000-0000-0000-0000-00000000000000&t=2022-10-28T04:23:35.1981776Z&apiVersion=2018-05-01-preview&token=1A1A1A1A"
    },
    "eventType": "Microsoft.EventGrid.SubscriptionValidationEvent",
    "eventTime": "2022-10-28T04:23:35.1981776Z",
    "metadataVersion": "1",
    "dataVersion": "1"
  }
]

Aby udowodnić własność punktu końcowego, powtórz kod weryfikacji we validationResponse właściwości, jak pokazano w poniższym przykładzie:

{
  "validationResponse": "512d38b6-c7b8-40c8-89fe-f46f9e9622b6"
}

Wykonaj jedną z następujących czynności:

  • Musisz zwrócić kod stanu odpowiedzi HTTP 200 OK . Akceptowany protokół HTTP 202 nie jest rozpoznawany jako prawidłowa odpowiedź na walidację subskrypcji usługi Event Grid. Żądanie HTTP musi zostać ukończone w ciągu 30 sekund. Jeśli operacja nie zostanie zakończona w ciągu 30 sekund, operacja zostanie anulowana i może zostać ponownie odcięta po 5 sekundach. Jeśli wszystkie próby kończą się niepowodzeniem, jest on traktowany jako błąd uzgadniania sprawdzania poprawności.

    Fakt, że aplikacja jest przygotowana do obsługi i zwracania kodu weryfikacji wskazuje, że utworzono subskrypcję zdarzeń i oczekiwano odebrania zdarzenia. Wyobraź sobie scenariusz, w którym nie jest obsługiwana walidacja uzgadniania, a haker poznaje adres URL aplikacji. Haker może utworzyć temat i subskrypcję zdarzeń przy użyciu adresu URL aplikacji i rozpocząć przeprowadzanie ataku DoS do aplikacji, wysyłając wiele zdarzeń. Walidacja uzgadniania zapobiega temu.

    Załóżmy, że masz już zaimplementowaną walidację w aplikacji, ponieważ utworzono własne subskrypcje zdarzeń. Nawet jeśli haker tworzy subskrypcję zdarzeń z adresem URL aplikacji, poprawna implementacja zdarzenia żądania weryfikacji sprawdza aeg-subscription-name nagłówek w żądaniu, aby upewnić się, że jest to subskrypcja zdarzeń rozpoznana.

    Nawet po tej poprawnej implementacji uzgadniania haker może zalać aplikację (już zweryfikowaną subskrypcję zdarzeń), replikując żądanie, które wydaje się pochodzić z usługi Event Grid. Aby temu zapobiec, należy zabezpieczyć element webhook przy użyciu uwierzytelniania firmy Microsoft Entra. Aby uzyskać więcej informacji, zobacz Dostarczanie zdarzeń do chronionych punktów końcowych firmy Microsoft.

  • Możesz też ręcznie zweryfikować subskrypcję, wysyłając żądanie GET do adresu URL weryfikacji. Subskrypcja zdarzeń pozostaje w stanie oczekiwania do momentu zweryfikowania. Adres URL weryfikacji używa portu 553. Jeśli reguły zapory blokują port 553, należy zaktualizować reguły pomyślnego ręcznego uzgadniania.

    Jeśli zweryfikujesz zdarzenie weryfikacji subskrypcji, jeśli zidentyfikujesz, że nie jest to subskrypcja zdarzeń, dla której oczekujesz zdarzeń, nie zostanie zwrócona odpowiedź 200 ani żadna odpowiedź. W związku z tym walidacja kończy się niepowodzeniem.

Przykład obsługi uzgadniania weryfikacji subskrypcji można znaleźć w przykładzie języka C#.

Walidacja punktu końcowego za pomocą rozwiązania CloudEvents w wersji 1.0

Rozwiązanie CloudEvents w wersji 1.0 implementuje własną semantyka ochrony przed nadużyciami przy użyciu metody HTTP OPTIONS . Więcej informacji na ten temat można znaleźć tutaj. W przypadku używania schematu CloudEvents dla danych wyjściowych usługa Event Grid używa ochrony przed nadużyciami cloudEvents w wersji 1.0 zamiast mechanizmu zdarzeń weryfikacji usługi Event Grid.

Zgodność schematu zdarzeń

Po utworzeniu tematu jest definiowany przychodzący schemat zdarzeń. Po utworzeniu subskrypcji definiowany jest schemat zdarzeń wychodzących. W poniższej tabeli przedstawiono zgodność dozwoloną podczas tworzenia subskrypcji.

Schemat zdarzeń przychodzących Schemat zdarzeń wychodzących Obsługiwane
Schemat usługi Event Grid Schemat usługi Event Grid Tak
Schemat zdarzeń w chmurze w wersji 1.0 Tak
Niestandardowy schemat danych wejściowych Nie.
Schemat zdarzeń w chmurze w wersji 1.0 Schemat usługi Event Grid Nie.
Schemat zdarzeń w chmurze w wersji 1.0 Tak
Niestandardowy schemat danych wejściowych Nie.
Niestandardowy schemat danych wejściowych Schemat usługi Event Grid Tak
Schemat zdarzeń w chmurze w wersji 1.0 Tak
Niestandardowy schemat danych wejściowych Tak

Następne kroki

Zapoznaj się z następującym artykułem, aby dowiedzieć się, jak rozwiązywać problemy z weryfikacjami subskrypcji zdarzeń: Rozwiązywanie problemów z walidacją subskrypcji zdarzeń.