Identidad firmada

Shayan TaslimActualizado

Una llamada sencilla a uj.identify proviene del navegador, así que cualquiera puede modificarla. La identidad firmada evita la suplantación: tu servidor firma un JWT HS256 de corta duración que demuestra quién es el usuario, y el widget envía ese token a UserJot.

Todo lo que contiene el token (ID de usuario, correo electrónico, nombre, avatar, atributos y empresas) se considera verificado.

Cuándo lo necesitas

  • Quieres verificar que los comentarios, votos y conversaciones provengan de la cuenta que realmente inició sesión.

  • Quieres que los clientes puedan editar y eliminar sus propias publicaciones de comentarios y opiniones dentro del widget (las sesiones uj.identify sin firmar no pueden editar ni eliminar contenido en el widget).

  • Activaste Exigir tokens firmados en Configuración → Inicio de sesión (disponible en los planes Starter y Professional una vez que se habilita Inicio de sesión automático), lo que rechaza las llamadas identify sin firmar y también exige que las membresías de empresa se incluyan en el token firmado (se ignoran los companies del lado del cliente sin firmar y se muestra una advertencia UNSIGNED_COMPANY_IGNORED).

  • Un administrador o propietario del espacio de trabajo está usando el widget. La identificación sin firmar nunca se acepta para cuentas con privilegios. Un token firmado aplica sus atributos y empresas; su nombre, avatar y correo electrónico se siguen administrando en el panel y, si se envían, se devuelve una advertencia PRIVILEGED_PROFILE_IGNORED.

Note

Si tu producto usa tanto el widget web como el SDK de Swift, al activar Exigir tokens firmados se exige la verificación en ambos. El widget web usa un JWT HS256 (token), mientras que el SDK de Swift usa un signature HMAC-SHA256 firmado con el mismo secreto del espacio de trabajo.

1. Crea el token en tu servidor

Firma un JWT con HS256 usando el secreto de tu espacio de trabajo. Encontrarás tanto el ID del proyecto como el Secreto del proyecto en Configuración → Inicio de sesión, dentro de Secretos.

Nunca firmes tokens en el navegador. Mantén el secreto en tu servidor.

Claims obligatorios

Reclamación

Valor

sub

El ID estable del usuario en tu sistema. Obligatorio.

iss

El ID de proyecto de UserJot. Obligatorio.

aud

La cadena exacta userjot. Obligatorio.

iat

Marca de tiempo de emisión en segundos Unix. Obligatoria.

exp

Marca de tiempo de expiración en segundos Unix. Obligatoria. Como máximo 1 hora (3600 segundos) después de iat.

Claims verificados opcionales

También puedes incluir email, firstName, lastName, avatar, traits y companies. Cada entrada de companies admite:

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

Ejemplos para servidores

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 token nuevo en cada carga de página o desde un endpoint de backend autenticado. Como los tokens vencen después de un máximo de 1 hora, no los almacenes en caché por más tiempo.

2. Pasa el token para identificar al usuario

Pasa el JWT en el campo token:

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

También puedes pasar user y companies junto con token para incluir campos adicionales sin verificar; si un campo aparece en ambos, prevalece el token firmado (a menos que esté habilitada la opción Exigir tokens firmados, que ignora las empresas sin firmar). Confirma la verificación mediante la promesa devuelta:

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

Los tokens no válidos producen un error en lugar de recurrir a otra opción

Si un token ha vencido, está mal formado o está firmado con el secreto incorrecto, uj.identify lo rechaza con IDENTIFY_FAILED en lugar de recurrir silenciosamente a una sesión sin firmar.

Identidad firmada y conversaciones

  • Si un visitante anónimo inicia una conversación de invitado y luego se identifica con un token firmado, su conversación de invitado se transfiere a su cuenta de miembro verificada.

  • Las conversaciones iniciadas con una identidad firmada siguen protegidas. Si se vuelven a abrir sin una sesión firmada, se pedirá al visitante que se verifique antes de consultar el historial.

  • Activar Exigir tokens firmados sigue permitiendo que los visitantes anónimos inicien conversaciones de invitado asociadas al navegador; solo impide que las llamadas identify sin firmar se vinculen a cuentas de miembros.

La identidad se mantiene en tus páginas públicas

Una vez identificado, el widget pasa automáticamente la sesión a los enlaces que dirigen a tus páginas públicas de UserJot (tablero, hoja de ruta, registro de cambios o centro de ayuda). Para que los visitantes lleguen ya con la sesión iniciada en esas páginas, activa Inicio de sesión automático en Configuración → Inicio de sesión (plan Starter o Professional). Consulta Inicio de sesión automático.

Solución de problemas

La llamada identify se rechaza con IDENTIFY_FAILED

  • Verifica que el token esté firmado con HS256 y con tu Secreto del proyecto actual.

  • Verifica que iss coincida con tu ID del proyecto y que aud sea exactamente userjot.

  • Verifica que tanto iat como exp estén presentes en segundos Unix y que exp - iat <= 3600.

  • Verifica que el reloj de tu servidor sea preciso (se rechazan los tokens emitidos en el futuro si la diferencia supera los 60 segundos de desviación del reloj).

La identificación sin firmar dejó de funcionar

Exigir tokens firmados está activado en Configuración → Inicio de sesión (se muestra cuando está activado Inicio de sesión automático). Una vez activado, todas las llamadas identify deben incluir un token firmado válido.

¿Respondió esto a tu pregunta?