Prima di iniziare

Prima di abilitare la protezione, devi creare una coppia di chiave pubblica / privata RS256. Puoi utilizzare uno strumento come OpenSSL o PuTTYgen.

Ad esempio, per creare la coppia di chiavi in un prompt dei comandi utilizzando OpenSSL, utilizzare il comando openssl genrsa -out key.pem 2048.

Salvare la coppia chiave generata in un'ubicazione sicura.

Assicurarsi che queste chiavi siano accessibili solo dal codice server. Non trasmetterli mai a un browser client attraverso il tuo sito web.

Generazione di un JWT

Per utilizzare la sicurezza della chat web, devi configurare la chat web sul tuo sito web per inviare un JWT (JSON Web Token) con ogni messaggio all'assistente. Il JWT viene utilizzato per verificare l'origine dei messaggi inviati dal tuo sito web e facoltativamente per trasportare ulteriori dati crittografati. Il tuo sito web dovrà essere in grado di creare un nuovo JWT all'inizio di ogni sessione, e anche ogni volta che un JWT esistente scade.

Non codificare un JWT nel codice del sito Web o condividere i JWT tra gli utenti.

Sul server, implementare una funzione che genera e restituisce un JWT (JSON Web Token) firmato con la chiave privata. Utilizzerai questo token per verificare l'origine dei messaggi inviati dal tuo sito web e facoltativamente per trasportare ulteriori dati crittografati.

La maggior parte dei linguaggi di programmazione offre librerie JWT che puoi utilizzare per generare un token. Per convalidare i JWT firmati, l'integrazione della chat web utilizza la libreria jsonwebtoken con l'algoritmo RS256.

Il payload JWT deve specificare le seguenti richieste:

• sub: un ID utente univoco che identifica il cliente che interagisce con la chat web. Può essere un identificativo univoco generato (per utenti anonimi) o un ID utente autenticato. Per ulteriori informazioni su come viene utilizzato il valore sub, vedi Autenticazione degli utenti nella chat web.

  Per garantire la sicurezza, il JWT deve essere specifico per ciascun utente. Utilizzare le informazioni di accesso autenticate dell'utente o un ID univoco generato. Non riutilizzare lo stesso JWT o lo stesso valore sub per più di un utente.

• exp: l'ora di scadenza dopo la quale il JWT non è più valido. Molte librerie JWT impostano automaticamente questo valore. Impostare una richiesta exp di breve durata (ad esempio, 1h).

  Non creare un JWT senza una richiesta exp. Anche se questa richiesta non è formalmente richiesta, ometterla rappresenta un rischio per la sicurezza perché chiunque abbia accesso al JWT può copiarla e utilizzarla in un secondo momento per accedere al tuo assistente. L'impostazione di una scadenza limita questa esposizione.

Il seguente esempio JavaScript mostra come generare un JWT utilizzando la libreria jsonwebtoken :

// Sample NodeJS code on your server.
const jwt = require('jsonwebtoken');

// Returns a signed JWT signed with the RS256 algorithm.
function createJWT() {
  const payload = {
    sub: 'some-user-id', // Identifies user for billing purposes
  };
  // The "expiresIn" option adds an "exp" claim to the payload.
  return jwt.sign(payload,
    process.env.YOUR_PRIVATE_RSA_KEY,
    { algorithm: 'RS256', expiresIn: '1h' });
}

Configurazione della chat Web per includere i JWT

Ora che è stata implementata una funzione per generare un JWT firmato, è necessario aggiornare l'istanza della chat Web per includere il JWT firmato con ogni messaggio inviato. Dopo aver abilitato la sicurezza della chat Web, tutti i messaggi non firmati con la chiave privata appropriata vengono rifiutati.

Nell'HTML del sito Web, aggiornare lo script di incorporazione della chat Web per specificare un nuovo JWT all'inizio di ogni sessione e anche ogni volta che il JWT esistente scade. Il modo più semplice per eseguire questa operazione è sottoscrivere l'evento identityTokenExpired e generare un nuovo JWT quando tale evento viene ricevuto. L'evento identityTokenExpired viene attivato in entrambe le seguenti situazioni:

• All'inizio di una nuova sessione, se non è stato fornito alcun JWT utilizzando l'opzione di configurazione identityToken.

• Quando il JWT precedentemente specificato scade.

Nel tuo gestore eventi onLoad, utilizza il metodo dell'istanza on() per sottoscrivere l'evento identityTokenExpired.

Nel callback, richiamare la funzione sul proprio server implementata per generare un nuovo JWT. Quindi, utilizzare il parametro identityToken dell'evento per specificare il nuovo JWT, come in questo esempio:

instance.on({ type: 'identityTokenExpired',
              handler: async function(event) {
                const jwtFromServer = await fetch('http://example.com:3001/createJWT');
                event.identityToken = jwtFromServer;
}});

Il nuovo JWT specificato viene inviato automaticamente con ogni messaggio successivo dall'istanza di chat Web sul proprio sito Web (fino alla scadenza del token).

È inoltre possibile specificare il JWT all'inizio della sessione utilizzando la proprietà identityToken nell'oggetto di configurazione della chat web. Tuttavia, sarà ancora necessario creare un gestore eventi per identityTokenExpired, a meno che non si sia certi che i JWT non scadranno mai durante una sessione.

Aggiornamento delle impostazioni della chat web

Ora che la chat web è stata configurata per inviare JWTs firmati, è possibile abilitare la sicurezza della chat web nelle impostazioni di integrazione della chat web.

Dopo aver abilitato la sicurezza della chat web, i messaggi provenienti da qualsiasi origine diversa dall'istanza della chat web (che è stata configurata per inviare JWT firmati) vengono rifiutati. Ciò significa che l'abilitazione della sicurezza della chat Web disabilita il link di anteprima condivisibile, che non invia JWT con messaggi. Per ulteriori informazioni sul link di anteprima, consultare Copia di un link da condividere.

Per abilitare la sicurezza, completa la seguente procedura:

1. Nella scheda Sicurezza delle impostazioni di integrazione della chat web, impostare l'opzione Proteggi la chat web su On.

2. Nel campo La tua chiave pubblica, incolla la tua chiave pubblica.

   watsonx Assistant utilizza la chiave pubblica per verificare che i messaggi in entrata abbiano origine dal sito web.

Il seguente diagramma mostra il flusso di messaggi tra la chat web e l'assistente quando la sicurezza della chat web è abilitata: