Si tienes el Messenger instalado en tu sitio para users conectados, es esencial asegurarlo y evitar que actores malintencionados suplantan a tus users o envíen datos no autorizados.
En un Messenger que no es seguro, alguien podría interactuar con tu Intercom Messenger y falsificar la identidad de otro user, proporcionando un identificador conocido como su dirección de 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.
Si te ayuda, aquí tienes un video explicativo de la función y los riesgos que mitiga:
Si tienes una integración de Messenger con users conectados, te recomendamos encarecidamente que asegures tu Messenger.
Nota:
Si varios users comparten la misma dirección de correo electrónico y tu integración usa solo el correo electrónico como identificador, Intercom rechazará la solicitud con un error de conflicto en lugar de adivinar qué user usar. Para asegurar una autenticación exitosa, siempre incluye un identificador único estable (user_id) en la carga útil de tu JWT. Ten en cuenta que la verificación de identidad JWT requiere user_id, los tokens sin él serán rechazados.
¿Qué es un JSON web token (JWT)?
Un JSON Web Token (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 encabezado especifica el tipo de token (JWT) y el algoritmo de firma (por ejemplo, HS256).
La carga útil contiene afirmaciones sobre el user o la sesión (por ejemplo, user_id, email).
Finalmente, la firma asegura que el token no ha sido manipulado, 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 el que están hablando 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 una expiración para el 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 reduce el riesgo.
Workflows y Fin más seguros: Da a tus procesos complejos, Actions y Workflows a Fin, incluso si requieren información confiable del user.
Al transmitir de forma segura la identidad y los datos del user y hacer cumplir la expiración del token, los JWTs aseguran que tu Intercom Messenger esté en el estado más seguro posible.
Experiencia del cliente
Al usar JWTs con el Intercom Messenger, la experiencia es la siguiente:
Tu integración de Messenger iniciará a tu user conectado con una solicitud
Intercom('boot')que contiene un JWT, que incluye todos los datos del user que desees enviar a Intercom. La firma del JWT se genera usando la clave secreta del Messenger de tus configuraciones.Luego, Intercom 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 un 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 le mostrará sus conversaciones históricas y una nueva sesión. Además, fusionaremos cualquier actividad desconectada que haya ocurrido en el mismo dispositivo en la cuenta de ese user autenticado.
Si deseas que la vida útil de la cookie de sesión del user sea más corta que los 7 días predeterminados, puedes especificar el TTL de la cookie en milisegundos con el atributo session_duration del Messenger.
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 espacio de trabajo en Configuración > Messenger > Seguridad.
La principal diferencia entre una configuración insegura del Messenger y una configuración segura 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 de Javascript. Esto gobierna qué datos quieres enviar a Intercom. Dado que usarás JWTs para transmitir datos, solo debes incluir aquí atributos que no quieras firmar, por ejemplo: si quieres enviar algunos datos específicos del front-end.
Si no quieres enviar ningún dato 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 espacio de trabajo de Intercom.
Paso 2: Comienza a generar JWTs para tus users
Puedes usar bibliotecas estándar de JWT para generar el token, usando el Messenger API Secret como clave secreta. Tu clave secreta puede generarse en la configuración de seguridad del Messenger de tu espacio de trabajo.
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:
Nota: Tus claves secretas de la API del Messenger, así como el código para generar tus JWTs, nunca deben ponerse en el código front-end. Siempre debes poner esto en el servidor y asegurar tus claves secretas adecuadamente.
Si hay atributos adicionales que quieres enviar sobre tus users (por ejemplo: price_plan o number_of_songs_added) también los agregarías a tu JWT. user_id es el único campo obligatorio. Aprende más sobre atributos de datos personalizados aquí.
¿Cuándo debo incluir el JWT?
Debes enviar un JWT para cada solicitud en la que estés iniciando un user en el Messenger o intentando actualizar datos sobre él.
¿Qué expiración debo establecer?
Establece una expiración corta para tu JWT, asegurando que viva lo suficiente para que una solicitud completa nos llegue y sea procesada. La expiración no es un campo obligatorio pero se recomienda encarecidamente para reducir el riesgo de repetición de tokens.
Paso 3: Agrega JWTs a tu fragmento del Messenger
Al lanzar el Messenger para un user conectado, puedes proporcionar un JSON Web Token firmado y asignarlo al atributo intercom_user_jwt de la carga útil del Messenger.
Ejemplo de configuración del lado del 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 para el user. 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 Configuración > Canales > Messenger > General > Mantén tu Messenger seguro
Paso 4: Asegúrate de que las actualizaciones estén deshabilitadas para tus atributos
Es posible habilitar actualizaciones inseguras para atributos de datos para la API del Messenger, lo que significa que cualquier actualización a través del Messenger para actualizar ese atributo tendrá éxito.
Si estás enviando 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 que habilites este interruptor para cualquier atributo que estés enviando en tu JWT.
Paso 5: Cerrar sesiones de usuario al cerrar sesión
Intercom te permite poner el Intercom Messenger en cualquier sitio público que poseas (tu sitio de marketing, tu sitio de documentación, tu centro de desarrolladores, etc.). Para mantener la continuidad de las conversaciones a través de todos estos subdominios potencialmente diferentes 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 esto, es muy importante cerrar correctamente Intercom cuando la sesión de un user en tu app termine (ya sea cerrando sesión manual o automáticamente).
Aquí te mostramos cómo cerrar Intercom:
Ya habrás comenzado a rastrear a tu user mediante el fragmento JS de Intercom o el método “boot”.
Cuando tu user cierre sesión en Intercom (o sea cerrado automáticamente por tu app), llama a Intercom('shutdown'); desde nuestra API de JavaScript para finalizar la sesión de Intercom y borrar la cookie.
🎉 Paso final: Aplicar seguridad al Messenger para tu espacio de trabajo
Cuando tu integración esté enviando correctamente JWTs para tus users, deberías aplicar la seguridad del Messenger activándola en la configuración del Messenger. Al hacer esto, Intercom requerirá que las solicitudes para los users de tu espacio de trabajo estén aseguradas con un JWT válido o un user_hash válido.
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. Puedes hacer 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 comunes de error
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 - “Falta user_id en la carga útil”: Se espera que todos los JWTs incluyan user_id como parte de la carga útil. Si un cliente considera “email” su identificador principal, debe poner el valor de email tanto en los campos user_id como email en la carga útil.HTTP 400 - “Carga útil intercom_user_jwt inválida”: La carga útil del JWT es inválida. Los clientes deben asegurarse de que la carga útil esté bien formada, codificada y firmada con un HMAC SHA256 usando el valor api_secret como secreto de firma.HTTP 400 - “Intercom_user_jwt expirado”: 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 - “Desajuste de identidad JWT": 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 sesión con un nuevo user.HTTP 400 - "Intercom_user_jwt inválido": Asegúrate de iniciar sesión correctamente con un user válido.
Decodificador JWT
Nuestra herramienta decodificadora también te ofrece una forma de verificar un JSON web token. Puedes encontrarla en la barra lateral en las páginas de instalación.
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 la carga útil de tu JWT, el encabezado y una nota sobre si es válido o inválido. Ver la carga útil puede ser útil para ayudar a solucionar problemas sobre si estás enviando un atributo o no.
En este ejemplo he usado tanto un secreto inválido como no he incluido el campo user_id, ambos causarán un fallo.
Preguntas frecuentes
¿Por qué se requiere user_id dentro del JWT? Mis users solo tienen direcciones de email.
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 tanto en los atributos user_id como email de la carga útil. Sin embargo, si actualmente ya tienes tus users en Intercom solo con una dirección de email, tendrás que actualizarlos para que tengan un user ID antes de poder usar JWTs. Esto se debe a que el user ID es un identificador de orden superior para users que la dirección de email.
Para agregar user ID a tus users, primero identifica al user con el ID de Intercom para el user. Puedes hacer esto a través de nuestra API con el endpoint "Get a contact". Luego usa el endpoint "Update a Contact" para agregar un user_id al user. Más detalles aquí
¿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. Debes asegurarte de que las APIs del Messenger estén deshabilitadas para el tráfico de users, ya que no esperas tráfico de users a través de este canal.
Puedes hacer esto en Messenger > Instalar. Elige el método de instalación que estás usando (web, iOS, Android) y verifica que el interruptor "Habilitar conexión al messenger" esté desactivado para users.
¿Qué debería establecer como expiración?
Debes enviar un nuevo JWT cada vez que se inicie el Messenger, por lo que la duración del token solo necesita soportar el tiempo entre lanzamientos del Messenger. Elige la duración mínima que sea adecuada para el comportamiento de la aplicación. Si la página web se recarga con frecuencia, el JWT debería ser de corta duración, aunque sugerimos un mínimo de 5 minutos para evitar problemas inesperados de expiración.
¿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.
¿Puedo enviar tanto un user_hash como un intercom_user_jwt?
No, no soportamos enviar ambos, user_hash y el 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 hacer esto mientras migran de user_hash a intercom_user_jwt.
Si actualmente usas Identity Verification y envías user hashes, consulta esta guía para cambiar tu integración y enviar JWTs en su lugar.
¿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 espacio de trabajo?
Debes habilitar el interruptor de aplicación en la configuración de tu 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_ids que el cliente pueda almacenar en el registro de User. Puedes encontrar tus atributos en Configuración > Datos > 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 que elijas una duración de sesión para la cookie que coincida con el tiempo de espera de sesión de tu aplicación.
¿Y qué pasa con mi Messenger móvil?
¿Por qué no requerimos que se firme toda la carga útil?
Permitimos que los clientes envíen Atributos no firmados para apoyar situaciones donde necesitan enviar datos de baja fidelidad sobre el User, mientras el User está tomando acción en su aplicación. Si el cliente no necesita esta capacidad, puede actualizar todos sus Atributos de Datos de User para que estén “protegidos de actualizaciones de Messenger” y solo enviar la carga útil firmada.
¿Cómo gestiono y rotó mis claves secretas de Messenger?
Tu clave secreta puede generarse en la configuración de seguridad de Messenger de tu workspace.
Puedes encontrar y copiar tus claves existentes en la barra lateral derecha de la página de configuración de JWT.
Puedes rotar claves en Workspace > Security > Messenger.
¿Pueden los atributos incluidos en un JWT aplicarse solo a un ticket o conversación individual?
No. Cualquier atributo que incluyas en un JSON Web Token (JWT) siempre actualizará el perfil del user en Intercom. Los atributos JWT no pueden usarse para agregar datos que apliquen solo a un ticket o conversación individual.
¿Qué pasó con la Verificación de Identidad? ¿Esto la reemplaza?
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 tu integración.
Mientras los user_hashes seguirán siendo aceptados, recomendamos encarecidamente que todos los clientes actualicen a usar JWTs ya que ofrece más beneficios de seguridad y la Verificación de Identidad no recibirá futuras actualizaciones.
Si necesitas gestionar tu instalación de Verificación de Identidad desde las páginas de JWT, aún puedes hacerlo. Las instrucciones se han actualizado para reflejar la configuración de JWT, y si haces cambios recomendamos encarecidamente que pases a JWTs, pero si necesitas desactivar la función o rotar tus claves secretas de Messenger API, aún puedes lograrlo desde la página de configuración de JWT.
¿Puedo incluir datos de la empresa en mi JWT para asociar users con una empresa?
Sí. Puedes incluir company_id y otros atributos de la empresa en la carga útil de tu JWT para asociar users con una empresa en Intercom. Cuando están presentes, Intercom creará y asociará automáticamente la empresa al iniciar — de la misma manera que funciona pasar datos de la empresa en Intercom('boot'). No se introduce latencia adicional, ya que la empresa se crea en línea durante la solicitud de ping/boot.
Esto es particularmente importante para configuraciones que usan funciones a nivel de empresa como el Tickets Portal, donde los tickets enviados por múltiples users necesitan consolidarse en una vista compartida de la empresa. Si los users no están siendo asociados con una empresa, verifica que company_id esté incluido en la carga útil de tu JWT.
Alternativamente, puedes crear empresas y asociar users vía la API del lado del servidor antes de que cualquier user inicie sesión. Este es el mejor enfoque cuando necesitas que los datos de la empresa existan antes de la primera sesión del user — por ejemplo, para prellenar registros de empresa al crear el tenant.
Nota: Si estás pasando company_id en tu JWT pero las empresas no se están creando en Intercom, informa esto a nuestro equipo de soporte ya que puede indicar un bug.