El token de redirección se envió dos veces, a menudo porque la página se vuelve a cargar. Firma un token nuevo para cada redirección.
Inicia sesión de lectores con JWT u OIDC
Los lectores pueden iniciar sesión en tu centro de ayuda con una cuenta que ya tengan. Así, podrán acceder a un centro de ayuda privado, y las reglas de grupo determinarán lo que pueden ver. Hay dos formas de hacerlo: con un JWT de tu propia aplicación o con OIDC de un proveedor de identidad como Okta, Auth0 o Azure AD. Descubre cómo puede ayudar a tu equipo en Cómo hacer que tu centro de ayuda sea privado.
Los propietarios y administradores configuran ambos métodos en Centro de ayuda > Control de acceso. El inicio de sesión con JWT está disponible en todos los planes. OIDC, los centros de ayuda privados y las reglas de grupo dependen del plan. Consulta Precios y planes.
JWT: inicia sesión con tu producto
El lector selecciona Continuar con tu producto en la página de inicio de sesión del centro de ayuda. Si JWT es el único método de inicio de sesión, el centro de ayuda omite esa página y continúa directamente.
El centro de ayuda los dirige a tu URL de inicio de sesión con un parámetro
return_to. Se conserva cualquier cadena de consulta que ya tenga la URL de inicio de sesión.Tu aplicación inicia la sesión del lector si es necesario, firma un JWT con el secreto de firma del centro de ayuda y lo redirige a
return_tocon el token en el fragmento:#jwt=TOKEN.El centro de ayuda verifica el token, inicia una sesión que dura 180 días y devuelve al lector a la página que quería visitar.
import { SignJWT } from 'jose';
const secret = new TextEncoder().encode(process.env.FERNDESK_SIGNING_SECRET);
// Your login URL: the reader is signed in to your app here
app.get('/help-center/sso', requireLogin, async (req, res) => {
const now = Math.floor(Date.now() / 1000);
const token = await new SignJWT({
email: req.user.email,
name: req.user.name,
metadata: { plan: req.user.plan, roles: req.user.roles }
})
.setProtectedHeader({ alg: 'HS256' })
.setSubject(String(req.user.id))
.setIssuedAt(now)
.setExpirationTime(now + 300)
.sign(secret);
res.redirect(req.query.return_to + '#jwt=' + token);
});La URL de retorno también acepta el token como campo de un POST de formulario o como parámetro de consulta ?jwt=, y token también funciona como nombre del campo. El fragmento evita que el token aparezca en los registros del servidor, así que es la opción recomendada.
Afirmaciones
Afirmación | Obligatorio | Descripción |
|---|---|---|
| Sí | El ID de usuario permanente. Identifica al lector en cada inicio de sesión. |
| Sí | El correo electrónico del lector. |
| Sí | Cuándo se firmó el token. |
| Sí | Cuándo caduca. |
| No | El nombre que se muestra del lector. |
| No | Una URL de imagen HTTPS que se usa como avatar del lector. |
| No | Atributos para las reglas de grupo; consulta más abajo. También funciona |
Reglas del token
Firma con HS256. También se aceptan HS384 y HS512.
Un token se acepta durante un máximo de 15 minutos desde su
iat, independientemente de lo que indiqueexpy sin margen para diferencias entre relojes.Un token devuelto mediante la redirección funciona una sola vez. No se comprueban
issniaud.Si llega un nuevo
subcon una dirección de correo que ya pertenece a otro lector, el inicio de sesión falla. Si unsubconocido llega con una nueva dirección de correo, se actualiza el correo del lector, a menos que esa dirección ya pertenezca a otro lector.
El secreto de firma
Ferndesk genera el secreto: selecciona Generar secreto en Inicio de sesión único. Los propietarios y administradores pueden mostrarlo y volver a generarlo allí o en Configuración > Espacio de trabajo > Desarrolladores, en Inicio de sesión de clientes; se trata del mismo secreto. Si lo vuelves a generar, el inicio de sesión se interrumpirá hasta que tu aplicación use el nuevo secreto. Probar inicio de sesión ejecuta el flujo completo cuando ya se hayan configurado un secreto y una URL de inicio de sesión.
Iniciar sesión sin una redirección
Para iniciar la sesión de un lector desde tu producto, envía POST /api/auth/identify al dominio de tu centro de ayuda con el cuerpo JSON {"jwt": "TOKEN"}. El SDK del widget lo hace por el widget. En Más opciones, una URL de cierre de sesión dirige allí a los lectores que iniciaron sesión a través de tu aplicación cuando cierran sesión, y añade return_to.
Atributos y reglas de grupo
Los atributos de metadata se guardan en el lector y se reemplazan en cada inicio de sesión. Las reglas de grupo se basan en ellos, y deben cumplirse todas las condiciones de una regla.
Los valores pueden ser cadenas (de hasta 256 caracteres), números, valores booleanos o listas de uno de esos tipos (de hasta 64 elementos).
Los objetos anidados se aplanan en rutas con puntos, hasta 4 niveles:
{"features": {"sso": true}}se convierte enfeatures.sso.Se permiten hasta 32 atributos después de aplanarlos. Se rechaza cualquier JWT que contenga un atributo no válido.
Operador | Coincide cuando |
|---|---|
es, es uno de | El atributo es igual al valor o a uno de los valores. Si es una lista, puede coincidir cualquiera de sus elementos. |
contiene | Una lista contiene el valor como elemento, o una cadena lo contiene. |
no es, no es ninguno de, excluye | Es lo contrario del operador de coincidencia, cuando el atributo está definido. |
está definido, no está definido | El atributo está presente o falta. |
Un atributo que falta solo coincide con no está definido. Los valores de las reglas se interpretan como texto: true y false coinciden con valores booleanos, y un número coincide con un atributo numérico.
OIDC
En Inicio de sesión de visitantes, abre Inicio de sesión único (OIDC) e introduce la URL de descubrimiento, el ID de cliente y el secreto de cliente de tu proveedor. En tu proveedor, permite este URI de redirección:
https://<your help center domain><base path>/api/auth/oidc/callbackFerndesk usa el flujo de código de autorización con PKCE, solicita
openid,profileyemail, y envía el secreto de cliente en el cuerpo de la solicitud del token.La URL de descubrimiento debe ser pública e incluir
issuer,authorization_endpoint,token_endpointyjwks_uri. El emisor del token de ID debe coincidir con ella, y la audiencia debe ser el ID de cliente.El token de ID debe incluir
subyemail. El nombre se obtiene denamey, si no está, depreferred_username.Un lector existente solo se identifica por su correo electrónico si el proveedor establece
email_verified.Cualquier otra afirmación, como
groups, se convierte en un atributo del lector para las reglas de grupo. No se guardan las afirmaciones relacionadas con el propio inicio de sesión, comoauth_time,jtiyemail_verified.Un lector puede tener hasta 32 atributos. Primero se añaden tus propias afirmaciones; las afirmaciones de perfil estándar, como
given_nameylocale, ocupan los espacios restantes. Se descartan las afirmaciones no válidas.Al cerrar sesión, solo se termina la sesión del centro de ayuda, no la del proveedor.
Solución de problemas
Cuando falla un inicio de sesión con redirección, los lectores ven No se pudo iniciar sesión, sea cual sea la causa. Para ver el motivo, envía el mismo token a POST /api/auth/identify: su campo error contiene uno de los mensajes siguientes.
"Este enlace de inicio de sesión ya se usó"
"Token no válido o caducado"
La firma no coincide con el secreto de firma, el token ha caducado o se firmó hace más de 15 minutos. Fírmalo con el secreto actual justo antes de la redirección y mantén sincronizado el reloj del servidor.
"JWT caducado o falta la afirmación exp"
El token no incluye la afirmación exp. Añádela.
"El asunto del JWT no coincide con el usuario existente del centro de ayuda"
Otro lector con un sub distinto ya tiene esta dirección de correo. Mantén el valor de sub estable para cada persona.
"Los metadatos del JWT son demasiado grandes o no son válidos"
Un atributo supera los límites indicados arriba; por ejemplo, un valor nulo o una lista que mezcla distintos tipos.
OIDC muestra «No se completó el inicio de sesión único»
Comprueba el ID y el secreto de cliente, que el proveedor permita el URI de redirección y el método client_secret_post, y que el token de ID incluya sub y email.