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.
Para melhorar a segurança e flexibilidade para nossos clientes, introduzimos JSON Web Tokens (JWTs) como uma forma mais segura e escalável de autenticar users no Messenger.
Se você está usando atualmente Verificação de Identidade (IDV) para verificar users, mudar para JWTs lhe dará:
Maior controle sobre autenticação – Gerencie a expiração e revogação da sessão você mesmo, em vez de depender de configurações fixas.
Segurança reforçada – JWTs permitem tokens assinados e com tempo limitado, reduzindo o risco de ataques de repetição.
Melhoria na segurança dos dados – Defina exatamente quais atributos do user podem ser atualizados, reduzindo a exposição de dados sensíveis.
Preparação para o futuro – JWTs são a substituição recomendada para IDV, garantindo que seu sistema de autenticação esteja alinhado com as melhores práticas.
Quem deve migrar?
Esta migração é relevante para todos os clientes que usam IDV atualmente, especialmente se você:
✅ Precisa de melhor controle sobre expiração de sessão e revogação de token
✅ Quer impor atualizações seguras e específicas de atributos do user
✅ Lida com dados sensíveis de clientes e requer autenticação mais forte
✅ Está planejando melhorias de segurança a longo prazo no seu workspace
Embora o IDV continue funcionando por enquanto, JWTs oferecem uma abordagem mais moderna e segura que está alinhada com as melhores práticas de autenticação. Este guia irá orientá-lo passo a passo no processo de migração.
Principais diferenças entre Verificação de Identidade e Segurança do Messenger com JWTs
| Verificação de Identidade | Segurança do Messenger com JWTs |
Método de verificação | Hash assinado HMAC-SHA256 | Token JWT assinado HMAC-SHA256 |
Suporta expiração? | Não | Sim |
Suporta atualizações seguras de dados? | Não | Sim |
Recomendado para | Verificação básica de identidade no Messenger | Autenticação segura com melhor controle de sessão e manipulação segura de dados |
Passos da migração
Passo 1: Atualize sua integração para gerar JWTs em vez de hashes
Pare de gerar assinaturas HMAC-SHA256 (também chamadas de user_hashes) para Verificação de Identidade.
[opcional] Gere uma nova chave secreta para seu Messenger, escolhendo para quais plataformas deseja aplicá-la
Gere um JWT usando sua chave secreta.
Se a Verificação de Identidade já estiver ativada para seu workspace (indicado pelas configurações do Messenger dizendo "instalado com segurança"), a Intercom aceitará apenas requisições contendo um user hash válido ou um JWT válido.
Se desejar verificar se sua implementação de JWT funciona como esperado antes de mudar, recomendamos fazer a integração primeiro no seu workspace de teste.
Nota: workspaces de teste e de produção têm chaves secretas do Messenger diferentes e, portanto, gerarão user hashes e JSON web tokens diferentes.
Aqui está um exemplo de configuração de código do lado do servidor para Node.js:
const jwt = require("jsonwebtoken");
const payload = {
user_id: "USER_ID_HERE", // Required
email: "EMAIL_ADDRESS_HERE", // Optional
data_attribute: "YOUR_DATA", // Optional
exp: Math.floor(Date.now() / 1000) + 3600 // Expires in 1hr
};
const secret = process.env.MESSENGER_SECRET_KEY || "YOUR_MESSENGER_SECRET_KEY"; // Secure key storage
const intercomUserJwt = jwt.sign(payload, secret, { algorithm: "HS256" });O que colocar no payload do seu JWT:
user_idpara identificar o user. Este é um campo obrigatório.Um timestamp opcional (
exp) para expiraçãoQuaisquer outros atributos de dados que você queira enviar com segurança para seus users
Para instruções detalhadas sobre como gerar JWTs para seu workspace, veja nosso artigo principal do help center ou visite suas configurações de segurança.
Passo 1a: Uma nota sobre atributos de dados
Se você está enviando atualmente atributos de dados sobre seus users pelo Messenger, você deve atualizar sua integração para enviar esses atributos com segurança dentro do JWT do user. Para isso, adicione quaisquer atributos ao seu payload e garanta que quaisquer requisições inseguras do Messenger sejam bloqueadas.
No exemplo de código acima, nosso payload assina o user_id e o email. Também inclui uma expiração, que também deve ir para o payload.
Para esses atributos, agora devemos desativar atualizações inseguras do Messenger para esses atributos. Isso significa que eles só podem ser atualizados via JWT válido e nunca sem ele.
Recomendamos que você ative essa opção para qualquer atributo que esteja enviando no seu JWT. Você pode ver os atributos do seu workspace em Configurações > Dados > Pessoas
Nota: Esta opção de atualização de atributo não impede que você colete dados diretamente de leads com um bot. Esses dados vêm diretamente do user.
Passo 2: Atualize seu snippet frontend para enviar JWTs para users
Em vez de passar uma assinatura HMAC para IDV, passe o JWT nas configurações do Messenger como intercom_user_jwt
Para Web (JavaScript SDK):
window.Intercom("boot", {
api_base: "https://api-iam.intercom.io",
app_id: "<YOUR_APP_ID_HERE",
intercom_user_jwt: "<YOUR_USER_JWT_HERE>"
};
Como mencionado na seção anterior, agora estamos enviando nossos atributos de dados dentro do JWT e eles foram removidos do snippet.
Para instruções detalhadas sobre como gerar JWTs para seu workspace, veja nosso artigo principal do help center ou visite suas configurações de segurança. Para instruções móveis, consulte nossa documentação para desenvolvedores para iOS e Android.
Solução de problemas
Existem logs detalhados de falhas e uma ferramenta de depuração de token em suas configurações de segurança para ajudar na migração para JWTs.
Perguntas frequentes
O que acontece se eu não migrar?
A Verificação de Identidade continuará funcionando por enquanto, mas JWTs oferecem segurança mais forte e melhor controle.
Como revogo uma sessão JWT?
Você pode definir uma expiração curta (exp) ou rotacionar as chaves de assinatura para invalidar tokens antigos.
Posso usar Verificação de Identidade e JWTs juntos?
Uma vez que a autenticação JWT esteja ativada para uma plataforma, Verificação de Identidade não é mais necessária. No entanto, você pode usar JWTs e Verificação de Identidade independentemente na web, iOS e Android, pois todos são configurados individualmente.