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 en tres pasos:

1. Tu frontend detecta que un usuario 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 de tu panel de Ferndesk:

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

2. En la sección Identificación de usuarios, expande la fila Identificación mediante JWT.

3. Haz clic en Generar secreto.

Al generar un secreto, se activa automáticamente la autenticación JWT para tu centro de ayuda. 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.

Si necesitas rotar el secreto, haz clic en Regenerar. 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 MCP y clientes de IA

La identificación mediante JWT funciona silenciosamente en tu producto. En cambio, los clientes de IA inician sesión mediante un navegador.

En Identificación mediante JWT, dentro de Inicio de sesión en el navegador (MCP y clientes de IA):

1. Introduce la URL de la página de inicio de sesión de SSO. Ferndesk redirige a los usuarios aquí con un parámetro return_to. Después de iniciar sesión, redirígelos a return_to con un parámetro de consulta jwt.

2. Opcionalmente, activa Permitir el inicio de sesión por correo electrónico para clientes de IA para que los usuarios existentes puedan demostrar que son propietarios de su dirección de correo electrónico al conectar un cliente de IA. Déjalo desactivado si los atributos de usuario controlan el acceso a contenido confidencial.

3. Haz clic en Guardar cambios.

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

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

Genera el JWT en el servidor

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

Notificaciones obligatorias:

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

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

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

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

Notificaciones opcionales:

• name (cadena, opcional): Nombre visible

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

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 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 de 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

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

Verifica 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 notificaciones ha fallado. Verifica lo siguiente:

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

• Que el token no haya expirado

• Que el algoritmo sea HS256

• Que estén presentes las notificaciones obligatorias: sub, email, exp e iat

el sujeto del JWT no coincide con el usuario existente del centro de ayuda

Este error ocurre cuando el correo electrónico de un usuario ya existe en tu centro de ayuda, pero con un ID de sujeto diferente. Esto significa que alguien inició sesión anteriormente con esa dirección de correo electrónico usando un sistema de identidad o un valor 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, será necesario volver a aprovisionar en Ferndesk al usuario afectado

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

El origen no coincide. Las solicitudes posteriores de sesión del widget deben proceder del origen exacto 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 confirmes secretos en el control de versiones

• Mantén estables tus valores sub. Ferndesk conserva la identidad mediante el sujeto.