Assegurar Acesso ao Jogo com JWT Autenticação

JWT Autenticação permite transmitir informações do jogador para a sua experiência Drimify de forma segura e controlar quem pode aceder a esta. Em vez de passar dados do jogador em parâmetros de consulta simples — que qualquer pessoa pode falsificar — o seu sistema emite um JSON Web Token (JWT) assinado. A Drimify verifica a assinatura utilizando o seu segredo partilhado, garantindo que as afirmações sobre a identidade do jogador são de confiança sem necessidade de uma chamada de servidor para servidor.

Isto é ideal para programas de fidelização, portais de membros e quaisquer cenários onde o jogo está embutido num ambiente autenticado e é necessário saber com fiabilidade quem está a jogar.

Como funciona

1. Cria uma Configuração JWT na sua conta Drimify (algoritmo + segredo).
2. Ativa a Autenticação JWT na sua aplicação e seleciona essa configuração.
3. O seu sistema gera um token assinado contendo as informações do jogador e passa-o ao abrir o jogo.
4. A Drimify verifica a assinatura e validade do token, lê as alegações mapeadas, e permite a entrada do jogador. Tokens inválidos ou em falta são bloqueados com um ecrã de erro personalizável.

Etapa 1 — Criar uma Configuração JWT

Vá a Minha Conta → Configurações JWT (logo abaixo de Integrações) e clique para adicionar uma nova configuração:

• Nome: Um rótulo para a sua própria referência.
• Algoritmo: O algoritmo de assinatura que o seu sistema utiliza. Suportados: HS256, HS384, HS512 (HMAC, segredo partilhado) e ES256, ES384 (ECDSA).
• Segredo: O segredo partilhado usado para verificar a assinatura do token. Por segurança, os segredos HMAC devem ter um comprimento mínimo: 32 caracteres para HS256, 48 para HS384, 64 para HS512. O segredo é mascarado após ser guardado.
• Espaços de Trabalho: Selecionar quais espaços de trabalho podem usar esta configuração. Uma aplicação só pode usar configurações disponíveis no seu espaço de trabalho.

Mapeamento de Campo (nomes de claims)

Por padrão, a Drimify lê nomes de claims padrão do seu token. Se o emissor do seu token usar nomes de claims diferentes (por exemplo, user_email em vez de email), use a secção de mapeamento de campo para mapear cada nome de claim do seu token para o parâmetro correspondente do jogo Drimify.

O mapeamento de campo funciona como uma lista permitida: apenas os campos que configurar são lidos do token. Cada campo da Drimify pode ser mapeado uma vez (sem duplicados).

Etapa 2 — Ativar autenticação JWT na sua aplicação

No seu editor de aplicativos, abra a etapa de Configurações e ative Habilitar Autenticação JWT. Em seguida:

• Selecionar a configuração JWT para utilizar (apenas as configurações disponíveis no espaço de trabalho da aplicação são listadas — se não existir nenhuma, um link leva-o para Configurações JWT).
• Opcionalmente, defina um título e descrição de erro personalizados, mostrados aos jogadores quando o acesso é negado (token em falta ou inválido).

Etapa 3 — Passar o token ao abrir o jogo

O seu sistema pode entregar o token de três formas (se várias estiverem presentes, esta é também a ordem de precedência):

1. Cabeçalho Bearer — Authorization: Bearer <token> — recomendado para produção, já que o token nunca aparece em URLs, registos ou histórico do navegador.
2. String de consulta — https://your-game-url?jwt=<token> — conveniente para testes, mas tokens em URLs podem ser expostos através de registos e histórico do navegador.
3. Dados POST — um campo de formulário jwt=<token>.

Requisitos do Token

• O token deve ser assinado com o algoritmo e segredo definidos na sua Configuração JWT.
• Inclua uma claim exp (expiração) e mantenha as durações do token curtas — tokens expirados são rejeitados. É aplicada uma pequena tolerância de desvio de tempo, para que pequenas diferenças de relógio entre servidores não causem falhas.
• As claims devem conter os campos do jogador que você mapeou na configuração (por exemplo, email, id único, nome de usuário, número de telefone).

Exemplo de carga útil

{
  "sub": "user-123",
  "email": "player@example.com",
  "iat": 1753257600,
  "exp": 1753261200
}

Pode gerar tokens de teste em jwt.io colando o seu segredo no campo de verificação da assinatura.## Comportamento de segurança a ter em atenção

• Parâmetros de consulta não substituem dados dos jogadores. Quando a Autenticação JWT está ativada, as informações dos jogadores vêm exclusivamente do token verificado — valores de query-string comuns são ignorados. Isto impede que alguém contorne o token editando o URL.
• Limites de participação são aplicados a partir do token. Se a sua aplicação limita jogadas por email ou número de telefone, a reivindicação correspondente deve estar presente no token; caso contrário, o acesso é negado. Valores de email ou telefone inválidos também são rejeitados, por isso os limites não podem ser ultrapassados com dados malformados.
• Configurações em uso não podem ser eliminadas. Uma Configuração JWT que ainda está referenciada por uma aplicação deve ser desassociada antes de poder ser removida.
• Mantenha o seu segredo seguro. Quem tiver o segredo pode emitir tokens válidos. Se um segredo for comprometido, atualize-o na configuração — note que isto imediatamente invalida todos os tokens assinados com o segredo antigo.

Resolução de problemas

• Jogadores veem a tela de erro de acesso: Verifique se o token está assinado com o algoritmo e segredo corretos, não expirou e está a ser transmitido por um dos três métodos suportados.
• Dados dos jogadores não aparecem: Verifique o mapeamento de campo — apenas os claims mapeados são lidos do token.
• Configuração não listada nas definições da aplicação: Certifique-se de que a configuração está ativada para o espaço de trabalho da aplicação.

Actualizado em: 24/07/2026