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 dados potencialmente sensíveis.
Se ajudar, aqui está um vídeo explicativo da funcionalidade e dos riscos que ela mitiga:
Nota:
Se você tem uma integração do Messenger com users logados, recomendamos fortemente que você proteja seu Messenger.
Se múltiplos users compartilham o mesmo endereço de email e sua integração usa apenas 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.
Dica: Ativar a Segurança do Messenger também desbloqueia o histórico completo de conversas dos seus users no Messenger. Sem isso, users logados só podem ver conversas dos últimos 14 dias — uma medida de segurança para evitar acesso não autorizado. Uma vez que a Segurança do Messenger está ativa em um canal, o limite de histórico é removido automaticamente. Veja Visibilidade do histórico de conversas do user para detalhes.
Transmitindo com segurança a identidade e dados do user e aplicando 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 do user.
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 o padrão de 7 dias, 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 do Messenger e uma configuração segura é que você incluirá um campo adicional intercomUserJwt em suas requisições de user que será usado para identificar e atualizar o user.
Nota: 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, você 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, você 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 em Configurações > Workspace > Segurança > Messenger.
Depois, volte para Configurações do Messenger > Segurança e 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:
Importante: As chaves secretas da API do seu 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. A 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>,
};
Este 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 para a API do Messenger, o que significa que qualquer atualização através do Messenger para atualizar esse atributo terá sucesso.
Se você estiver enviando alguns dados com segurança no seu JWT, deve garantir que você desative atualizações inseguras do Messenger para esses atributos para que eles sejam atualizados apenas via um JWT válido. Nota: esse toggle não impede que você colete dados diretamente de leads com um bot
Recomendamos que você ative esse toggle para qualquer atributo que esteja enviando no seu JWT.
Passo 5: Encerrar sessões de usuário ao sair
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 potencialmente 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 sair do Intercom (ou for desconectado automaticamente pelo seu app), chame Intercom('shutdown'); da nossa API JavaScript para encerrar a sessão do Intercom e limpar o cookie.
Passo final: Aplicar Segurança do Messenger para seu workspace
Quando sua integração estiver enviando JWTs corretamente para seus users, você deve aplicar a segurança do Messenger ativando-a em Configurações do Messenger > Segurança. Ao fazer isso, o Intercom exigirá que as solicitaçõ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 solicitação, timestamp, referer e dados do user. Isso pode ajudar a entender por que sua solicitação falhou e ajudar a rastreá-la até seu próprio app.
Mensagens comuns de erro
HTTP 400 - "user_hash and intercom_user_jwt cannot be provided simultaneously": A solicitaçã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”: Espera-se que todos os JWTs incluam 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 que há 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 nas 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 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 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 Verificação Básica de Identidade.
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 configurar 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ê estiver 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 > Install. Escolha o método de instalação que está usando (web, iOS, Android) e verifique se o toggle "Enable connection to messenger" está desligado 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, pois alguns clientes precisarão fazer isso enquanto migram de user_hash para intercom_user_jwt.
Se você estiver usando atualmente Verificação de Identidade e enviando user hashes, veja este guia para alterar 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 aplicar a exigência de JWTs para meu workspace?
Você deve ativar o toggle de aplicaçã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 > People.
Qualquer atributo que você queira que o Fin use em uma parte crítica de uma Action ou Workflow deve ser protegido, para garantir que um user malicioso não possa substituir esse valor.
Se quiser enviar dados fora do JWT, pode fazer isso desde que tenha permitido atualizações do Messenger, mas tenha em mente que um user pode atualizar esse campo sozinho.
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 no Messenger de um user após o cookie expirar, o Intercom emitirá um novo cookie 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á realizando uma ação em sua aplicação. Se o cliente não precisar dessa capacidade, pode atualizar todos os seus Atributos de Dados do User para serem “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 ela?
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 boot (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 múltiplos 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.
Importante: Dados da empresa passados fora do JWT (por exemplo, como um objeto company na sua chamada Intercom('boot')) são ignorados quando um JWT está presente. A empresa não será atualizada, e o valor last_seen da empresa não será atualizado. Para garantir que os dados da empresa sejam atualizados corretamente, inclua-os no payload do seu JWT. Esta é a abordagem recomendada para todas as configurações seguras do Messenger.
Alternativamente, você pode criar empresas e associar users via API do lado servidor antes que qualquer user faça login. Esta é a melhor abordagem quando você precisa que os dados da empresa existam antes da primeira sessão do user — por exemplo, para pré-popular 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.