Protezione dell'accesso alla Partita con Autenticazione JWT

L'Autenticazione JWT permette di trasmettere in modo sicuro le informazioni dei giocatori nella tua esperienza Drimify e controllare chi può accedervi. Anziché passare i dati dei giocatori come parametri di query — che chiunque può contraffare — il tuo sistema emette un JSON Web Token (JWT) firmato. Drimify verifica la firma usando il tuo segreto condiviso, per garantire che le informazioni sull'identità dei giocatori siano attendibili senza bisogno di callback server-to-server.

Questa soluzione è ideale per programmi di fedeltà, portali per membri e qualsiasi scenario in cui la partita è integrata in un ambiente autenticato e hai bisogno di sapere con certezza chi sta giocando.

Come funziona

1. Crei una Configurazione JWT nel tuo account Drimify (algoritmo + segreto).
2. Abiliti l'Autenticazione JWT sulla tua app e selezioni quella configurazione.
3. Il tuo sistema genera un token firmato contenente le informazioni del giocatore e lo passa all'apertura della partita.
4. Drimify verifica la firma e la scadenza del token, legge le informazioni mappate e consente l'accesso al giocatore. I token non validi o mancanti sono bloccati con una schermata di errore personalizzabile.

Fase 1 — Crea una Configurazione JWT

Vai a Il Mio Account → Configurazioni JWT (subito sotto Integrazioni) e clicca su aggiungi una nuova configurazione:

• Nome: Un'etichetta per il tuo riferimento personale.
• Algoritmo: L'algoritmo di firma usato dal tuo sistema. Supportati: HS256, HS384, HS512 (HMAC, segreto condiviso) e ES256, ES384 (ECDSA).
• Segreto: Il segreto condiviso usato per verificare la firma del token. Per motivi di sicurezza, i segreti HMAC devono rispettare una lunghezza minima: 32 caratteri per HS256, 48 per HS384, 64 per HS512. Il segreto è oscurato dopo il salvataggio.
• Spazi di lavoro: Seleziona quali spazi di lavoro possono usare questa configurazione. Un'app può utilizzare solo le configurazioni disponibili nella sua area di lavoro.

Mappatura campi (nomi dei claim)

Di default, Drimify legge i nomi dei claim standard dal tuo token. Se la tua fonte di token usa nomi di claim diversi (ad esempio user_email anziché email), usa la sezione mappatura campi per mappare ciascun nome di claim del tuo token al corrispondente parametro partita di Drimify.

La mappatura campi funziona come una lista di permessi: solo i campi che configuri vengono letti dal token. Ogni campo di Drimify può essere mappato una sola volta (nessun duplicato).

Fase 2 — Abilita l'autenticazione JWT sulla tua app

Nel tuo editor di app, apri la fase Impostazioni e attiva Abilita Autenticazione JWT. Poi:

• Seleziona la configurazione JWT da usare (solo le configurazioni disponibili nell'area di lavoro dell'app sono elencate — se non ne esistono, un collegamento ti porterà a Configurazioni JWT).
• Imposta facoltativamente un titolo e descrizione di errore personalizzati, mostrati ai giocatori quando l'accesso è negato (token mancante o non valido).

Fase 3 — Passa il token all'apertura della partita

Il tuo sistema può fornire il token in tre modi (se ne sono presenti diversi, questo è anche l'ordine di precedenza):

1. Header Bearer — Authorization: Bearer <token> — raccomandato per la produzione, dato che il token non appare mai in URL, registri o cronologia del browser.
2. Stringa di query — https://your-game-url?jwt=<token> — conveniente per i test, ma i token negli URL possono trapelare tramite registri e cronologia del browser.
3. Dati POST — un campo jwt=<token> nel modulo.

Requisiti del token

• Il token deve essere firmato con l'algoritmo e il segreto definiti nella tua Configurazione JWT.
• Includi un claim exp (scadenza) e mantieni brevi le durate del token — i token scaduti sono rifiutati. Una piccola tolleranza sui disallineamenti orari è applicata, quindi leggere differenze orarie tra server non causeranno fallimenti.
• I claim dovrebbero contenere i campi del giocatore che hai mappato nella configurazione (es. email, id univoco, nome utente, numero di telefono).

Esempio di payload

{
  "sub": "user-123",
  "email": "player@example.com",
  "iat": 1753257600,
  "exp": 1753261200
}

Puoi generare token di prova su jwt.io inserendo il tuo segreto nel campo di verifica della firma.## Comportamenti di sicurezza da tenere a mente

• I parametri di query non sovrascrivono più i dati del giocatore. Quando l'Autenticazione JWT è attivata, le informazioni sui giocatori provengono esclusivamente dal token verificato — i valori delle query-string vengono ignorati. Questo impedisce a chiunque di aggirare il token modificando l'URL.
• I limiti di partecipazione sono applicati dal token. Se la tua app limita le giocate per email o numero di telefono, il claim corrispondente deve essere presente nel token; in caso contrario l'accesso viene negato. Anche i valori di email o telefono non validi vengono rifiutati, quindi i limiti non possono essere aggirati con dati malformati.
• Le configurazioni in uso non possono essere eliminate. Una Configurazione JWT che è ancora referenziata da un'app deve essere disassegnata prima di poter essere rimossa.
• Tieni il tuo segreto al sicuro. Chiunque possieda il segreto può emettere token validi. Se un segreto viene compromesso, aggiorna la configurazione — nota che ciò invaliderà immediatamente tutti i token firmati con il vecchio segreto.

Risoluzione dei problemi

• I giocatori vedono la schermata di errore di accesso: Verifica che il token sia firmato con l'algoritmo e il segreto giusti, che non sia scaduto, e che venga trasmesso tramite uno dei tre metodi supportati.
• I dati del giocatore non compaiono: Verifica la tua mappatura campo — solo i claim mappati vengono letti dal token.
• La configurazione non è elencata nelle impostazioni dell'app: Assicurati che la configurazione sia abilitata per l'area di lavoro dell'app.

Aggiornato il: 24/07/2026