Whitelist controla quem pode conectar a um servidor que você administra. Ela é útil para testes fechados, eventos privados, manutenção ou uma comunidade por convite. Para funcionar bem, precisa de processo claro de convite e remoção, operadores responsáveis e um caminho de recuperação quando um membro legítimo fica de fora.

O Paper recomenda usar comandos para gerenciar a lista em vez de editar diretamente o arquivo JSON. A opção white-list ativa a regra, enquanto configurações adicionais determinam quando aplicá-la. Confirme o comportamento na versão instalada e evite mudar ao mesmo tempo a autenticação da rede.

Planeje a regra de acesso

Decida se o servidor ficará sempre restrito ou somente durante a manutenção. Defina quem aprova convites, quais informações são necessárias para identificar a conta e como pedidos são tratados. Não use uma whitelist como substituta para permissões internas ou proteção de backend numa rede com proxy.

Em comunidades grandes, estabeleça uma política para nomes divergentes, mudanças de conta e membros ausentes. Evite pedir dados privados além do necessário. Registre data do convite, responsável e motivo em sistema interno com acesso restrito, e revise a lista conforme as regras de privacidade aplicáveis.

Habilite pelo mecanismo suportado

Ative whitelist usando os comandos do console ou os comandos de administração documentados. Confira estado da lista e modo de aplicação. Algumas opções permitem que pessoas fora dela sejam removidas quando a regra muda; compreenda esse efeito antes de habilitar numa sessão com jogadores conectados.

Não edite whitelist.json manualmente. A referência do Paper chama esse arquivo de dado do servidor, não uma configuração, e recomenda usar o comando /whitelist. Edição JSON pode introduzir UUID inválido, vírgula extra ou dados inconsistentes que o jogo poderia gerenciar corretamente.

Convide e confirme a conta correta

Use o comando para adicionar a conta conforme mecanismo oficial do servidor. Para autenticação online, o nome pode ser resolvido para UUID; confirme o resultado no feedback e teste a entrada com a conta do próprio jogador. Não assuma que uma conta homônima ou uma mudança de nome corresponde a um UUID diferente.

Em rede proxy, conheça o caminho de autenticação e forwarding antes de testar. A whitelist do backend pode usar identidade recebida pelo proxy. Alterações no modo online ou no encaminhamento podem fazer uma conta que antes entrava aparecer como outra. Siga a documentação da topologia e nunca desabilite autenticação sem as proteções combinadas.

Crie uma rotina de remoção

Quando alguém sair do projeto ou perder acesso, remova a conta pelo comando correspondente e confirme a mudança na lista. Se a pessoa estiver conectada, saiba se é necessário expulsá-la explicitamente; gerenciar autorização futura e encerrar sessão atual são operações distintas.

Revise contas antigas periodicamente e diferencie membro inativo de banimento disciplinar. Whitelist define admissão, enquanto banimento tem outro objetivo e pode usar histórico ou regras próprias. Evite usar os dois mecanismos de forma contraditória; comunique decisão com critérios conhecidos.

Teste sem bloquear a equipe

Antes de ligar a restrição em produção, mantenha uma conexão de console confiável e tenha pelo menos um operador autorizado. Teste uma conta listada e outra não listada em horário controlado. Confirme código e mensagem que o jogador vê e o evento correspondente no log.

Se pretende fechar acesso ao público durante manutenção, avise a equipe e confirme se administradores e serviços de monitoramento ainda conseguem entrar. Um proxy ou plugin de login pode alterar o fluxo. Faça a verificação no ponto de entrada público e em qualquer endereço alternativo existente.

Evite erros comuns de identidade

Um jogador adicionado com grafia errada pode não ser reconhecido. Copy/paste de nome exibido ou de UUID ajuda a reduzir erro, desde que obtido de fonte confiável. Se conta funciona em um backend e falha em outro, compare modo de autenticação, forwarding e configuração de whitelist antes de remover ou adicionar repetidamente.

Não conceda OP para resolver uma whitelist. Operador tem poderes muito maiores que acesso ao servidor e não corrige uma identidade inconsistente. Inspecione entradas duplicadas, consulte console e revise o fluxo de conta. Se o acesso expõe outro backend, feche a origem primeiro conforme procedimento de segurança.

Tenha caminho de recuperação

Guarde contato dos operadores e acesso ao painel para uma falha de lista. Se ninguém consegue entrar, use console para consultar e corrigir autorização sem editar arquivos fora do jogo. Teste essa recuperação numa cópia quando alterar autenticação ou arquitetura.

Documente comando de ativação, estado atual, responsável e critério para reabrir. Em mudança de evento, desative a regra ou remova participantes somente após confirmar que nenhum jogador legítimo ficará conectado a um fluxo alternativo. Reavalie a lista após cada teste e mantenha os registros necessários.

Consulte os próximos passos de segurança e whitelist do Paper, a referência de server.properties e a documentação do arquivo whitelist.json. Use comandos suportados e teste uma conta comum depois da mudança.

Trate contas Bedrock e integrações do proxy

Uma rede com Geyser, Floodgate ou autenticação conectada pode representar nome e UUID conforme a configuração de identidade. Teste convite e remoção com cada tipo de conta aceito e use o fluxo oficial do plugin. Não acrescente manualmente uma entrada JSON para corrigir conta que recebeu uma identidade diferente no backend.

Se whitelist funciona em Paper direto mas falha atrás do proxy, compare encaminhamento e modo de autenticação em homologação. Mantenha o listener administrativo acessível para recuperação e faça teste de uma conta convidada e outra não convidada em cada rota de entrada disponível.

Inclua a equipe na revisão de acesso

Explique como um convite é aprovado e a quem recorrer em caso de conta trocada ou nome alterado. Recolha somente o identificador necessário para localizar o perfil. Ao encerrar período de teste, remova a entrada de quem não deveria permanecer e confirme que a conta ainda conectada foi encerrada se a regra exigir expulsão imediata.

Registre a revisão periódica

Defina uma frequência para conferir se a whitelist ainda corresponde aos membros ativos e à política de acesso. Registre quem revisou, quantas entradas foram alteradas e como pedidos pendentes foram tratados, sem expor nomes publicamente. Uma revisão simples após encerramento de evento ou mudança de equipe evita que permissões temporárias persistam por meses sem responsável.

Fontes e referências

Documentação consultada em 2026-10-08. Os exemplos precisam ser conferidos na versão instalada; este guia não afirma que a configuração foi testada no seu ambiente.