Autenticación JWT

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

Necesitará su secreto JWT de Centro de ayuda > Personalizar > Control de acceso y tener instalado el SDK de Ferndesk.

Cómo funciona

Flujo de tres pasos:

Su frontend detecta un usuario con sesión iniciada
Su backend genera un JWT firmado con los detalles del usuario
Su frontend llama a Ferndesk('identify', { token })

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

El método identify solo funciona desde el mismo dominio que su centro de ayuda o un subdominio de primer nivel. Si su centro de ayuda está en help.example.com, puede identificar desde app.example.com pero no desde otrodominio.com.

Generar el JWT en el servidor

Cree un endpoint que devuelva un token firmado. Notificaciones (claims) requeridas:

userId (string): ID único en su sistema
email (string): Correo electrónico del usuario
name (string, opcional): Nombre para mostrar
customAttributes (objeto, opcional): Metadatos adicionales
exp (número, 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({
    userId: 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({
        'userId': 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

Nunca exponga su secreto JWT en el código del lado del cliente. Almacénelo en variables de entorno únicamente en el servidor.

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(token => Ferndesk('identify', { token }))
  .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(token => window.Ferndesk('identify', { token }));
  }
}, [currentUser]);

Llame a identify después de init pero antes de abrir el widget. Para cerrar la sesión, reinicialice sin llamar a identify.

Verificar que funciona

Compruebe estos indicadores:

Consola del navegador: Sin errores. Los tokens inválidos muestran Ferndesk: identify failed - invalid token
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

identify requiere un token

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

token inválido

Falló la verificación de la firma. Verifique:

Secreto JWT correcto
El token no ha expirado
El algoritmo es HS256

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

Discrepancia de dominios. 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)
Solo genere tokens para usuarios autenticados
Utilice HTTPS en todas partes
Nunca incluya secretos en el control de versiones

¿Te fue util?