Convalida degli endpoint con lo schema eventi di Griglia di eventi

I webhook sono uno dei molti modi per ricevere eventi da Griglia di eventi di Azure. Quando un nuovo evento è pronto, il servizio Griglia di eventi esegue il POST di una richiesta HTTP nell'endpoint configurato con le informazioni sull'evento nel corpo della richiesta.

Analogamente a molti altri servizi che supportano i webhook, Griglia di eventi richiede la dimostrazione della proprietà dell'endpoint del webhook prima dell'inizio del recapito di eventi a tale endpoint. Questo requisito impedisce a un utente malintenzionato di sovraccaricare l'endpoint con eventi.

Convalida degli endpoint con eventi di Griglia di eventi

Quando si usa uno dei tre servizi di Azure seguenti, l'infrastruttura di Azure gestisce automaticamente questa convalida:

• App per la logica di Azure con il connettore Griglia di eventi
• Automazione di Azure tramite webhook
• Funzioni di Azure con il trigger Griglia di eventi

Se si usa un altro tipo di endpoint, ad esempio un trigger HTTP basato su una funzione di Azure, il codice dell'endpoint deve partecipare a un handshake di convalida con Griglia di eventi. Griglia di eventi supporta due modalità di convalida della sottoscrizione.

• Handshake sincrono: al momento della creazione della sottoscrizione di eventi, Griglia di eventi invia un evento di convalida della sottoscrizione all'endpoint. Lo schema di questo evento è simile a qualsiasi altro evento di Griglia di eventi. La parte di dati dell'evento include una proprietà validationCode. L'applicazione verifica che la richiesta di convalida sia per una sottoscrizione di eventi prevista e restituisce il codice di convalida nella risposta in modo sincrono. Questo meccanismo di handshake è supportato in tutte le versioni di Griglia di eventi.

• Handshake asincrono: in alcuni casi non è possibile restituire validationCode in risposta in modo sincrono. Se ad esempio si usa un servizio non Microsoft, come Zapier o IFTTT, non è possibile rispondere a livello di codice con il codice di convalida.

  Griglia di eventi supporta un handshake di convalida manuale. Se si sta creando una sottoscrizione di eventi con un SDK o uno strumento che usa l'API 2018-05-01-preview o versione successiva, Griglia di eventi invia una proprietà validationUrl nella parte di dati dell'evento di convalida della sottoscrizione. Per completare l'handshake, trovare l'URL nei dati dell'evento ed eseguire una richiesta GET per tale URL. È possibile usare un client REST o un Web browser.

  L'URL specificato è valido per 10 minuti. Durante questo periodo, lo stato di provisioning della sottoscrizione di eventi è AwaitingManualAction. Se si non completata la convalida manuale entro 10 minuti, lo stato di provisioning è impostato su Failed. È possibile creare la sottoscrizione all'evento nuovamente prima di avviare la convalida manuale.

  Questo meccanismo di autenticazione richiede anche che l'endpoint del webhook restituisca il codice di stato HTTP 200 per sapere che la richiesta POST per l'evento di convalida è stata accettata prima di passare alla modalità di convalida manuale. In altre parole, se l'endpoint restituisce 200 ma non restituisce una risposta di convalida in modo sincrono, viene eseguita la transizione della modalità di convalida a manuale. Se entro 10 minuti viene riscontrata una richiesta GET per l'URL di convalida, l'handshake di convalida viene considerato riuscito.

Nota

L'uso di certificati autofirmati per la convalida non è supportato. Usare un certificato firmato da un'autorità di certificazione commerciale (CA, Certificate Authority).

Dettagli di convalida

