JSON web tokens (JWTs) evitan que terceros suplanten a tus users conectados y vean sus conversaciones. Recomendamos encarecidamente que todos los clientes de Fin apliquen la autenticación JWT.
Si tienes Fin Messenger instalado en tu sitio para users conectados, es esencial asegurar su protección y evitar que actores malintencionados suplanten a tus users o envíen datos no autorizados.
En un Messenger que no es seguro, alguien podría interactuar con tu Fin Messenger y falsificar la identidad de otro user, proporcionando un identificador conocido como su correo electrónico o user_id. Esto permite a un atacante hacerse pasar por un user real ante tus compañeros, dando acceso a conversaciones previas y datos potencialmente sensibles.
¿Qué es un JSON web token (JWT)?
Un JWT es un estándar de la industria para firmar datos. Normalmente consta de tres partes, separadas por puntos. Un JWT típico se ve así: header.payload.signature.
El header especifica el tipo de token (JWT) y el algoritmo de firma (por ejemplo, HS256).
El payload contiene afirmaciones sobre el user o la sesión (por ejemplo, user_id, email).
Finalmente, la signature asegura que el token no ha sido alterado, usando una clave secreta o privada.
¿Cuáles son los beneficios de asegurar el Messenger con JSON web tokens (JWTs)?
Identidad segura del user: Asegurar tu messenger permite a tus compañeros estar seguros de que el user con quien hablan es realmente ese user.
Mayor seguridad de los datos del user: Asegurar tu Messenger permite la transmisión segura de atributos de datos sobre tu user a través de la API del Messenger.
Reducción del riesgo por sesiones robadas: Asegurar tu Messenger con JWTs te permite establecer la expiración del token, reduciendo significativamente el riesgo de brechas de datos que podrían ocurrir si los tokens son robados del navegador de tu user. Al especificar una expiración corta, se disminuye el riesgo.
Workflows Fin y AI más seguros: Da a Fin tus procesos complejos, Actions y Workflows, incluso si requieren información confiable del user.
Al transmitir de forma segura la identidad y datos del user y hacer cumplir la expiración del token, los JWTs aseguran que tu Fin Messenger esté en el estado más seguro posible.
Experiencia del cliente
Al usar JWTs con Fin Messenger, la experiencia es la siguiente:
Tu integración del Messenger iniciará a tu user conectado con una solicitud
Intercom('boot')que contiene un JWT, el cual incluye todos los datos del user que desees enviar a tu workspace. La firma del JWT se genera usando la clave secreta del Messenger de tus configuraciones.Luego, tu workspace proporcionará al user una cookie de sesión en su navegador. Esta cookie tiene una duración predeterminada de 7 días. La cookie se usará durante su vida útil para autenticar al user y realizar cualquier actualización de ese user.
Si la sesión expira y no se envía un JWT nuevo, la sesión del user terminará. El user verá un Messenger nuevo como visitante del sitio web desconectado. No contendrá su historial de conversaciones.
Una vez que el Messenger se reinicie con
Intercom('boot')y un JWT válido, el Messenger identificará al user y mostrará sus conversaciones históricas y una nueva sesión. Además, fusionaremos cualquier actividad desconectada ocurrida en el mismo dispositivo en la cuenta autenticada del user.
Consejos:
Si deseas que la duración de la cookie de sesión del user sea menor que los 7 días predeterminados, puedes especificar el TTL de la cookie en milisegundos con el atributo session_duration del Messenger.
Si estás creando tickets Zendesk desde Fin Messenger y quieres que los tickets se dirijan a una organización específica, puedes incluir un campo de empresa en el JWT. El valor
iddebe coincidir con el ID externo de la organización Zendesk (no el ID interno de Zendesk).
Instalación: Generación y envío de JWTs
Paso 1: Instala el Messenger en tu aplicación
Puedes encontrar las instrucciones únicas de configuración para tu workspace en Configuración > Messenger > Seguridad.
La principal diferencia entre una configuración insegura y una segura del Messenger es que incluirás un campo adicional intercomUserJwt en tus solicitudes de user, que se usará para identificar y actualizar al user.
Verás una opción para agregar atributos de datos en tu fragmento Javascript. Esto regula qué datos quieres enviar a tu workspace Fin. Como usarás JWTs para transmitir datos, solo debes incluir aquí atributos que no quieras firmar, por ejemplo, si quieres enviar datos específicos del front-end.
Si no quieres enviar datos fuera del JWT, puedes eliminar todos los datos de tu fragmento excepto api_base y app_id. Tu app_id es el identificador único de tu workspace Fin.
Para visitantes sin identificadores específicos de user (como user_id o email), configura un fragmento Messenger desconectado incluyendo solo el App ID en tu configuración. Evita agregar atributos de user para mantener una configuración ligera y segura para visitantes anónimos.
Paso 2: Comienza a generar JWTs para tus users
Puedes usar librerías estándar JWT para generar el token, usando el Messenger API Secret como clave secreta. Tu clave secreta puede generarse en la configuración de seguridad de tu workspace, en la pestaña messenger.
Nota: Los tokens JWT deben generarse de forma única para cada sesión de user usando cualquier librería estándar JWT. Los tokens deben incluir afirmaciones identificativas como user_id y firmarse con el Messenger API Secret para asegurar que están asociados de forma segura con el user correcto.
Elige tus frameworks de back y front end para obtener ejemplos de código relevantes para tu instalación.
Aquí tienes un ejemplo para Node.js:
Si hay atributos adicionales que quieres enviar sobre tus users (por ejemplo: price_plan o number_of_songs_added) también los agregarías en tu JWT. user_id es el único campo obligatorio. Asegúrate de que los nombres de campo dentro del payload del JWT y los atributos respeten mayúsculas y minúsculas. Por ejemplo, "user_id" debe escribirse con una 'i' minúscula en lugar de "user_Id", ya que la sensibilidad a mayúsculas puede afectar la identificación correcta del user.
Nota: Al usar el JWK generado por Fin para firmar tokens JWT, el reclamo sub por defecto es el User ID asignado por Fin y sirve como identificador único del user. Esto proporciona un mecanismo consistente y seguro para la identificación del user. Al usar el mecanismo JWK, el valor sub es fijo y no puede personalizarse, asegurando compatibilidad y evitando errores de configuración.
Paso 3: Añade JWTs a tu fragmento Messenger
Al lanzar el Messenger para un user conectado, puedes proporcionar un JSON Web Token firmado y asignarlo al atributo intercom_user_jwt del payload del Messenger. Alternativamente, también puedes usar Intercom.setUserJwt(jwt) antes de iniciar sesión para asignar el token JWT para una atribución segura de datos.
Ejemplo de configuración del lado cliente
window.Intercom("boot", {
api_base: "https://api-iam.intercom.io",
app_id: "APP_ID_CODE",
intercom_user_jwt: <YOUR_USER_JWT_TOKEN>,
};
Este JWT puede contener cualquier atributo de datos del user que quieras enviar de forma segura. Una vez que se reciba un JWT válido para el user, se creará una cookie de sesión en el navegador del user con una duración predeterminada de 7 días.
Para controlar el TTL de la cookie de sesión del Messenger, puedes establecer un máximo en el desplegable Mantén tu Messenger seguro en tu Configuración General del Messenger.
Paso 4: Asegúrate de que las actualizaciones estén deshabilitadas para tus atributos
Es posible habilitar actualizaciones inseguras para atributos de datos en la API del Messenger, lo que significa que cualquier actualización a través del Messenger para ese atributo tendrá éxito.
Si envías algunos datos de forma segura en tu JWT, debes asegurarte de deshabilitar las actualizaciones inseguras del Messenger para esos atributos, de modo que solo se actualicen mediante un JWT válido. Nota: este interruptor no impide que recolectes datos directamente de leads con un bot
Recomendamos habilitar este interruptor para cualquier atributo que envíes en tu JWT.
Paso 5: Cierra las sesiones de user al cerrar sesión
Puedes instalar Fin Messenger en cualquier sitio público que poseas (tu sitio de marketing, tu sitio de documentación, tu hub de desarrolladores, etc.). Para mantener la continuidad de las conversaciones en todos estos posibles subdominios mientras tus users están conectados, establecemos una cookie en el navegador de tu user. Esta cookie expira después de una semana.
Cualquier user que use una computadora y navegador compartidos con otra persona podrá ver el historial de conversaciones del user que inició sesión más recientemente hasta que la cookie expire. Por eso, es muy importante cerrar correctamente el Fin Messenger cuando la sesión de un user en tu app termine (ya sea cerrando sesión manual o automáticamente).
Así es como se cierra el Fin Messenger:
Ya habrás comenzado a rastrear a tu user mediante el fragmento Intercom JS o el método “boot”.
Cuando tu user cierre sesión en el Fin Messenger (o sea cerrado automáticamente por tu app), llama a Intercom('shutdown'); desde nuestra API de JavaScript para terminar la sesión y borrar la cookie.
Paso final: Aplicar la seguridad del Messenger para tu workspace
Cuando tu integración envíe correctamente JWTs para tus users, debes aplicar la seguridad del Messenger activándola en la configuración del Messenger. Al hacer esto, el Fin Messenger requerirá que las solicitudes para los users de tu workspace estén aseguradas con un JWT válido o un user_hash válido.
Nota: La autenticación JWT no es compatible actualmente con los SDKs de Fin Messenger para iOS o Android. Para implementaciones móviles, continúa usando la Verificación de Identidad (HMAC-SHA256) en lugar de JWTs hasta que el SDK lo soporte.
Guía para solución de problemas
Tenemos dos herramientas para ayudarte a depurar tu instalación, una para ver los registros recientes de errores y un depurador de tokens.
Revisa los registros de tu instalación
En el paso 6 bajo Configuración > Canales > Messenger > Seguridad, verás los registros de tu instalación. Estos mostrarán todos los registros de fallos relacionados con tu instalación de JWT. Aquí verás errores que indican si tus JWTs son inválidos, expirados, etc. Haz clic en "Ver registro" para ver un registro completo que incluye el ID de la solicitud, la marca de tiempo, el referer y los datos del user. Esto puede ayudarte a entender por qué falló tu solicitud y rastrearla hasta tu propia app.
Mensajes de error comunes
HTTP 400 - "user_hash and intercom_user_jwt cannot be provided simultaneously": La solicitud incluyó tanto un JWT como un user_hash. Los clientes deben incluir uno de estos valores, pero no ambos.HTTP 400 - “Missing user_id in payload”: Se espera que todos los JWTs incluyan user_id como parte del payload. Si un cliente considera el “email” como su identificador principal, debe poner el valor del email tanto en los campos user_id como email del payload.HTTP 400 - “Invalid intercom_user_jwt payload”: El payload del JWT es inválido. Los clientes deben asegurarse de que el payload esté bien formado, codificado y firmado con un HMAC SHA256 usando el valor api_secret como secreto de firma.HTTP 400 - “Intercom_user_jwt expired”: El ‘exp’ del JWT es una marca de tiempo en el pasado. Los clientes deben proporcionar una fecha de expiración en el futuro.HTTP 400 - “JWT identity mismatch": El ID de user proporcionado en el JWT no coincide con el user asociado con la cookie de sesión activa de intercom. Esto indicaría que hay un intento de iniciar dos sesiones en competencia. Asegúrate de llamar a Intercom('shutdown') antes de intentar iniciar un nuevo user.HTTP 400 - "Invalid intercom_user_jwt": Asegúrate de iniciar correctamente un user válido.Si la verificación del token JWT falla (por ejemplo, por una discrepancia en las reclamaciones o una firma incorrecta), la conversación se cerrará automáticamente y se registrará un error en los registros de errores de la API para ayudar a depurar el problema.
Decodificador JWT
Nuestra herramienta decodificadora también te permite verificar un JSON web token. Puedes encontrarla en la barra lateral en Configuración > Messenger > Seguridad.
En la herramienta puedes verificar uno de tus JWTs de user generados para validez. Elige la clave secreta relevante que usaste para generar el JWT y haz clic en Decodificar.
Una vez decodificado, puedes ver los detalles del user desde el payload del JWT, el encabezado y una nota sobre si es válido o inválido.
En este ejemplo hemos usado tanto un secreto inválido como no incluir el campo user_id, ambos causarán un fallo.
Preguntas frecuentes
¿Por qué se requiere user_id dentro del JWT?
Ahora necesitas proporcionar user_id como tu identificador principal para users. Históricamente, hemos soportado user_id o email como posibles identificadores, pero esto ha creado confusión significativa en la Verificación de Identidad básica. Si solo tienes un email para identificar a tus users, puedes suministrar la dirección de email en ambos atributos user_id y email del payload.
¿Cómo configuro esto para users no conectados, donde no tengo un user_id?
La función de seguridad del Messenger requiere que tus users tengan IDs únicos que tú proporciones. Si solo usas el Messenger para leads, no puedes identificarlos de esta manera. Sin embargo, si tienes users con user_ids en tu workspace desde alguna otra integración (REST API, CSV, etc.) aún deberías habilitar la seguridad JWT del Messenger para evitar que alguien intente iniciar el Messenger para esos users. Para visitantes desconectados, puedes configurar el messenger para que funcione sin autenticación usando una versión ligera. Simplemente carga el script del Messenger solo con el App ID y evita pasar datos de user o tokens JWT. Esto asegura facilidad de uso mientras mantiene la funcionalidad del sistema y la integridad de los datos.
En resumen, si tienes cualquier user en tu workspace que tenga identificadores predecibles (email, user_id), deberías habilitar la seguridad del Messenger. Al soportar tanto users conectados como desconectados, adopta una estrategia mixta para seguridad y usabilidad. Usa autenticación JWT para sesiones de users conectados para proteger información sensible mientras permites que visitantes desconectados usen una configuración simplificada del messenger sin tokens o datos específicos de user.
¿Qué duración de expiración debo establecer?
Debes enviar un nuevo JWT cada vez que se inicie el Messenger, por lo que la vida útil del token solo necesita cubrir el tiempo entre lanzamientos del Messenger. Elige la duración mínima adecuada para el comportamiento de la aplicación. Si la página web se recarga frecuentemente, el JWT debería ser de corta duración, aunque sugerimos un mínimo de 5 minutos para evitar problemas inesperados de expiración. Siempre incluye una reclamación de expiración (exp) en tus JWTs para garantizar seguridad reduciendo el impacto de tokens robados.
¿Qué algoritmo de firma puedo usar?
Soportamos:
HS256 (HMAC con SHA-256). Este algoritmo usa una clave secreta compartida para firmar y verificar el token, asegurando que los datos dentro del token no hayan sido alterados.
RS256 para JWTs, que usa un par de claves asimétricas - privada para firmar y pública para verificar, proporcionando una alternativa para mayor seguridad.
Configuraciones JSON Web Key (JWK), que permiten integración fluida con claves generadas por Fin para una gestión simplificada de tokens.
¿Puedo enviar tanto un user_hash como un intercom_user_jwt?
No, no soportamos enviar ambos user_hash e intercom_user_jwt, ya que el `user_hash` debería ser reemplazado por JWTs. Sin embargo, puedes alternar entre enviar user_hashes y/o valores intercom_user_jwt, ya que algunos clientes necesitarán hacerlo mientras migran de user_hash a intercom_user_jwt.
¿Cómo puedo verificar que mis JWTs son válidos y que todo funciona?
Consulta la sección de solución de problemas arriba.
¿Cómo aplico el requisito de JWTs para mi workspace?
Debes activar el interruptor de aplicación en la configuración del Messenger.
¿Qué atributos debo proteger?
Todos los atributos identificativos deben marcarse como protegidos y enviarse de forma segura en el JWT si es posible. Esto incluye email, teléfono y cualquier account_id que el cliente pueda almacenar en el registro del User. Puedes encontrar tus atributos en Configuración > Datos de Personas.
Cualquier atributo que quieras que Fin use en una parte crítica de una Acción o Workflow debe estar protegido, para asegurar que un user malintencionado no pueda sobrescribir ese valor.
Si quieres enviar datos fuera del JWT, puedes hacerlo siempre que hayas permitido actualizaciones del Messenger, pero ten en cuenta que un user podría actualizar este campo por sí mismo.
window.intercomSettings = {
app_id: <APP_ID_CODE>,
intercom_user_jwt: <TOKEN>,
unsigned_data_attribute: 'data'
};
¿Qué pasa si la sesión expira mientras el user está haciendo algo?
Si hay actividad dentro del Messenger de un user después de que la cookie expire, Intercom emitirá una cookie nueva de corta duración de 1 hora para evitar un impacto negativo en la experiencia del user. Para prevenir efectos no deseados en la experiencia del user, recomendamos elegir una duración de sesión de cookie que coincida con el tiempo de espera de sesión de tu aplicación.
¿Por qué no requerimos que todo el payload esté firmado?
Le permitimos enviar atributos no firmados para situaciones en las que necesita enviar datos de baja fidelidad sobre el User, mientras el User está realizando una acción en su aplicación. Si no necesita esta capacidad, puede actualizar todos sus Atributos de Datos de User para que estén “protegidos contra actualizaciones de Messenger” y solo enviar la carga firmada.
¿Cómo gestiono y rotó mis claves secretas de Messenger?
Su clave secreta puede generarse en la configuración de seguridad de Messenger de su espacio de trabajo.
Puede encontrar y copiar sus claves existentes en la barra lateral derecha de la página de configuración de JWT.
Puede rotar las claves en Workspace > Security > Messenger.
¿Qué pasó con la Verificación de Identidad? ¿Los JWT la reemplazan?
La Verificación de Identidad es la iteración anterior de la Seguridad de Messenger que funciona usando hashes HMAC de user para identificar que una solicitud de user fue enviada por su integración.
Mientras los user_hashes seguirán siendo aceptados, recomendamos encarecidamente a todos los clientes actualizar a usar JWTs ya que ofrece más beneficios de seguridad y la Verificación de Identidad no recibirá futuras actualizaciones.
Si necesita gestionar su instalación de Verificación de Identidad desde las páginas de JWT, aún puede hacerlo. Las instrucciones se han actualizado para reflejar la configuración de JWT, y si realiza cambios recomendamos encarecidamente que migre a JWTs, pero si necesita desactivar la función o rotar sus claves secretas de Messenger API, aún puede hacerlo desde Settings > Security > Messenger.