> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://help.drimify.com/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# Garantir o acesso ao jogo com JWT Autenticação

# 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

```json
{
  "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.