Identidade assinada

Shayan TaslimAtualizado

Uma chamada uj.identify simples é feita a partir do browser, pelo que qualquer pessoa a pode editar. A identidade assinada impede a falsificação: o seu servidor assina um JWT HS256 de curta duração que comprova quem é o utilizador, e o widget passa esse token ao UserJot.

Tudo o que estiver dentro do token (ID do utilizador, e-mail, nome, avatar, atributos e empresas) é considerado verificado.

Quando precisa disto

  • Quer verificar se o feedback, os votos e as conversas vêm da conta autenticada legítima.

  • Pretende que os clientes possam editar e eliminar as suas próprias publicações de feedback e comentários no widget (as sessões sem assinatura uj.identify não podem editar nem eliminar conteúdo no widget).

  • Ativou Exigir tokens assinados em Definições → Início de sessão (disponível nos planos Starter e Professional depois de ativar o Início de sessão automático), o que rejeita chamadas de identificação sem assinatura e também exige que as associações a empresas sejam incluídas no token assinado (ignorando empresas não assinadas do lado do cliente companies com um aviso UNSIGNED_COMPANY_IGNORED).

  • Um administrador ou proprietário do espaço de trabalho está a utilizar o widget. A identificação não assinada nunca é aceite para contas com privilégios. Um token assinado aplica os atributos e as empresas dessa pessoa; o nome, o avatar e o e-mail continuam a ser geridos no dashboard e geram um aviso PRIVILEGED_PROFILE_IGNORED se forem enviados.

Note

Se o seu produto utilizar tanto o widget Web como o Swift SDK, ativar Exigir tokens assinados impõe a verificação em ambos. O widget Web utiliza um JWT HS256 (token), enquanto o Swift SDK utiliza um signature HMAC-SHA256 assinado com o mesmo segredo do espaço de trabalho.

1. Crie o token no seu servidor

Assine um JWT com HS256 usando o segredo do seu espaço de trabalho. Encontre o ID do projeto e o Segredo do projeto em Definições → Início de sessão, na secção Segredos.

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

Declarações obrigatórias

Claim

Valor

sub

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

iss

O ID do seu projeto UserJot. Obrigatório.

aud

A cadeia de caracteres exata userjot. Obrigatório.

iat

Carimbo de data/hora de emissão, em segundos Unix. Obrigatório.

exp

Carimbo de data/hora de expiração, em segundos Unix. Obrigatório. No máximo, 1 hora (3600 segundos) após iat.

Declarações verificadas opcionais

Também pode incluir email, firstName, lastName, avatar, traits e companies. Cada entrada em companies suporta:

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

Emita um token novo a cada carregamento de página ou a partir de um endpoint de backend autenticado. Como os tokens expiram ao fim de, no máximo, 1 hora, não os mantenha em cache durante mais tempo.

2. Passe o token para a chamada identify

Passe o JWT no campo token:

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

Também pode transmitir user e companies juntamente com token para incluir campos adicionais não verificados; se um campo surgir em ambos, prevalece o token assinado (a menos que Exigir tokens assinados esteja ativado, caso em que as empresas não assinadas são ignoradas). Confirme a verificação através da promessa devolvida:

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

Os tokens inválidos são rejeitados, sem recurso a alternativas

Se um token estiver expirado, malformado ou assinado com o segredo errado, uj.identify é rejeitado 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 de convidado e, mais tarde, se identificar com um token assinado, a conversa de convidado é transferida para a conta de membro verificada.

  • As conversas iniciadas com uma identidade assinada permanecem protegidas. Se forem reabertas sem uma sessão assinada, é pedido ao visitante que verifique a identidade antes de consultar o histórico.

  • Ativar Exigir tokens assinados continua a permitir que visitantes anónimos iniciem conversas de convidado associadas ao browser; apenas impede que chamadas identify não assinadas sejam associadas a contas de membro.

A identidade mantém-se nas suas páginas públicas

Depois de identificado, o widget passa automaticamente a sessão para as ligações que apontam para as suas páginas públicas do UserJot (quadro, roteiro, registo de alterações ou centro de ajuda). Para que os visitantes cheguem a essas páginas já com sessão iniciada, ative o Início de sessão automático em Definições → Início de sessão (plano Starter ou Professional). Consulte Início de sessão automático.

Resolução de problemas

A chamada identify é rejeitada com IDENTIFY_FAILED

  • Verifique se o token está assinado com HS256 e com o seu 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, expressos em segundos Unix, e se exp - iat <= 3600.

  • Verifique se o relógio do servidor está certo (os tokens emitidos no futuro são rejeitados se a diferença em relação ao relógio exceder 60 segundos).

A chamada identify sem assinatura deixou de funcionar

A opção Exigir tokens assinados está ativada em Definições → Início de sessão (apresentada quando o Início de sessão automático está ativado). Depois de ativada, todas as chamadas identify têm de incluir um token assinado válido.

Isto respondeu à sua pergunta?