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 a un usuario que ha iniciado sesión
Su backend genera un JWT firmado con los detalles del usuario
Su frontend llama a Ferndesk('identify', { jwt })

El centro de ayuda y el widget ahora conocen la identidad del usuario para fines de autenticación, personalización y análisis.

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 lado del 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 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 únicamente en variables de entorno en el lado del 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(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]);

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

Verificar que funciona

Revise estos indicadores:

Consola del navegador: Sin errores. Los JWT no válidos muestran Ferndesk: identify failed - invalid jwt
Formulario de contacto: El correo electrónico y el nombre se rellenarán automáticamente
Análisis: Las sesiones de usuario aparecen en su panel de control

Errores comunes

Ferndesk: identify requires a jwt

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

invalid jwt

La verificación de la firma falló. 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 dominio. Su aplicación y el centro de ayuda deben compartir un dominio raíz.

Notas de seguridad

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

¿Te fue útil?