Inicia sesión con tu producto
Inicia sesión con tu producto es un inicio de sesión único basado en redirecciones: los lectores hacen clic en un botón en la página de inicio de sesión de tu centro de ayuda, inician sesión en la propia página de inicio de sesión de tu producto y regresan con un JWT de corta duración que establece su sesión en el centro de ayuda. Está disponible en todos los planes y funciona tanto en centros de ayuda públicos como privados.
Lo que necesitas
Una página de inicio de sesión en tu producto. Introduces su URL en Ferndesk, y debe ser una URL completa
http://ohttps://.Firma de JWT en el servidor con HS256. Tu backend firma el token después de que los lectores inician sesión en tu plataforma.
Un rol de propietario o administrador en tu espacio de trabajo de Ferndesk. Solo los propietarios y administradores activos del espacio de trabajo pueden generar, revelar y rotar el secreto de firma.
Configura Inicia sesión con tu producto
Todo se configura en un solo lugar: el panel, en Centro de ayuda, luego Control de acceso, en la pestaña Acceso.
Abre la configuración del inicio de sesión único
En el panel, ve a Centro de ayuda, luego a Control de acceso y abre la pestaña Acceso. Expande Inicia sesión con tu producto y, después, Inicio de sesión único.
Introduce tu URL de inicio de sesión
La URL de inicio de sesión es la página de inicio de sesión de tu producto a la que se redirige a los lectores. Debe comenzar con http:// o https://.
Asigna un nombre al botón de inicio de sesión
El Nombre del botón se muestra a los lectores como Continuar con <product name>. De forma predeterminada, usa el nombre de tu centro de ayuda.
Copia la URL de devolución de llamada
En la sección se muestra una URL de devolución de llamada de solo lectura. Cópiala: tu producto redirige a los lectores de vuelta a esta URL después de iniciar sesión.
Genera el secreto de firma
En la sección Secreto de firma, genera el secreto que tu backend usa para firmar JWT.
Configura las opciones adicionales
En Más opciones puedes añadir una URL del logotipo del botón y una URL de cierre de sesión. La URL de cierre de sesión es el lugar al que se envía a los lectores cuando cierran sesión en el centro de ayuda mediante el SSO del producto.
Abre la guía de configuración de la sección para consultar ejemplos de código listos para usar en Node.js y Python.
El estado del método refleja lo que está configurado: No configurado hasta que existe un secreto de firma, Solo identificación cuando existe un secreto pero no hay una URL de inicio de sesión válida configurada, y Habilitado cuando el secreto y una URL de inicio de sesión válida están configurados.
Cómo funciona el flujo de inicio de sesión
La redirección pasa por tu producto y el token firmado regresa a Ferndesk en el fragmento de la URL.
Un lector hace clic en el botón de inicio de sesión de tu centro de ayuda. Ferndesk lo envía a tu URL de inicio de sesión con un parámetro de consulta
return_to.Tu producto inicia la sesión del lector, firma un JWT y redirige el navegador de vuelta al valor de
return_tocon el token añadido como#jwt=<token>.Ferndesk valida el token y crea la sesión del lector en el centro de ayuda.
Envía el token en el fragmento de la URL. Los fragmentos no se envían a los registros del servidor ni al encabezado Referer, por lo que el token no aparece en ellos. La devolución de llamada también acepta el token mediante un POST de formulario o como un parámetro de consulta ?jwt=.
Los tokens devueltos mediante la devolución de llamada de redirección solo se pueden usar una vez. Cada token establece una sesión.
Firma el JWT
Firma con HS256. Solicitudes obligatorias:
Solicitud | Valor |
|---|---|
| ID de usuario estable y único de tu sistema |
| Dirección de correo electrónico del lector |
| Marca de tiempo de emisión del token |
| Marca de tiempo de expiración del token. El token puede tener una duración máxima de 15 minutos. |
Solicitudes opcionales:
name: nombre visible del lectorcustomAttributesometadata: atributos del grupo de usuarios
La solicitud sub debe mantenerse estable para cada usuario. Es lo que Ferndesk usa para identificar al lector entre sesiones.
Nunca expongas el secreto de firma en código del lado del cliente. Guárdalo únicamente en variables de entorno del backend.
Ejemplo de Node.js:
const jwt = require('jsonwebtoken');
app.get('/sso/ferndesk', (req, res) => {
if (!req.user) return res.redirect('/login');
const returnTo = req.query.return_to;
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)
}, process.env.FERNDESK_JWT_SECRET, { algorithm: 'HS256' });
res.redirect(returnTo + '#jwt=' + token);
});Prueba el inicio de sesión
Cuando tu página de inicio de sesión firme y redirija el token, haz clic en Probar inicio de sesión en la sección Inicio de sesión único para ejecutar el flujo antes de que los lectores lo utilicen.
Inicia sesión de los lectores silenciosamente (opcional)
Puedes omitir por completo la redirección para los lectores que ya hayan iniciado sesión en tu producto. Envía un JWT firmado con el mismo secreto de firma al endpoint de identificación, /api/auth/identify, o utiliza el flujo de identificación del widget. Consulta Autenticación JWT para obtener información sobre la identificación silenciosa.
Rota el secreto de firma
La rotación está limitada a los propietarios y administradores activos del espacio de trabajo, los mismos roles que pueden generar y revelar el secreto. Rotar el secreto lo reemplaza de inmediato, y los tokens firmados con el secreto anterior dejan de funcionar. Copia el nuevo secreto en las variables de entorno de tu backend en lugar del anterior.
Otras formas en que los lectores pueden iniciar sesión
Inicia sesión con enlaces mágicos: enlaces de inicio de sesión por correo electrónico de un solo uso
Inicia sesión con SSO de OIDC: inicio de sesión mediante un proveedor de identidad externo
Contraseña compartida: una sola contraseña para todo el centro de ayuda