Autenticación JWT

Identifica a los usuarios en tu widget de ayuda sin necesidad de un inicio de sesión aparte. Cuando los usuarios hayan iniciado sesión en tu app, puedes transmitir su identidad a Ferndesk mediante un token JWT firmado por tu backend.

Cómo funciona

Flujo de tres pasos:

1. Tu frontend detecta a un usuario que ha iniciado sesión

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

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

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

Secreto JWT

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

1. Ve a Help Center > Access Control.

2. En la sección User identification, despliega la fila JWT identify.

3. Haz clic en Generate Secret.

Generar un secreto habilita automáticamente la autenticación JWT para tu centro de ayuda. El secreto se muestra solo una vez. Cópialo de inmediato y guárdalo de forma segura en las variables de entorno de tu backend. No podrás volver a verlo.

Si necesitas rotar el secreto, haz clic en Regenerate. Esto reemplaza el secreto existente e invalida todos los tokens firmados con el anterior. Actualiza tu backend con el nuevo secreto antes de que los usuarios se vean afectados.

Inicio de sesión en el navegador para clientes MCP e IA

JWT identify funciona de forma silenciosa en tu producto. Los clientes de IA inician sesión a los usuarios a través de un navegador.

En JWT identify dentro de Browser sign-in (MCP and AI clients):

1. Introduce la URL de tu SSO login page URL. Ferndesk redirige a los usuarios aquí con un parámetro return_to. Después de iniciar sesión, redirige a return_to con un parámetro de consulta jwt.

2. Opcionalmente, activa Allow email sign-in for AI clients para que los usuarios existentes puedan demostrar la propiedad del correo electrónico al conectar un cliente de IA. Déjalo desactivado si los atributos de usuario controlan contenido sensible.

3. Haz clic en Save changes.

Usa una URL válida http: o https:. Los valores inválidos muestran Introduce una URL de página de inicio de sesión válida, incluido https://.

Relacionado: Usa Ferndesk con herramientas de IA · Permite que los lectores usen tu centro de ayuda en herramientas de IA

Genera el JWT del lado del servidor

Crea un endpoint que devuelva un token firmado. Ferndesk no requiere claims iss (issuer) ni aud (audience).

Claims obligatorios:

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

• email (string, required): Dirección de correo electrónico del usuario

• exp (number, required): Marca de tiempo de caducidad del token

• iat (number, required): Marca de tiempo de emisión del token

Claims opcionales:

• name (string, optional): Nombre para mostrar

• customAttributes (object, optional): Atributos adicionales del usuario. También puedes usar metadata; se aceptan ambas claves.

Ejemplo en 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 now = Math.floor(Date.now() / 1000);
  const token = jwt.sign({
    sub: req.user.id,
    email: req.user.email,
    name: req.user.name,
    iat: now,
    exp: now + 3600, // 1 hour
    customAttributes: { plan: req.user.plan }
  }, process.env.FERNDESK_JWT_SECRET, { algorithm: 'HS256' });

  res.send(token);
});

Ejemplo en Python:

import jwt
import time

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

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

    return token

Llama 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 en 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]);

Verifica que funcione

Comprueba estos indicadores:

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

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

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

Errores comunes

Ferndesk: identify requires a jwt

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

invalid jwt

Falló la verificación de la firma o la validación de claims. Verifica:

• El secreto JWT correcto coincide con lo almacenado en Ferndesk

• El token no ha caducado

• El algoritmo es HS256

• Están presentes los claims obligatorios: sub, email, exp e iat

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 subject diferente. Esto significa que alguien inició sesión previamente con ese correo usando otro sistema de identidad o valor sub.

Para resolverlo:

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

• Si has cambiado los sistemas de ID de usuario, será necesario volver a aprovisionar al usuario afectado en Ferndesk

must be called from same domain or 1-level subdomain

Discordancia de dominio. Tu app y tu centro de ayuda deben compartir un dominio raíz.

Notas de seguridad

• Establece la caducidad del token (1 hora es lo habitual)

• Genera tokens solo para usuarios autenticados

• Usa HTTPS en todas partes

• Nunca confirmes secretos en el control de versiones

• Mantén estables tus valores sub. Ferndesk conserva la identidad por subject.