• In fase di creazione/aggiornamento della sottoscrizione di eventi, Griglia di eventi inserisce un evento di convalida della sottoscrizione nell'endpoint di destinazione.
• L'evento contiene un valore di intestazione aeg-event-type: SubscriptionValidation.
• Il corpo dell'evento ha lo stesso schema degli altri eventi di Griglia di eventi.
• La proprietà eventType dell'evento è Microsoft.EventGrid.SubscriptionValidationEvent.
• La proprietà data dell'evento include una proprietà validationCode con una stringa generata in modo casuale. Ad esempio: validationCode: acb13….
• I dati dell'evento includono anche una proprietà validationUrl con un URL che è possibile usare per convalidare manualmente la sottoscrizione.
• La matrice contiene solo l'evento di convalida. Gli altri eventi vengono inviati in una richiesta separata dopo che è stato rimandato il codice di convalida.
• Gli SDK del piano dati di Griglia di eventi includono classi corrispondenti ai dati degli eventi di convalida della sottoscrizione e alla risposta di convalida della sottoscrizione.

Un esempio di SubscriptionValidationEvent è mostrato di seguito:

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

Per dimostrare la proprietà dell'endpoint, rimandare il codice di convalida nella proprietà validationResponse, come mostrato nell'esempio seguente:

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

Eseguire inoltre uno dei passaggi seguenti:

• È necessario restituire un codice di stato risposta HTTP 200 OK. HTTP 202 Accettata non è riconosciuto come risposta di convalida di sottoscrizione di Griglia di eventi valida. La richiesta HTTP deve essere completata entro 30 secondi. Se l'operazione non termina entro 30 secondi, verrà annullata e viene eseguito un nuovo tentativo dopo 5 secondi. Se tutti i tentativi hanno esito negativo, l'operazione viene considerata errore di handshake di convalida.

  Il fatto che l'applicazione sia pronta a gestire e restituire il codice di convalida indica che è stata creata la sottoscrizione di eventi e si prevede di ricevere l'evento. Si immagini uno scenario in cui non sia supportata la convalida dell'handshake e un hacker conosca l'URL dell'applicazione. L'hacker può creare un argomento e una sottoscrizione di eventi con l'URL dell'applicazione e iniziare a condurre un attacco DoS contro l'applicazione inviando molti eventi. La convalida dell'handshake impedisce che ciò accada.

  Si supponga di avere già implementato la convalida nell'app perché sono state create sottoscrizioni di eventi personalizzate. Anche se un hacker crea una sottoscrizione di eventi con l'URL dell'app, l'implementazione corretta dell'evento di richiesta di convalida verifica la presenza dell'intestazione aeg-subscription-name nella richiesta per confermare che si tratti di una sottoscrizione di eventi riconosciuta.

  Anche dopo l'implementazione corretta dell'handshake, un hacker può eseguire un attacco flood contro l'app (con sottoscrizione di eventi già convalidata) replicando una richiesta che sembra provenire da Griglia di eventi. Per evitare questo problema, è necessario proteggere il webhook con l'autenticazione di Microsoft Entra. Per altre informazioni, vedere Recapitare eventi agli endpoint protetti da Microsoft Entra.

• In alternativa, è possibile convalidare manualmente la sottoscrizione inviando una richiesta GET all'URL di convalida. La sottoscrizione dell'evento rimane nello stato in sospeso fino a quando non viene convalidata. L'URL di convalida usa la porta 553. Se le regole del firewall bloccano la porta 553, è necessario aggiornare le regole per consentire l'esito positivo di un handshake manuale.

  Nella convalida dell'evento di convalida della sottoscrizione, se si identifica che non si tratta di una sottoscrizione di eventi per cui si prevedono eventi, non verrebbe restituita una risposta 200 o nessuna risposta. Di conseguenza, la convalida non riesce.

Per un esempio di gestione dell'handshake di convalida della sottoscrizione, vedere un esempio C#.

Contenuto correlato

Per informazioni su come risolvere i problemi relativi alle convalide delle sottoscrizioni di eventi, vedere l'articolo seguente: Risolvere i problemi di convalida delle sottoscrizioni di eventi.