JSON web tokens (JWTs) impedem terceiros de personificar seus users logados e ver suas conversas. Recomendamos fortemente que todos os clientes Fin apliquem autenticação JWT.

Se você tem o Fin Messenger instalado no seu site para users logados, é essencial protegê-lo e evitar que agentes maliciosos personifiquem seus users ou enviem dados não autorizados.

Em um Messenger que não é seguro, alguém poderia interagir com seu Fin 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.

O que é um JSON web token (JWT)?

Um JWT é uma forma 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 de 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ê seus processos complexos, Actions e Workflows para Fin, mesmo que exijam informações confiáveis do user.

Ao transmitir com segurança a identidade e dados do user e aplicar a expiração do token, os JWTs garantem que seu Fin Messenger esteja no estado mais seguro possível.

Experiência do cliente

Ao usar JWTs com o Fin 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 seu workspace. A assinatura do JWT é gerada usando a chave secreta do Messenger nas suas configurações.
Então, seu workspace 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 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 ocorreu no mesmo dispositivo na conta desse user autenticado.

Dicas:

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.
Se você está criando tickets Zendesk a partir do Fin Messenger e quer que os tickets sejam direcionados para uma organização específica, você pode incluir um campo de empresa no JWT. O valor id deve corresponder ao ID externo da organização Zendesk (não o ID interno do Zendesk).

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 intercomUserJwt adicional nas requisições do 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 determina quais dados você quer enviar para seu workspace Fin. 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 Fin.

Para visitantes sem identificadores específicos de user (como user_id ou email), configure um snippet do Messenger desconectado incluindo apenas o App ID na configuração. Evite adicionar atributos de user para manter uma configuração leve e segura para visitantes anônimos.

Passo 2: Comece a gerar JWTs para seus users

Você pode usar bibliotecas padrão JWT para gerar o token, usando o Messenger API Secret como chave secreta. Sua chave secreta pode ser gerada nas configurações de segurança do seu workspace, na aba do messenger.

Nota: Tokens JWT devem ser gerados exclusivamente para cada sessão de user usando qualquer biblioteca padrão JWT. Os tokens devem incluir declarações identificadoras como user_id e ser assinados com o Messenger API Secret para garantir associação segura com o user correto.

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:

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. Garanta que os nomes dos campos no payload do JWT e nos atributos sejam sensíveis a maiúsculas e minúsculas. Por exemplo, "user_id" deve ser escrito com 'i' minúsculo em vez de "user_Id", pois a sensibilidade incorreta pode atrapalhar a identificação correta do user.

Nota: Ao usar o JWK gerado pelo Fin para assinar tokens JWT, a declaração sub padrão é o User ID atribuído pelo Fin e serve como identificador único do user. Isso fornece um mecanismo consistente e seguro para identificação do user. Ao usar o mecanismo JWK, o valor sub é fixo e não pode ser personalizado, garantindo compatibilidade e evitando configurações incorretas.

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. Alternativamente, você também pode usar Intercom.setUserJwt(jwt) antes de logar um user para atribuir o token JWT para atribuição segura de dados.

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 Manter seu Messenger seguro no menu suspenso em suas Configurações Gerais do Messenger.

Passo 4: Garanta que as atualizações estejam desativadas para seus atributos

É possível ativar 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, de modo que sejam atualizados apenas via JWT válido. Nota: esse controle não impede que você colete dados diretamente de leads com um bot.

Recomendamos que você ative esse controle para qualquer atributo que esteja enviando no seu JWT.

Passo 5: Encerre sessões de users ao sair

Você pode instalar o Fin 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 user. Esse cookie expira após uma semana.

Qualquer usuário que utilize um computador e navegador compartilhados com outra pessoa poderá ver o histórico de conversas do usuário que fez login mais recentemente até que o cookie expire. Por isso, é muito importante encerrar corretamente o Fin Messenger quando a sessão de um usuário no seu app terminar (seja manualmente ou automaticamente).

Veja como encerrar o Fin Messenger:

Você já terá começado a rastrear seu usuário via o snippet Intercom JS ou pelo método “boot”.
Quando seu usuário fizer logout do Fin Messenger (ou for desconectado automaticamente pelo seu app), chame Intercom('shutdown'); da nossa API JavaScript para encerrar a sessão e limpar o cookie.

Passo final: Aplique a 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 nas configurações do Messenger. Ao fazer isso, o Fin Messenger exigirá que as requisições para os users do seu workspace sejam protegidas com um JWT válido ou um user_hash válido.

Nota: A autenticação JWT não é atualmente suportada para os SDKs Fin Messenger iOS ou Android. Para implementações móveis, continue usando Verificação de Identidade (HMAC-SHA256) em vez de JWTs até que o suporte ao SDK esteja disponível.

