Autenticación JWT

Identifique a los usuarios en su widget de ayuda sin necesidad de un inicio de sesión independiente. Cuando los usuarios inicien sesión en su aplicación, puede pasar su identidad a Ferndesk mediante 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 conectado
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 conocen la identidad del 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 realizar la identificación desde app.example.com pero no desde otrominio.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 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

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 aparecerán pre-rellenados
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 (invalid token)

Fallo en 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 el centro de ayuda deben compartir un dominio raíz.

Notas de seguridad

Establezca una expiración del token (1 hora es lo habitual)
Solo genere tokens para usuarios autenticados
Use HTTPS en todas partes
Nunca envíe secretos al control de versiones

¿Te fue útil?