Autenticación JWT

Identifica a los usuarios en tu widget de ayuda sin requerir un inicio de sesión independiente. Cuando los usuarios hayan iniciado sesión en tu aplicación, puedes pasar 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 })

El centro de ayuda y el widget ahora saben quién es el usuario para la autenticación, la personalización y el análisis.

Secreto JWT

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

1. Ve a Centro de ayuda > Control de acceso.

2. Abre la pestaña Acceso.

3. En la sección Iniciar sesión con tu producto, en Inicio de sesión único, busca el área Secreto de firma.

4. Haz clic en Generar secreto.

La sección muestra un estado: No configurado significa que aún no existe ningún secreto. Solo identificación significa que el secreto funciona para la identificación silenciosa, pero los lectores todavía no pueden iniciar sesión a través de tu producto porque no se ha configurado ninguna URL de inicio de sesión válida. Habilitado significa que el secreto y una URL de inicio de sesión válida están configurados.

El secreto se oculta después de generarlo. Cópialo inmediatamente y guárdalo de forma segura en las variables de entorno de tu backend. Más adelante podrás volver a mostrarlo desde el panel.

La identificación silenciosa también puede realizarse enviando un JWT firmado con el mismo secreto al endpoint de identificación /api/auth/identify.

Solo los propietarios y administradores activos del espacio de trabajo pueden generar, mostrar, rotar o eliminar el secreto. Los demás miembros del espacio de trabajo verán instrucciones para pedir ayuda a un propietario o administrador en lugar de los controles de administración del secreto.

Si necesitas rotar el secreto, haz clic en Regenerar y confirma la rotación en el cuadro de diálogo ¿Regenerar el secreto de firma JWT?. El secreto existente se sustituye y todos los tokens firmados con el anterior dejan de funcionar inmediatamente. Implementa el nuevo secreto en tu backend antes de que se reanude el inicio de sesión en el centro de ayuda.

Iniciar sesión con tu producto

Los lectores inician sesión mediante la propia página de inicio de sesión del centro de ayuda, utilizando los métodos que este habilite. Uno de esos métodos es iniciar sesión a través de tu producto: el centro de ayuda redirige al lector a tu producto, tu backend firma un JWT de corta duración y el lector vuelve al centro de ayuda con la sesión iniciada. El mismo secreto de firma también permite la identificación silenciosa desde el interior de tu aplicación.

Los clientes de IA que leen tu centro de ayuda mediante MCP inician sesión con los propios métodos de inicio de sesión del centro de ayuda en el navegador.

Los pasos de configuración se encuentran en Iniciar sesión con tu producto.

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

Generar el JWT en el servidor

Crea un endpoint que devuelva un token firmado. Ferndesk no requiere las claims iss (emisor) ni aud (audiencia).

Claims obligatorias:

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

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

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

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

Claims opcionales:

• name (string, opcional): Nombre visible

• customAttributes (object, opcional): 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 + 900, // 15 minutes (maximum token age)
    customAttributes: { plan: req.user.plan }
  }, process.env.FERNDESK_JWT_SECRET, { algorithm: 'HS256' });

  res.send(token);
});

Ejemplo en Python:

import jwt
import os\nimport 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 + 900,  # 15 minutes (maximum token age)
        'customAttributes': {'plan': current_user.plan}
    }, 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 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]);

Verificar que funciona

Comprueba estos indicadores:

• Consola del navegador: No hay errores. Los JWT no válidos muestran Ferndesk: identify failed (Invalid or expired token).

• Formulario de contacto: El correo electrónico y el nombre aparecerán rellenados previamente

• Análisis: Las sesiones de los usuarios aparecen en tu panel

Errores comunes

Ferndesk: identify requires a jwt

Falta el parámetro jwt. Comprueba que tu backend devuelva una cadena JWT.

invalid jwt

La verificación de la firma o la validación de las claims ha fallado. Comprueba lo siguiente:

• El secreto JWT correcto coincide con el almacenado en Ferndesk

• El token no ha caducado

• El algoritmo es HS256, HS384 o HS512 (los ejemplos anteriores usan HS256)

• Están presentes las claims obligatorias: sub, email, exp e iat

El subject del JWT no coincide con el usuario existente del centro de ayuda

Este error se produce 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 anteriormente con ese correo electrónico utilizando otro sistema de identidad o valor sub.

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, será necesario volver a aprovisionar en Ferndesk al usuario afectado

debe llamarse desde el mismo dominio o un subdominio de 1 nivel

El origen no coincide. Las solicitudes posteriores de sesión del widget deben proceder exactamente del origen que realizó la identificación, incluidos el esquema, el host y el puerto.

Notas de seguridad

• Establece la expiración del token en 15 minutos o menos

• Genera tokens únicamente para usuarios autenticados

• Usa HTTPS en todas partes

• Nunca incluyas secretos en el control de versiones

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