Identidade assinada

Shayan TaslimAtualizado

Uma chamada uj.identify simples vem do navegador, então qualquer pessoa pode editá-la. A identidade assinada evita falsificações: seu servidor assina um JWT HS256 de curta duração que comprova quem é o usuário, e o widget passa esse token para o UserJot.

Tudo o que está dentro do token (ID do usuário, e-mail, nome, avatar, atributos e empresas) é considerado verificado.

Quando você precisa disso

  • Você quer confirmar que o feedback, os votos e as conversas vêm da conta autenticada de fato.

  • Você quer que os clientes possam editar e excluir suas próprias publicações de feedback e comentários dentro do widget (sessões não assinadas uj.identify não podem editar nem excluir conteúdo no widget).

  • Você ativou Exigir tokens assinados em Configurações → Login (disponível nos planos Starter e Professional após ativar o Login automático), o que rejeita chamadas de identificação não assinadas e também exige que as associações a empresas sejam incluídas no token assinado (ignorando companies não assinadas no lado do cliente e exibindo um aviso UNSIGNED_COMPANY_IGNORED).

  • Um administrador ou proprietário do workspace está usando o widget. A identificação não assinada nunca é aceita para contas privilegiadas. Um token assinado aplica os atributos e as empresas dessa pessoa; o nome, o avatar e o e-mail continuam sendo gerenciados no painel e, se forem enviados, geram um aviso PRIVILEGED_PROFILE_IGNORED.

Note

Se o seu produto usa o widget da web e o Swift SDK, ativar Exigir tokens assinados impõe a verificação em ambos. O widget da web usa um JWT HS256 (token), enquanto o Swift SDK usa um signature HMAC-SHA256 assinado com o mesmo segredo do workspace.

1. Crie o token no seu servidor

Assine um JWT com HS256 usando o segredo do seu workspace. Encontre o ID do projeto e o Segredo do projeto em Configurações → Login, na seção Segredos.

Nunca assine tokens no navegador. Mantenha o segredo no seu servidor.

Claims obrigatórias

Declaração

Valor

sub

O ID estável do usuário no seu sistema. Obrigatório.

iss

O ID do seu projeto no UserJot. Obrigatório.

aud

A string exata userjot. Obrigatória.

iat

Data e hora de emissão em segundos Unix. Obrigatória.

exp

Data e hora de expiração em segundos Unix. Obrigatória. No máximo 1 hora (3600 segundos) após iat.

Claims verificadas opcionais

Você também pode incluir email, firstName, lastName, avatar, traits e companies. Cada entrada em companies aceita:

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

Exemplos de servidor

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

Gere um token novo a cada carregamento de página ou a partir de um endpoint de backend autenticado. Como os tokens expiram após no máximo 1 hora, não os armazene em cache por mais tempo.

2. Passe o token para identify

Passe o JWT no campo token:

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

Você também pode passar user e companies junto com token para incluir campos adicionais não verificados; se um campo aparecer em ambos, o token assinado prevalece (a menos que Exigir tokens assinados esteja ativado, caso em que empresas não assinadas são ignoradas). Confirme a verificação usando a promessa retornada:

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

Tokens inválidos falham, sem usar uma alternativa

Se um token estiver expirado, malformado ou assinado com o segredo errado, uj.identify rejeitará com IDENTIFY_FAILED, em vez de recorrer silenciosamente a uma sessão não assinada.

Identidade assinada e conversas

  • Se um visitante anônimo iniciar uma conversa como visitante e depois se identificar com um token assinado, a conversa como visitante será transferida para a conta verificada de membro.

  • As conversas iniciadas com uma identidade assinada continuam protegidas. Ao reabri-las sem uma sessão assinada, o visitante precisará verificar a identidade antes de ver o histórico.

  • Ativar Exigir tokens assinados ainda permite que visitantes anônimos iniciem conversas de visitante vinculadas ao navegador; isso apenas impede que chamadas identify não assinadas sejam associadas a contas de membros.

A identidade também é usada nas suas páginas públicas

Após a identificação, o widget passa automaticamente a sessão para links que apontam para suas páginas públicas do UserJot (quadro, roadmap, changelog ou central de ajuda). Para que os visitantes já cheguem autenticados nessas páginas, ative o Login automático em Configurações → Login (plano Starter ou Professional). Consulte Login automático.

Solução de problemas

A chamada identify é rejeitada com IDENTIFY_FAILED

  • Verifique se o token está assinado com HS256 e com o Segredo do projeto atual.

  • Verifique se iss corresponde ao seu ID do projeto e se aud é exatamente userjot.

  • Verifique se iat e exp estão presentes como segundos Unix e se exp - iat <= 3600.

  • Verifique se o relógio do servidor está correto (tokens emitidos no futuro são rejeitados quando a diferença ultrapassa 60 segundos).

As chamadas identify sem assinatura pararam de funcionar

Exigir tokens assinados está ativado em Configurações → Login (exibido quando o Login automático está ativado). Depois de ativar, toda chamada identify precisa incluir um token assinado válido.

Isso respondeu à sua pergunta?