Identità firmata

Shayan TaslimAggiornato

Una chiamata uj.identify non firmata proviene dal browser, quindi chiunque può modificarla. L'identità firmata impedisce lo spoofing: il tuo server firma un JWT HS256 di breve durata che dimostra chi è l'utente, e il widget passa quel token a UserJot.

Tutto ciò che è contenuto nel token (ID utente, email, nome, avatar, attributi e aziende) viene considerato verificato.

Quando ne hai bisogno

  • Vuoi verificare che feedback, voti e conversazioni provengano dall'account effettivo connesso.

  • Vuoi consentire ai clienti di modificare ed eliminare i propri post di feedback e commenti all’interno del widget (le sessioni senza firma uj.identify non possono modificare né eliminare contenuti nel widget).

  • Hai attivato Richiedi token firmati in Impostazioni → Accesso (disponibile con i piani Starter e Professional una volta abilitato Accesso automatico); questa opzione rifiuta le chiamate identify senza firma e richiede inoltre che le appartenenze alle aziende siano incluse nel token firmato (ignorando le companies senza firma lato client e mostrando un avviso UNSIGNED_COMPANY_IGNORED).

  • Un amministratore o proprietario dell'area di lavoro sta usando il widget. L'identificazione non firmata non viene mai accettata per gli account con privilegi. Un token firmato applica i relativi attributi e aziende; nome, avatar ed email restano gestiti nella dashboard e, se vengono inviati, restituiscono un avviso PRIVILEGED_PROFILE_IGNORED.

Note

Se il tuo prodotto usa sia il widget web sia Swift SDK, attivando Richiedi token firmati imponi la verifica su entrambi. Il widget web usa un JWT HS256 (token), mentre Swift SDK usa un signature HMAC-SHA256 firmato con lo stesso segreto dell'area di lavoro.

1. Crea il token sul tuo server

Firma un JWT con HS256 usando il segreto della tua area di lavoro. Trovi sia l'ID progetto sia il Segreto progetto in Impostazioni → Accesso nella sezione Segreti.

Non firmare mai i token nel browser. Conserva il segreto sul tuo server.

Dichiarazioni obbligatorie

Dichiarazione

Valore

sub

L'ID stabile dell'utente nel tuo sistema. Obbligatorio.

iss

L'ID progetto di UserJot. Obbligatorio.

aud

La stringa esatta userjot. Obbligatoria.

iat

Timestamp di emissione in secondi Unix. Obbligatorio.

exp

Timestamp di scadenza in secondi Unix. Obbligatorio. Massimo 1 ora (3600 secondi) dopo iat.

Dichiarazioni verificate facoltative

Puoi includere anche email, firstName, lastName, avatar, traits e companies. Ogni voce in companies supporta:

JSON
{
  "companies": [
    {
      "id": "acme",
      "name": "ACME Inc.",
      "domain": "acme.com",
      "logo": "https://acme.com/logo.png",
      "traits": { "plan": "enterprise" }
    }
  ]
}

Esempi lato server

Node.js

JavaScript
import jwt from 'jsonwebtoken';

export function createUserJotToken(user, secret, projectId) {
  return jwt.sign(
    {
      sub: user.id,
      email: user.email,
      firstName: user.firstName,
      lastName: user.lastName,
      iss: projectId,
      aud: 'userjot'
    },
    secret,
    { algorithm: 'HS256', expiresIn: '1h' }
  );
}

Python

Python
import time
import jwt

def create_userjot_token(user, secret, project_id):
    now = int(time.time())
    return jwt.encode(
        {
            "sub": user["id"],
            "email": user["email"],
            "firstName": user["first_name"],
            "lastName": user["last_name"],
            "iss": project_id,
            "aud": "userjot",
            "iat": now,
            "exp": now + 3600,
        },
        secret,
        algorithm="HS256",
    )

PHP

PHP
<?php

use Firebase\JWT\JWT;

function createUserJotToken(array $user, string $secret, string $projectId): string
{
    $now = time();

    return JWT::encode([
        'sub' => $user['id'],
        'email' => $user['email'],
        'firstName' => $user['firstName'],
        'lastName' => $user['lastName'],
        'iss' => $projectId,
        'aud' => 'userjot',
        'iat' => $now,
        'exp' => $now + 3600,
    ], $secret, 'HS256');
}

Ruby

Ruby
require 'jwt'

def create_userjot_token(user, secret, project_id)
  now = Time.now.to_i

  payload = {
    sub: user[:id],
    email: user[:email],
    firstName: user[:first_name],
    lastName: user[:last_name],
    iss: project_id,
    aud: 'userjot',
    iat: now,
    exp: now + 3600
  }

  JWT.encode(payload, secret, 'HS256')
end

Genera un nuovo token a ogni caricamento della pagina o da un endpoint backend autenticato. Poiché i token scadono dopo al massimo 1 ora, non memorizzarli nella cache più a lungo.

2. Passa il token per identificare l'utente

Passa il JWT nel campo token:

JavaScript
uj.identify({
  token: 'TOKEN_FROM_YOUR_SERVER'
});

Puoi anche passare user e companies insieme a token per aggiungere campi non verificati; se un campo è presente in entrambi, prevale il token firmato (a meno che non sia attivato Richiedi token firmati, che ignora le aziende senza firma). Verifica l’esito tramite la promise restituita:

JavaScript
const result = await uj.identify({ token });
result.identityTrust; // 'signed'

I token non validi causano un errore, senza ricorrere a un'alternativa

Se un token è scaduto, malformato o firmato con il segreto sbagliato, uj.identify viene rifiutata con IDENTIFY_FAILED invece di ricorrere silenziosamente a una sessione non firmata.

Identità firmata e conversazioni

  • Se un visitatore anonimo avvia una conversazione ospite e in seguito si identifica con un token firmato, la conversazione ospite viene trasferita al suo account membro verificato.

  • Le conversazioni avviate con un'identità firmata restano protette. Se vengono riaperte senza una sessione firmata, al visitatore viene chiesto di verificarsi prima di visualizzare la cronologia.

  • L'attivazione di Richiedi token firmati consente comunque ai visitatori anonimi di avviare conversazioni ospite associate al browser; impedisce solo alle chiamate identify non firmate di associarsi agli account membro.

L'identità viene mantenuta nelle tue pagine pubbliche

Una volta identificato, il widget passa automaticamente la sessione ai link che rimandano alle tue pagine UserJot pubbliche (bacheca, roadmap, changelog o centro assistenza). Per far sì che i visitatori arrivino già connessi a quelle pagine, attiva Accesso automatico in Impostazioni → Accesso (piano Starter o Professional). Consulta Accesso automatico.

Risoluzione dei problemi

La chiamata identify viene rifiutata con IDENTIFY_FAILED

  • Verifica che il token sia firmato con HS256 e con il tuo Segreto progetto attuale.

  • Verifica che iss corrisponda al tuo ID progetto e che aud sia esattamente userjot.

  • Verifica che siano presenti sia iat sia exp, espressi in secondi Unix, e che exp - iat <= 3600.

  • Verifica che l'orologio del server sia preciso (i token emessi nel futuro vengono rifiutati se lo scarto dell'orologio supera i 60 secondi).

L'identificazione non firmata ha smesso di funzionare

Richiedi token firmati è attivato in Impostazioni → Accesso (l'opzione viene mostrata quando è attivato Accesso automatico). Una volta attivata, ogni chiamata identify deve includere un token firmato valido.

Ha risposto alla tua domanda?