Autenticazione webhook

Introduzione

Verificare la legittimità delle richieste webhook in entrata è fondamentale per l’autenticazione dei webhook. Questo processo garantisce che le richieste provengano da fonti attendibili, proteggendo le applicazioni da accessi non autorizzati e attività dannose. Senza un’adeguata autenticazione, i sistemi rischiano violazioni dei dati e sfruttamento.

Questa pagina fornisce un’introduzione ai webhook e al loro funzionamento. Per un approfondimento sui webhook, visita il nostro portale per sviluppatori qui.

Cos’è un webhook?

Un webhook richiede un mittente (configurato per riconoscere gli eventi) e un destinatario (un’applicazione con un’API). Quando si verifica un evento, il mittente notifica il destinatario. I webhook sono un modo semplice per iscriversi alle risposte agli eventi dell’applicazione.

I webhook ti notificano automaticamente tramite un evento se vengono pubblicate nuove informazioni o dati.

Vediamo un esempio pratico:

1. Il tuo volo è in ritardo.
2. Il webhook viene attivato a causa del ritardo.
3. Riceverai una notifica push che ti avviserà del ritardo.

Tipi di Webhook

In questo documento, esamineremo alcuni esempi introduttivi di tre metodi di autenticazione Webhook offerti da Esendex. Per esempi e informazioni più dettagliate, puoi accedere al portale per sviluppatori qui (aggiungere il link quando sarà attivo).

Nota: attualmente, è possibile utilizzare un solo metodo di autenticazione Webhook per account. Se si tenta di utilizzarne più di uno, verrà visualizzato un messaggio di errore che indica che ne è consentito solo uno.

Autenticazione di base

Cos’è l’autenticazione di base?

L’autenticazione di base è un semplice metodo di autenticazione HTTP che richiede ai clienti di inserire nome utente e password per accedere a un endpoint API. Questo approccio è comunemente utilizzato per proteggere le API, garantendo che solo gli utenti autorizzati possano accedere a determinate risorse.

Flusso operativo

• Durante la configurazione dell’autenticazione di base per un webhook, è possibile fornire una combinazione di nome utente e password oppure direttamente il token di autenticazione di base. Questa flessibilità semplifica l’integrazione e la gestione delle credenziali di sicurezza.

• Quando viene fornita una combinazione di nome utente e password, generiamo un token di autenticazione utilizzando la codifica Base64 (nel formato `nomeutente:password`). Questo approccio segue il meccanismo standard utilizzato nell’autenticazione di base.

• Se l’utente non segue le linee guida specificate per la creazione del token, offriamo un’alternativa che consente di impostare il token direttamente.

Token di verifica 0Auth (Bearer Token).

Cos’è 0Auth?

In Auth0, il processo di autenticazione tramite token richiede agli utenti di confermare la propria identità. Una volta completata con successo la verifica, Auth0 genera un token univoco, come ad esempio un *access token* (token di accesso). Questo token consente agli utenti di accedere a risorse protette, eliminando la necessità di inserire ripetutamente le proprie credenziali.

Il processo

• La nostra piattaforma necessita dell’autorizzazione per inviare informazioni al server del cliente. A tal fine, è necessaria una chiave speciale che dimostri la nostra autorizzazione a procedere.

• La piattaforma del cliente dispone di un Server di Autorizzazione che agisce come un “guardiano” (gatekeeper) ed emette chiavi di accesso temporanee, denominate *Access Token*.

• Forniamo alla nostra piattaforma un ID pubblico affinché il server del cliente possa riconoscerci; successivamente, ne dimostriamo l’autenticità fornendo un codice segreto (*clientSecurityValue*) noto solo a noi e al server di autorizzazione del cliente.

• Indichiamo quindi alla nostra piattaforma dove ottenere l’*Access Token* dal cliente (*tokenUrl*) e quale codice segreto utilizzare per superare il controllo del server di autorizzazione del cliente.

• Se il server di autorizzazione verifica e convalida tali dati, emette un *Access Token* temporaneo a favore della nostra piattaforma; questo token consente l’invio di informazioni al server del cliente ed è associato a un *timestamp* che ne determina la scadenza dopo un intervallo di tempo prestabilito.

• A questo punto, quando la nostra piattaforma invia una chiamata webhook al server del cliente, include l’*Access Token* come prova dell’avvenuta autorizzazione. Se il token viene accettato, l’invio delle informazioni ha esito positivo.

• Per ogni chiamata webhook è necessario utilizzare un nuovo *Access Token*.

Intestazione personalizzata (chiave API)

Cos’è un’intestazione personalizzata (Custom Header)?

L’autenticazione tramite chiave API in un’intestazione personalizzata è un metodo che utilizza una chiave univoca generata dal server. I client includono questa chiave in un’intestazione HTTP personalizzata quando effettuano richieste per accedere a un’API. Questo approccio garantisce un accesso sicuro verificando l’identità del client che effettua la richiesta.

Il processo

• 1. Chiave API: Una chiave API è una stringa segreta che identifica il mittente del webhook.
  • La chiave API verrà generata da noi per te (quindi rilassati e lascia che siamo noi a occuparcene).
  • La ​​tua chiave API deve essere univoca; la best practice prevede la generazione di una nuova chiave API per ogni sottoscrizione al webhook.
  • La tua chiave API è un’informazione sensibile e verrà trattata come tale.

• 2. Intestazione personalizzata (Custom Header): La chiave API viene inviata tramite un’intestazione HTTP personalizzata, definita dal destinatario (consumer) del webhook.
  • Il nome dell’intestazione personalizzata è solitamente un identificatore univoco, come “x-api-key” o “api-key”.
  • Si consiglia l’uso di HTTPS per la comunicazione del webhook, al fine di proteggere la chiave API e gli altri dati in transito.

• 3.  Richiesta Webhook: Quando il webhook viene attivato, il produttore del webhook (Esendex Connect) include nella richiesta un’intestazione personalizzata contenente la chiave API.
  • Il destinatario del webhook deve essere configurato per riconoscere l’intestazione personalizzata e la relativa chiave API.
• 4. Autenticazione: Il destinatario del webhook verifica la presenza e la validità dell’intestazione personalizzata contenente la chiave API. Se l’intestazione è presente e la chiave API è corretta, la richiesta webhook viene considerata autentica.
  • La chiave API sarà composta da 32 caratteri alfanumerici (case-sensitive).
• 5. Validazione: Il destinatario del webhook (l’utente, ovvero tu) convalida la richiesta webhook utilizzando la chiave API per decidere se autenticarla.

Esempio

Supponiamo che tu abbia una chiave API, “MY_ESENDEX_CONNECT_KEY”, e che tu voglia utilizzarla in un’intestazione personalizzata chiamata “x-my-titan-key”. La richiesta webhook dovrebbe includere questa intestazione:

x-titan-app-key: ESENDEX_ CONNECT_API_KEY

Il destinatario del webhook deve verificare che tale intestazione esista e che il valore “MY_ESENDEX_CONNECT_KEY” corrisponda a una chiave API valida.

Puoi approfondire l’argomento dei webhook nel nostro portale per sviluppatori qui.