Autenticación JWT

Identifique a los usuarios en su widget de ayuda sin necesidad de un inicio de sesión independiente. Cuando los usuarios hayan iniciado sesión en su aplicación, puede pasar su identidad a Ferndesk mediante un token JWT firmado por su backend.

Cómo funciona

Flujo de tres pasos:

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

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

3. Su 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 tokens JWT, necesita un secreto de firma de su panel de Ferndesk:

1. Vaya a Help Center > Customize > Access Control

2. Desplácese hasta la sección JWT Authentication

3. Haga clic en Generate Secret

El secreto se muestra solo una vez al generarlo. Cópielo de inmediato y guárdelo de forma segura en las variables de entorno de su backend. No podrá volver a verlo.

Si pierde su secreto, deberá eliminarlo y generar uno nuevo. Esto invalidará todos los tokens JWT existentes firmados con el secreto anterior hasta que actualice su backend para usar el nuevo.

Generar el JWT en el lado del servidor

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

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

• email (string, requerido): Dirección de 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 su frontend

Obtenga el token de su backend y páselo 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

Compruebe estos indicadores:

• Consola del navegador: Sin errores. Los JWT no vá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 su panel de control

Errores comunes

Ferndesk: identify requires a jwt

Falta el parámetro jwt. Compruebe que su backend está devolviendo una cadena JWT.

invalid jwt

Error en la verificación de la firma. Verifique:

• El secreto JWT correcto coincide con el almacenado en Ferndesk

• El token no ha expirado

• El algoritmo es 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 su centro de ayuda pero con un ID de asunto diferente. Esto significa que alguien inició sesión previamente con ese correo electrónico utilizando un sistema de identidad o un valor sub diferente.

Para resolverlo:

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

• Si ha 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. Su aplicación y su centro de ayuda deben compartir un dominio raíz.

Notas de seguridad

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

• Genere tokens solo para usuarios autenticados

• Use HTTPS en todas partes

• Nunca suba los secretos al control de versiones

• Mantenga estables sus valores sub: Ferndesk conserva la identidad por el asunto