Orientações para solução de problemas

Temos duas ferramentas para ajudar a depurar sua instalação, uma para ver logs recentes de erros e um depurador de token.

Verifique os logs da sua instalação

No passo 6 em Configurações > Canais > Messenger > Segurança, você verá os logs da sua instalação. Eles mostrarão todos os logs de falhas relacionadas à 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 ID da requisição, timestamp, referer e dados do usuário. Isso pode ajudar a entender por que sua requisição falhou e 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 usuário fornecido no JWT não corresponde ao usuário associado ao cookie de sessão intercom ativo. Isso indica uma tentativa de iniciar duas sessões concorrentes. Certifique-se de chamar Intercom('shutdown') antes de tentar iniciar um novo usuário.
HTTP 400 - "Invalid intercom_user_jwt": Certifique-se de estar iniciando um usuário válido corretamente.
Se a verificação do token JWT falhar (por exemplo, por divergência nas claims ou assinatura incorreta), a conversa será automaticamente encerrada e um erro será registrado nos logs de erro da API para ajudar na depuração do problema.

Decodificador JWT

Nossa ferramenta de decodificação também permite verificar um JSON web token. Você pode encontrá-la na barra lateral em Configurações > Messenger > Segurança.

Na ferramenta, você pode verificar um dos seus JWTs de usuário 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 usuário do payload do seu JWT, o cabeçalho e uma nota indicando se é válido ou inválido.

Neste exemplo, usamos 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?

Agora você precisa fornecer user_id como seu identificador principal para users. Historicamente, suportávamos user_id ou email como identificadores potenciais, mas isso causou 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.

Como configurar isso para users não logados, quando 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ê usa o Messenger apenas para leads, não pode identificá-los dessa forma. No entanto, se você tem users com user_ids no seu workspace de outra integração (REST API, CSV etc), ainda deve ativar a segurança JWT do Messenger para evitar que alguém tente iniciar o Messenger para esses users. Para visitantes deslogados, você pode configurar o messenger para funcionar sem autenticação usando uma versão leve. Basta carregar o script do Messenger apenas com o App ID e evitar passar dados do usuário ou tokens JWT. Isso garante facilidade de uso mantendo a funcionalidade do sistema e a integridade dos dados.

Resumindo, se você tem algum user no seu workspace com identificadores previsíveis (email, user_id), deve ativar a segurança do Messenger. Ao suportar users logados e deslogados, adote uma estratégia mista para segurança e usabilidade. Use autenticação JWT para sessões de users logados para proteger informações sensíveis, enquanto permite que visitantes deslogados usem uma configuração simplificada do messenger sem tokens ou dados específicos do usuário.

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 cobrir 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 de expiração inesperada. Sempre inclua uma claim de expiração (exp) nos seus JWTs para garantir segurança reduzindo o impacto de tokens roubados.

Qual algoritmo de assinatura posso usar?

Suportamos:

HS256 (HMAC com SHA-256). Este algoritmo usa uma chave secreta compartilhada para assinar e verificar o token, garantindo que os dados dentro do token não foram adulterados.
RS256 para JWTs, que usa um par de chaves assimétricas - privada para assinatura e pública para verificação, oferecendo uma alternativa para segurança aprimorada.
Configurações JSON Web Key (JWK), que permitem integração perfeita com chaves geradas pelo Fin para gerenciamento simplificado de tokens.

Posso enviar user_hash e intercom_user_jwt ao mesmo tempo?

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.

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 a opção 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 de 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 usuário malicioso não possa sobrescrever esse valor.

Se quiser enviar dados fora do JWT, pode fazer isso desde que tenha permitido atualizações do Messenger, mas lembre-se que um usuário 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 usuário?

Se houver atividade no Messenger de um usuário 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 usuário. Para evitar efeitos indesejados na experiência do usuário, recomendamos que você escolha uma duração de sessão do cookie que corresponda ao tempo limite da sessão da sua aplicação.

Por que não exigimos que o payload completo seja assinado?

Permitimos que você envie atributos não assinados para suportar situações em que é necessário enviar dados de baixa fidelidade sobre o User, enquanto o User está realizando uma ação em sua aplicação. Se você não precisa dessa capacidade, pode atualizar todos os seus User Data Attributes para serem “protegidos contra atualizações do Messenger” e enviar apenas o payload assinado.

Como faço para gerenciar e rotacionar 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.

O que aconteceu com a Verificação de Identidade? Os JWTs substituem 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 façam upgrade 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 em Settings > Security > Messenger.

Autenticando users no Fin Messenger com JSON web tokens (JWTs)