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 potencialmente datos sensibles.
Si te ayuda, aquí tienes un video explicativo de la función y los riesgos que mitiga:
Nota:
Si tienes una integración de Messenger con users conectados, recomendamos encarecidamente que asegures tu Messenger.
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 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 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, el riesgo disminuye.
Workflows y Fin más seguros: Da a tus procesos complejos, Actions y Workflows a Fin, incluso si requieren información confiable del user.
Consejo: Activar la seguridad del Messenger también desbloquea el historial completo de conversaciones de tus users en el Messenger. Sin ella, los users conectados solo pueden ver conversaciones de los últimos 14 días, una medida de seguridad para evitar accesos no autorizados. Una vez que la seguridad del Messenger está activa en un canal, el límite de historial se elimina automáticamente. Consulta Visibilidad del historial de conversaciones del user para más detalles.
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, combinaremos cualquier actividad desconectada que haya ocurrido en el mismo dispositivo en la cuenta de ese user autenticado.
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.
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 segura es que incluirás un campo adicional intercomUserJwt en tus solicitudes de user que se usará para identificar y actualizar al user.
Nota: Verás una opción para agregar atributos de datos en tu fragmento de Javascript. Esto regula 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 Configuración > Espacio de trabajo > Seguridad > Messenger.
Luego vuelve a Configuración del Messenger > Seguridad y 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:
Importante: 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 en 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 donde 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 alcance 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 desactivar las actualizaciones inseguras de 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 actives este interruptor para cualquier atributo que envíes 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 en 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 un ordenador 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 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 desconectado 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 la seguridad de Messenger para tu espacio de trabajo
Cuando tu integración envíe correctamente JWTs para tus users, debes aplicar la seguridad de Messenger activándola en Configuración de Messenger > Seguridad. 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, han expirado, 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 - “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 el “email” como su identificador principal, debe poner el valor del 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 permite verificar un JSON web token. Puedes encontrarla en la barra lateral de 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 una confusión significativa en la Verificación básica de Identidad.
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 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 añadir 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 añadir 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 de Messenger requiere que tus users tengan IDs únicos que tú proporciones. Si solo usas Messenger para leads, no puedes identificarlos de esta manera. Debes asegurarte de que las APIs de 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 > Install. Elige el método de instalación que estás usando (web, iOS, Android) y verifica que el interruptor "Enable connection to messenger" esté apagado para users.
¿Qué debo establecer como fecha de expiración?
Debes enviar un nuevo JWT cada vez que se inicie Messenger, por lo que la duración del token solo necesita cubrir el tiempo entre lanzamientos de Messenger. Elige la duración mínima adecuada para el comportamiento de la aplicación. Si la página web se recarga con frecuencia, el JWT debe 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 valores de user_hash y/o intercom_user_jwt, ya que algunos clientes necesitarán hacerlo 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 activar 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_id que el cliente pueda almacenar en el registro de User. Puedes encontrar tus atributos en Configuración > Datos > People.
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 de 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 de cookie que coincida con el tiempo de espera de sesión de tu aplicación.
¿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 realiza acciones 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.
¿Los atributos incluidos en un JWT solo pueden aplicarse a un solo ticket o conversación?
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.
¿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 migres a JWTs, pero si necesitas desactivar la función o rotar tus claves secretas de Messenger API, aún puedes hacerlo desde la página de configuración de JWT.
¿Puedo incluir datos de empresa en mi JWT para asociar users con una empresa?
Sí. Puedes incluir company_id y otros atributos de 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 (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 deben consolidarse en una vista compartida de la empresa. Si los users no se están asociando con una empresa, verifica que company_id esté incluido en la carga útil de tu JWT.
Importante: Los datos de empresa pasados fuera del JWT (por ejemplo, como un objeto company en tu llamada Intercom('boot')) se ignoran cuando hay un JWT presente. La empresa no se actualizará y el valor last_seen de la empresa no se refrescará. Para asegurar que los datos de empresa se actualicen correctamente, inclúyelos en la carga útil de tu JWT. Este es el enfoque recomendado para todas las configuraciones seguras de Messenger.
Alternativamente, puedes crear empresas y asociar users vía la API del lado servidor antes de que cualquier user inicie sesión. Este es el mejor enfoque cuando necesitas que los datos de empresa existan antes de la primera sesión de 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.