Neste artigo vamos te mostrar como configurar a autenticação por Token (JWT) para que usuários de plataformas externas sejam autenticados automaticamente na sua loja.
Como funciona
A integração permite o acesso de usuários por meio de tokens JWT (parâmetros seguros) enviados de um recurso externo para a loja. O sistema faz login automaticamente nos usuários que já existem na plataforma, ou cria uma nova conta caso o usuário ainda não esteja cadastrado.
A autenticação é feita pela rota /auth/token, que busca o parâmetro external-auth-token em query strings, cookies ou headers. Esse parâmetro é um JWT assinado com uma chave compartilhada usando o algoritmo HS256.
Passo 1: Pré-requisitos
Entre em contato com [email protected] informando:
- redirect_url: URL para redirecionamento caso o login ou cadastro falhe
- jti: Chave compartilhada para assinar os tokens
- issuer: Identificador do assinante do token (slug ou nome da loja)
Passo 2: Gerar o Token JWT
Com as credenciais fornecidas pelo suporte, você deverá gerar um JWT com os seguintes campos:
| Campo | Descrição |
|---|---|
iss | Slug que identifica o assinante do token (use o issuer dos pré-requisitos) |
jti | ID único do token em formato UUID V4 |
exp | Timestamp de expiração (60 segundos no futuro, em UTC) |
aud | Deve ser a string "farfalla" |
sub | Deve ser a string "usuario" |
intended_url | URL de destino após a autenticação |
user.uuid | Identificador único do usuário (obrigatório) |
user.email | E-mail do usuário (opcional) |
user.picture_url | URL da foto de perfil do usuário (opcional) |
user.accept_terms_and_policies | Aceite automático dos termos e políticas (opcional, boolean) |
|| O campo jti deve ser único para cada token gerado. Use um UUID V4 diferente a cada requisição.
Ferramentas úteis
- jwt.io — para gerar e validar tokens JWT
- timestampgenerator.com — para gerar timestamps Unix
- datatracker.ietf.org — especificação oficial do JWT
Como o link de autenticação funciona
O cliente deve construir um link na sua plataforma apontando para:
https://[dominio-da-sua-loja]/auth/token?external-auth-token=[SEU_JWT_AQUI]
Quando o usuário clica nesse link, a plataforma valida o token e faz o login automaticamente, redirecionando para a intended_url definida no payload.
Esperamos que este tutorial tenha sido simples para você. Se tiver dúvidas, escreva para [email protected].