Condividi tramite

Convalida degli endpoint con lo schema eventi di Event Grid

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 pos di una richiesta HTTP all'endpoint configurato con le informazioni sull'evento nel corpo della richiesta.

Analogamente a molti altri servizi che supportano webhook, Griglia di eventi richiede di dimostrare la proprietà dell'endpoint del webhook prima di iniziare a recapitare 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:

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 evento, 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 Event Grid.

  • 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, trova l'URL nei dati dell'evento ed esegui una richiesta GET. È 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 non completi 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

  • Quando si crea o si aggiorna una sottoscrizione di eventi, Griglia di eventi invia un evento di convalida della sottoscrizione all'endpoint di destinazione.
  • L'evento include un'intestazione con il valore aeg-event-type: SubscriptionValidation.
  • Il corpo dell'evento segue lo stesso schema di altri eventi di Griglia di eventi.
  • La proprietà eventType dell'evento è Microsoft.EventGrid.SubscriptionValidationEvent.
  • La data proprietà dell'evento contiene una validationCode proprietà 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 che corrispondono ai dati degli eventi di convalida della sottoscrizione e alla risposta di convalida della sottoscrizione.

Nell'esempio seguente viene illustrato un oggetto SubscriptionValidationEvent:

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

Segui uno di questi passaggi:

  • È necessario restituire un codice di stato risposta HTTP 200 OK. HTTP 202 Accettata non è riconosciuta come una risposta di convalida della sottoscrizione di Event Grid valida. La richiesta HTTP deve essere completata entro 30 secondi. Se l'operazione non viene completata entro 30 secondi, l'operazione viene annullata e ripetuta dopo 5 secondi. Se tutti i tentativi hanno esito negativo, l'operazione viene considerata come un errore di handshake di convalida.

    Il fatto che l'applicazione sia pronta a gestire e restituire il codice di convalida indica che si è creata la sottoscrizione evento e si prevede di ricevere l'evento. Immagina uno scenario in cui la convalida dell'handshake non è supportata e un malintenzionato venga a conoscenza dell'URL della tua applicazione. L'attore malintenzionato può creare un argomento e una sottoscrizione di eventi con l'URL dell'applicazione e iniziare a condurre un attacco DoS all'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 attore non valido 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 verificare che si tratti di una sottoscrizione di eventi riconosciuta.

    Anche dopo l'implementazione corretta dell'handshake, un attore malintenzionato può inondare l'app (già convalidata la sottoscrizione di eventi) 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 è una sottoscrizione evento per cui si prevedono eventi, non restituire una risposta 200 o non restituire alcuna 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 Risolvere i problemi relativi alle convalide delle sottoscrizioni di eventi.

  • Last updated on