Autenticación JWT

Identifica a los usuarios en tu widget de ayuda sin necesidad de un inicio de sesión por separado. Cuando los usuarios han iniciado sesión en tu aplicación, puedes pasar su identidad a Ferndesk utilizando un token JWT firmado por tu backend.

Cómo funciona

Flujo de tres pasos:

1. Tu frontend detecta a un usuario con sesión iniciada

2. Tu backend genera un JWT firmado con los detalles del usuario

3. Tu frontend llama a Ferndesk('identify', { jwt })

El centro de ayuda y el widget ahora saben quién es el usuario para fines de autenticación, personalización y analíticas.

Secreto JWT

Antes de poder firmar JWTs, necesitas un secreto de firma desde tu panel de Ferndesk:

1. Ve a Centro de Ayuda, luego, en Administrar, haz clic en Control de acceso.

2. Despliega la fila Identificación JWT

3. Haz clic en Generar secreto

El secreto se muestra solo una vez cuando lo generas. Cópialo de inmediato y almacénalo de forma segura en las variables de entorno de tu backend. No podrás volver a verlo.

Si pierdes tu secreto, tendrás que eliminarlo y generar uno nuevo. Esto invalidará todos los tokens JWT existentes firmados con el secreto anterior hasta que actualices tu backend para usar el nuevo.

Generar el JWT en el servidor

Crea un endpoint que devuelva un token firmado. Claims requeridos:

• sub (string, requerido): ID único en tu sistema que identifica a este usuario. Esta es la clave de identidad principal.

• email (string, requerido): Correo electrónico del usuario

• name (string, opcional): Nombre a mostrar

• customAttributes (object, opcional): Metadatos adicionales

• exp (number, recomendado): Marca de tiempo de expiración del token

Ejemplo de Node.js:

const jwt = require('jsonwebtoken');

app.get('/api/ferndesk-token', async (req, res) => {if (!req.user) return res.status(401).json({ error: 'Not authenticated' });

  const token = jwt.sign({
    sub: req.user.id,
    email: req.user.email,
    name: req.user.name,
    exp: Math.floor(Date.now() / 1000) + 3600 // 1 hour
  }, process.env.FERNDESK_JWT_SECRET, { algorithm: 'HS256' });

  res.send(token);
});

Ejemplo de Python:

import jwt
import time

@app.route('/api/ferndesk-token')
def ferndesk_token():
    if not current_user:
        return {'error': 'Not authenticated'}, 401

    token = jwt.encode({
        'sub': current_user.id,
        'email': current_user.email,
        'name': current_user.name,
        'exp': int(time.time()) + 3600
    }, os.environ['FERNDESK_JWT_SECRET'], algorithm='HS256')

    return token

Llamar a Identify desde tu Frontend

Obtén el token de tu backend y pásalo al SDK:

Ferndesk('init', { widgetId: 'your-widget-id' });

fetch('/api/ferndesk-token').then(r => r.text())
  .then(jwt => Ferndesk('identify', { jwt }))
  .catch(err => console.error('Identification failed:', err));

Ejemplo de React:

useEffect(() => {
  window.Ferndesk('init', { widgetId: 'your-widget-id' });

  if (currentUser) {
    fetch('/api/ferndesk-token')
      .then(r => r.text())
      .then(jwt => window.Ferndesk('identify', { jwt }));
  }
}, [currentUser]);

Verificar que funciona

Revisa estos indicadores:

• Consola del navegador: Sin errores. Los JWT inválidos muestran Ferndesk: identify failed - invalid jwt

• Formulario de contacto: El correo electrónico y el nombre se rellenarán automáticamente

• Analíticas: Las sesiones de usuario aparecen en tu panel de control

Errores comunes

Ferndesk: identify requires a jwt

Falta el parámetro jwt. Comprueba que tu backend esté devolviendo una cadena JWT.

invalid jwt

La verificación de la firma falló. Verifica:

• Que el secreto JWT correcto coincida con el almacenado en Ferndesk

• Que el token no haya expirado

• Que el algoritmo sea HS256

JWT subject does not match the existing help-center user

Este error ocurre cuando el correo electrónico de un usuario ya existe en tu centro de ayuda pero con un ID de asunto diferente. Esto significa que alguien inició sesión anteriormente con ese correo utilizando un sistema de identidad o un valor de sub diferente.

Para resolverlo:

• Asegúrate de que tu backend envíe siempre el mismo sub para cada usuario

• Si has cambiado los sistemas de ID de usuario, el usuario afectado deberá ser reaprovisionado en Ferndesk

must be called from same domain or 1-level subdomain

Discrepancia de dominio. Tu aplicación y tu centro de ayuda deben compartir un dominio raíz.

Notas de seguridad

• Establece la expiración del token (1 hora es lo habitual)

• Solo genera tokens para usuarios autenticados

• Usa HTTPS en todas partes

• Nunca subas secretos al control de versiones

• Mantén estables tus valores de sub: Ferndesk conserva la identidad por asunto