Se você tem o Messenger instalado no seu site para users logados, é essencial protegê-lo e evitar que agentes mal-intencionados personifiquem seus users ou enviem dados não autorizados.
Em um Messenger que não é seguro, alguém poderia interagir com seu Intercom Messenger e falsificar a identidade de outro user, fornecendo um identificador conhecido como email ou user_id. Isso permite que um atacante se passe por um user real para seus colegas, dando acesso a conversas anteriores e potencialmente dados sensíveis.
Se ajudar, aqui está um vídeo explicativo da funcionalidade e dos riscos que ela mitiga:
Se você tem uma integração do Messenger com users logados, recomendamos fortemente que você proteja seu Messenger.
Nota:
Se múltiplos users compartilharem o mesmo endereço de email e sua integração usar apenas o email como identificador, o Intercom rejeitará a solicitação com um erro de conflito em vez de tentar adivinhar qual user usar. Para garantir autenticação bem-sucedida, sempre inclua um identificador único estável (user_id) no payload do seu JWT. Note que a verificação de identidade JWT exige user_id, tokens sem ele serão rejeitados.
O que é um JSON web token (JWT)?
Um JSON Web Token (JWT) é um padrão da indústria para assinar dados. Normalmente consiste em três partes, separadas por pontos. Um JWT típico se parece com isto: header.payload.signature.
O header especifica o tipo do token (JWT) e o algoritmo de assinatura (ex: HS256).
O payload contém declarações sobre o user ou sessão (ex: user_id, email).
Finalmente, a assinatura garante que o token não foi adulterado, usando uma chave secreta ou privada.
Quais são os benefícios de proteger o Messenger com JSON web tokens (JWTs)?
Identidade segura do user: Proteger seu messenger permite que seus colegas tenham certeza de que o user com quem estão falando é realmente aquele user.
Segurança aprimorada dos dados do user: Proteger seu Messenger permite a transmissão segura de atributos de dados sobre seu user através da API do Messenger.
Risco reduzido de sessões roubadas: Proteger seu Messenger com JWTs permite definir expiração para o token, reduzindo significativamente o risco de vazamentos de dados que poderiam ocorrer se tokens forem roubados do navegador do seu user. Ao especificar uma expiração curta, o risco é diminuído.
Workflows Fin e AI mais seguros: Dê aos seus processos complexos, Actions e Workflows para Fin, mesmo que eles exijam informações confiáveis do user.
Ao transmitir com segurança a identidade e os dados do user e impor a expiração do token, os JWTs garantem que seu Intercom Messenger esteja no estado mais seguro possível.
Experiência do cliente
Ao usar JWTs com o Intercom Messenger, a experiência é a seguinte:
Sua integração do Messenger iniciará seu user logado com uma requisição
Intercom('boot')contendo um JWT, que inclui todos os dados do user que você deseja enviar para o Intercom. A assinatura do JWT é gerada usando a chave secreta do Messenger das suas configurações.Então, o Intercom fornecerá ao user um cookie de sessão no navegador. Esse cookie tem duração padrão de 7 dias. O cookie será usado durante sua vida útil para autenticar o user e realizar quaisquer atualizações nesse user.
Se a sessão expirar e nenhum JWT novo for enviado, a sessão do user terminará. O user verá um Messenger novo como um visitante do site desconectado. Ele não conterá o histórico de conversas.
Uma vez que o Messenger seja reiniciado com
Intercom('boot')e um JWT válido, o Messenger identificará o user e mostrará suas conversas históricas e uma nova sessão. Também iremos mesclar qualquer atividade desconectada que tenha ocorrido no mesmo dispositivo na conta desse user autenticado.
Se desejar que a duração do cookie de sessão do user seja menor que os 7 dias padrão, você pode especificar o TTL do cookie em milissegundos com o atributo session_duration do Messenger.
Instalação: Gerando e enviando JWTs
Passo 1: Instale o Messenger em sua aplicação
Você pode encontrar as instruções únicas de configuração para seu workspace em Configurações > Messenger > Segurança.
A principal diferença entre uma configuração insegura e uma segura do Messenger é que você incluirá um campo adicional intercomUserJwt nas suas requisições de user que será usado para identificar e atualizar o user.
Você verá uma opção para adicionar atributos de dados no seu snippet Javascript. Isso governa quais dados você quer enviar para o Intercom. Como você usará JWTs para transmitir dados para nós, deve incluir aqui apenas atributos que não deseja assinar, por exemplo: se quiser enviar alguns dados específicos do front-end.
Se não quiser enviar nenhum dado fora do JWT, pode remover todos os dados do seu snippet exceto api_base e app_id. Seu app_id é o identificador único do seu workspace Intercom.
Passo 2: Comece a gerar JWTs para seus users
Você pode usar bibliotecas padrão da indústria para gerar o token, usando o segredo da API do Messenger como chave secreta. Sua chave secreta pode ser gerada nas configurações de segurança do Messenger do seu workspace.
Escolha seus frameworks de back e front end para obter exemplos de código relevantes para sua instalação.
Aqui está um exemplo para Node.js:
Nota: Suas chaves secretas da API do Messenger, assim como o código para gerar seus JWTs, nunca devem ser colocados no código front end. Você deve sempre colocar isso no lado do servidor e proteger suas chaves secretas adequadamente.
Se houver atributos adicionais que você queira enviar sobre seus users (ex: price_plan ou number_of_songs_added) você também os adicionaria no seu JWT. user_id é o único campo obrigatório. Saiba mais sobre atributos de dados personalizados aqui.
Quando devo incluir o JWT?
Você deve enviar um JWT para cada requisição onde estiver iniciando um user no Messenger ou tentando atualizar dados sobre ele.
Qual expiração devo definir?
Defina uma expiração curta para seu JWT, garantindo que ele viva tempo suficiente para uma requisição completa chegar e ser processada por nós. Expiração não é um campo obrigatório, mas fortemente recomendada para reduzir o risco de repetição do token.
Passo 3: Adicione JWTs ao seu snippet do Messenger
Ao iniciar o Messenger para um user logado, você pode fornecer um JSON Web Token assinado e atribuí-lo ao atributo intercom_user_jwt do payload do Messenger.
Exemplo de Configuração do Lado do Cliente
window.Intercom("boot", {
api_base: "https://api-iam.intercom.io",
app_id: "APP_ID_CODE",
intercom_user_jwt: <YOUR_USER_JWT_TOKEN>,
};
Esse JWT pode conter quaisquer atributos de dados do user que você queira enviar com segurança para o user. Uma vez que um JWT válido seja recebido para o user, um cookie de sessão será criado no navegador do user com duração padrão de 7 dias.
Para controlar o TTL do cookie de sessão do Messenger, você pode definir um máximo em Configurações > Canais > Messenger > Geral > Mantenha seu Messenger seguro
Passo 4: Garanta que as atualizações estejam desativadas para seus atributos
É possível habilitar atualizações inseguras para atributos de dados da API do Messenger, o que significa que qualquer atualização via Messenger para atualizar esse atributo terá sucesso.
Se você está enviando alguns dados com segurança no seu JWT, deve garantir que desative atualizações inseguras do Messenger para esses atributos para que eles sejam atualizados apenas via JWT válido. Nota: esse toggle não impede que você colete dados diretamente de leads com um bot
Recomendamos que você ative essa opção para qualquer atributo que você esteja enviando no seu JWT.
Passo 5: Encerrar sessões de usuários ao fazer logout
O Intercom permite que você coloque o Intercom Messenger em qualquer site público que você possua (seu site de marketing, seu site de documentação, seu hub de desenvolvedores, etc). Para manter a continuidade das conversas em todos esses subdomínios diferentes enquanto seus users estiverem logados, definimos um cookie no navegador do seu user. Esse cookie expira após uma semana.
Qualquer user que use um computador e navegador compartilhados com outra pessoa poderá ver o histórico de conversas do user que fez login mais recentemente até que o cookie expire. Por isso, é muito importante encerrar corretamente o Intercom quando a sessão de um user no seu app terminar (via logout manual ou automático).
Veja como encerrar o Intercom:
Você já terá começado a rastrear seu user via o snippet Intercom JS ou o método “boot”.
Quando seu user fizer logout do Intercom (ou for automaticamente desconectado pelo seu app), chame Intercom('shutdown'); da nossa API JavaScript para encerrar a sessão do Intercom e limpar o cookie.
🎉 Passo final: Impor Segurança do Messenger para seu workspace
Quando sua integração estiver enviando JWTs corretamente para seus users, você deve impor a segurança do Messenger ativando-a nas configurações do Messenger. Fazendo isso, o Intercom exigirá que as requisições para seus users do workspace sejam protegidas com um JWT válido ou um user_hash válido.
Orientações para solução de problemas
Temos duas ferramentas para ajudar você a depurar sua instalação, uma para ver logs recentes de erros e um depurador de token.
Verifique seus logs de instalação
No passo 6 em Configurações > Canais > Messenger > Segurança, você verá seus logs de instalação. Eles mostrarão todos os logs de falhas relacionados à sua instalação de JWT. Aqui você verá erros indicando se seus JWTs são inválidos, expirados etc. Você pode clicar em "Ver log" para ver um log completo incluindo o ID da requisição, timestamp, referer e dados do user. Isso pode ajudar a entender por que sua requisição falhou e ajudar a rastreá-la até seu próprio app.
Mensagens de erro comuns
HTTP 400 - "user_hash and intercom_user_jwt cannot be provided simultaneously": A requisição incluiu tanto um JWT quanto um user_hash. Os clientes devem incluir um desses valores, mas não ambos.HTTP 400 - “Missing user_id in payload”: Todos os JWTs devem incluir user_id como parte do payload. Se um cliente considera “email” seu identificador principal, ele deve colocar o valor do email tanto no campo user_id quanto no campo email do payload.HTTP 400 - “Invalid intercom_user_jwt payload”: O payload do JWT é inválido. Os clientes devem garantir que o payload esteja bem formado, codificado e assinado com um HMAC SHA256 usando o valor api_secret como segredo de assinatura.HTTP 400 - “Intercom_user_jwt expired”: O ‘exp’ do JWT é um timestamp no passado. Os clientes devem fornecer uma data de expiração no futuro.HTTP 400 - “JWT identity mismatch": O ID do user fornecido no JWT não corresponde ao user associado ao cookie de sessão ativo do intercom. Isso indica uma tentativa de iniciar duas sessões concorrentes. Certifique-se de chamar Intercom('shutdown') antes de tentar iniciar um novo user.HTTP 400 - "Invalid intercom_user_jwt": Certifique-se de estar iniciando corretamente um user válido.
Decodificador JWT
Nossa ferramenta de decodificação também oferece uma forma de verificar um JSON web token. Você pode encontrá-la na barra lateral das páginas de instalação.
Na ferramenta, você pode verificar um dos seus JWTs de user gerados para validade. Escolha a chave secreta relevante que você usou para gerar o JWT e clique em Decodificar.
Uma vez decodificado, você pode ver os detalhes do user do payload do seu JWT, o cabeçalho e uma nota indicando se é válido ou inválido. Ver o payload pode ser útil para ajudar a solucionar problemas sobre se você está enviando um atributo ou não.
Neste exemplo, usei tanto um segredo inválido quanto não incluí o campo user_id, ambos causarão uma falha.
Perguntas frequentes
Por que o user_id é obrigatório no JWT? Meus users só têm endereços de email.
Agora você precisa fornecer user_id como seu identificador principal para users. Historicamente, suportávamos user_id ou email como identificadores potenciais, mas isso criou confusão significativa no produto em relação à Verificação de Identidade básica.
Se você só tem um email para identificar seus users, pode fornecer o endereço de email tanto no user_id quanto nos atributos email do payload. No entanto, se você já tem seus users no Intercom apenas com um endereço de email, terá que atualizá-los para ter um user ID antes de poder usar JWTs. Isso porque o user ID é um identificador de ordem superior para users do que o endereço de email.
Para adicionar user ID para seus users, primeiro identifique o user com o Intercom ID do user. Você pode fazer isso via nossa API com o endpoint "Get a contact". Depois use o endpoint "Update a Contact" para adicionar um user_id ao user. Mais detalhes aqui
Como configuro isso para users não logados, onde não tenho um user_id?
O recurso de segurança do Messenger exige que seus users tenham IDs únicos que você forneça. Se você está usando o Messenger apenas para leads, não pode identificá-los dessa forma. Você deve garantir que as APIs do Messenger estejam desativadas para o tráfego de users, já que você não espera tráfego de users por esse canal.
Você pode fazer isso em Messenger > Instalar. Escolha o método de instalação que você está usando (web, iOS, Android) e verifique se a opção "Ativar conexão com o messenger" está desligada para users.
Qual deve ser o tempo de expiração?
Você deve enviar um novo JWT toda vez que o Messenger for iniciado, então a duração do token só precisa suportar o tempo entre os lançamentos do Messenger. Escolha a duração mínima adequada ao comportamento da aplicação. Se a página web for recarregada frequentemente, o JWT deve ser de curta duração, embora sugerimos um mínimo de 5 minutos para evitar problemas inesperados de expiração.
Qual algoritmo de assinatura posso usar?
Suportamos HS256 (HMAC com SHA-256). Esse algoritmo usa uma chave secreta compartilhada para assinar e verificar o token, garantindo que os dados dentro do token não foram adulterados.
Posso enviar tanto um user_hash quanto um intercom_user_jwt?
Não, não suportamos enviar ambos user_hash e intercom_user_jwt, pois o `user_hash` deve ser substituído pelos JWTs. No entanto, você pode alternar entre enviar user_hashes e/ou valores intercom_user_jwt, já que alguns clientes precisarão fazer isso enquanto migram de user_hash para intercom_user_jwt.
Se você está usando atualmente a Verificação de Identidade e enviando user hashes, veja este guia para mudar sua integração para enviar JWTs em vez disso.
Como posso verificar se meus JWTs são válidos e se tudo está funcionando?
Veja a seção de solução de problemas acima.
Como faço para impor a exigência de JWTs para meu workspace?
Você deve ativar a opção de imposição nas configurações do Messenger.
Quais atributos devo proteger?
Todos os atributos identificadores devem ser marcados como protegidos e enviados com segurança no JWT, se possível. Isso inclui email, telefone e quaisquer account_ids que o cliente possa armazenar no registro do User. Você pode encontrar seus atributos em Configurações > Dados > Pessoas.
Qualquer atributo que você queira que o Fin use em uma parte crítica de uma Ação ou Workflow deve ser protegido, para garantir que um user malicioso não possa substituir esse valor.
Se você quiser enviar dados fora do JWT, pode fazer isso desde que tenha permitido atualizações do Messenger, mas lembre-se que um user pode atualizar esse campo por conta própria.
window.intercomSettings = {
app_id: <APP_ID_CODE>,
intercom_user_jwt: <TOKEN>,
unsigned_data_attribute: 'data'
};
E se a sessão expirar no meio do uso do user?
Se houver atividade dentro do Messenger de um user após o cookie expirar, o Intercom emitirá um cookie novo e de curta duração de 1 hora para evitar impacto negativo na experiência do user. Para evitar efeitos indesejados na experiência do user, recomendamos que você escolha uma duração de sessão do cookie que corresponda ao tempo limite da sessão da sua aplicação.
E quanto ao meu Messenger móvel?
Por que não exigimos que o payload completo seja assinado?
Permitimos que os clientes enviem Atributos não assinados para suportar situações em que precisam enviar dados de baixa fidelidade sobre o User, enquanto o User está agindo em sua aplicação. Se o cliente não precisar dessa capacidade, pode atualizar todos os seus Atributos de Dados do User para "protegidos contra atualizações do Messenger" e enviar apenas o payload assinado.
Como gerencio e rotaciono minhas chaves secretas do Messenger?
Sua chave secreta pode ser gerada nas configurações de segurança do Messenger do seu workspace.
Você pode encontrar e copiar suas chaves existentes na barra lateral direita da página de configuração do JWT.
Você pode rotacionar chaves em Workspace > Security > Messenger.
Os atributos incluídos em um JWT podem se aplicar apenas a um único ticket ou conversa?
Não. Quaisquer atributos que você incluir em um JSON Web Token (JWT) sempre atualizarão o perfil do user no Intercom. Os atributos do JWT não podem ser usados para adicionar dados que se aplicam apenas a um único ticket ou conversa.
O que aconteceu com a Verificação de Identidade? Isso substitui isso?
A Verificação de Identidade é a iteração anterior da Segurança do Messenger que funciona usando hashes HMAC do user para identificar que uma solicitação do user foi enviada pela sua integração.
Embora os user_hashes continuem sendo aceitos, recomendamos fortemente que todos os clientes atualizem para usar JWTs, pois isso oferece mais benefícios de segurança e a Verificação de Identidade não receberá atualizações futuras.
Se você precisar gerenciar sua instalação de Verificação de Identidade a partir das páginas de JWT, ainda pode. As instruções foram atualizadas para refletir a configuração do JWT, e se você estiver fazendo alterações, recomendamos fortemente que migre para JWTs, mas se precisar desativar o recurso ou rotacionar suas chaves secretas da API do Messenger, ainda pode fazer isso na página de configuração do JWT.
Posso incluir dados da empresa no meu JWT para associar users a uma empresa?
Sim. Você pode incluir company_id e outros atributos da empresa no payload do seu JWT para associar users a uma empresa no Intercom. Quando presente, o Intercom criará e associará automaticamente a empresa no momento do boot — da mesma forma que passar dados da empresa em Intercom('boot') funciona. Nenhuma latência adicional é introduzida, pois a empresa é criada inline durante a requisição de ping/boot.
Isso é particularmente importante para configurações que usam recursos em nível de empresa, como o Tickets Portal, onde tickets enviados por vários users precisam ser agrupados em uma visão compartilhada da empresa. Se os users não estiverem sendo associados a uma empresa, verifique se company_id está incluído no payload do seu JWT.
Alternativamente, você pode criar empresas e associar users via API do lado do servidor antes que qualquer user faça login. Essa é a melhor abordagem quando você precisa que os dados da empresa existam antes da primeira sessão do user — por exemplo, para pré-preencher registros da empresa no momento da criação do tenant.
Nota: Se você está passando company_id no seu JWT, mas as empresas não estão sendo criadas no Intercom, informe nossa equipe de suporte, pois isso pode indicar um bug.