Autenticación JWT

Identifique a los usuarios en su widget de ayuda sin requerir un inicio de sesión por separado. Cuando los usuarios inicien 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 Help Center > Customize > Access Control y tener instalado el SDK de Ferndesk.

Cómo funciona

Flujo de tres pasos:

Su frontend detecta a 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ítica.

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 realizar la identificación desde app.example.com pero no desde otrodominio.com.

Generar el JWT en el servidor

Cree un endpoint que devuelva un token firmado. Atributos (claims) requeridos:

userId (string): ID único en su sistema
email (string): 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 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 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 en 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 únicamente en variables de entorno 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 en 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

Revise 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 aparecerán completados automáticamente
Analítica: Las sesiones de usuario aparecen en su tablero

Errores comunes

identify requires a token

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

invalid token

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

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

must be called from same domain or 1-level subdomain

Discrepancia de dominios. Su aplicación y el centro de ayuda deben compartir un dominio raíz.

Notas de seguridad

Establezca una expiración del token (1 hora es común)
Solo genere tokens para usuarios autenticados
Use HTTPS en todas partes
Nunca incluya secretos en el control de versiones

¿Te fue útil?