A opção enforce-whitelist em server.properties faz o servidor expulsar jogadores que não estão na lista permitida. A lista é mantida em whitelist.json e pode ser administrada pelo comando /whitelist. Ativar enforcement transforma a lista em controle de acesso efetivo; sem um processo de convite, jogadores legítimos podem ficar de fora.

Uma whitelist é útil para testes privados, comunidades por convite, períodos de manutenção e servidores de equipe. Ela não substitui autenticação de contas nem proteção do proxy e precisa ser aplicada a cada backend relevante da rede.

Prepare lista antes de ativar

Cadastre contas autorizadas antes de exigir whitelist. Use comandos oficiais no console ou ferramenta administrativa documentada; Paper não recomenda editar diretamente o JSON de dados. Confirme o nome de conta e UUID corretos, especialmente depois de troca de nome, migração entre online/offline mode ou configuração de proxy.

Faça inventário de quem precisa entrar: equipe, testadores, construtores, bots e serviços. Se uma instância usa modo de autenticação diferente, a resolução de UUID pode variar. Teste com uma conta real autorizada e outra conta não autorizada em staging antes de fechar produção.

Mantenha pelo menos um operador autorizado e acesso seguro ao console do painel. Se a única conta de gestão fica fora da lista, a equipe pode perder acesso remoto pela própria política. Planeje emergência e recuperação sem abrir o servidor publicamente.

Entenda quem pode contornar

Operadores podem ter privilégios adicionais e certos comandos ou opções permitem contornar restrições. Revise `ops.json` e grupos de permissão. Não trate whitelist como substituto para menor privilégio ou controle do painel.

Em rede Velocity, a lista pode estar no proxy, nos backends ou nos dois, conforme arquitetura e plugins. Defina uma fonte de verdade e teste troca de servidor. Um jogador aceito no lobby pode ser rejeitado no survival se as listas não estão sincronizadas.

Se plugins de autenticação ou manutenção controlam acesso, entenda sua relação com whitelist. Duas camadas podem resultar em mensagens diferentes ou deixar um backend exposto se apenas a entrada principal estiver protegida.

Use um processo de convite e remoção

Defina quem pode aprovar, como validar o nome, qual é o prazo de atendimento e como revogar acesso. Confirme conta com o jogador por canal confiável, sem pedir senha. Registre motivo e responsável, mas não guarde dados desnecessários.

Ao remover alguém, pense se a conta pode estar online ou conectada a outro backend. Execute o comando apropriado e confirme a desconexão conforme política. Se acesso temporário for concedido para evento, registre data de expiração e revise depois.

Automação de convites deve validar origem e autenticar remetente. Um bot que adiciona qualquer nome enviado em canal público pode transformar a whitelist em controle inútil. Proteja credenciais e teste comportamento em caso de duplicação ou erro de API.

Ative sem bloquear a equipe

Faça cópia de server.properties e da lista atual. Adicione primeiro todos os operadores, equipe e contas técnicas necessárias; valide UUIDs e modo de autenticação. Depois ative enforce-whitelist=true, reinicie se necessário e teste acesso autorizado e negado.

Realize o teste a partir da rota normal do jogador, incluindo proxy. Confirme mensagem de recusa, logs, permanência em lobby e troca para outros servidores. Mantenha a console disponível para corrigir lista durante a janela de implantação.

Se alguém essencial é bloqueado, use console do painel para corrigir a lista, não desligue firewall ou autenticação. Preserve mensagem e logs para determinar se o problema é nome, UUID, sincronização ou outra camada.

Planeje manutenção e eventos

Durante beta fechado, a whitelist pode controlar vagas e facilitar observação. Publique instrução para solicitar acesso e defina critério de seleção transparente. Quando abrir ao público, planeje desativar enforcement no momento certo e confirme que backend continua protegido pelo proxy.

Para manutenção, uma whitelist temporária pode limitar quem entra, mas jogadores presentes podem permanecer conectados. Comunique janela e método de acesso dos testadores. Depois, restaure valor e confira que não deixou a rede inacessível aos membros.

Guarde snapshot da whitelist antes de grandes alterações e compare depois. Um backup do JSON deve ser consistente com a instância e protegido como outros dados de jogadores. Não publique lista de nomes sem razão.

Proteja a fonte de dados e faça auditoria

Restrinja escrita em `whitelist.json`, `ops.json` e arquivos de banimento às contas de servidor e operadores autorizados. Use backup e monitoramento de mudanças. Uma pessoa não autorizada que altera lista pode remover controles ou se conceder acesso privilegiado.

Audite periodicamente contas antigas, duplicadas, operadores e permissões de bypass. Remova acessos temporários expirados. Verifique se nome e UUID correspondem à conta esperada, especialmente em ambientes migrados ou com integração Bedrock.

Se alguém entra sem estar autorizado, preserve logs, confira operação do proxy e do backend, e revise plugins que alteram login. Não assuma que o arquivo de whitelist sozinho explica o caminho. Isole o incidente e corrija a camada que permitiu a entrada.

Documente e valide após atualizações

Registre valor de enforcement, fonte de verdade da lista, administradores, fluxo de convite e procedimento de emergência. Depois de atualizar Paper, proxy, plugin de login ou modo de autenticação, teste as contas essenciais e a rejeição correta.

A lista permitida é um controle simples quando a equipe sabe administrá-la e manter uma rota segura ao console. O processo evita bloqueios acidentais, convites inseguros e inconsistências entre mundos.

Diagnostique recusas de jogadores cadastrados

Se um usuário autorizado recebe “not whitelisted”, confirme se conectou à instância correta e se o perfil está na lista daquela instância. Em redes com vários servidores, a mensagem pode vir de um backend diferente do lobby. Compare nomes, UUID, modo de autenticação, log do proxy e horário.

Troca de nome e alteração entre online-mode e offline-mode podem resultar em UUID diferente. Não edite manualmente o JSON como primeira tentativa; use comandos administrativos e documentação da versão. Faça backup antes de migração de identidade e valide contas de teste para evitar duplicatas.

Se o jogador aparece cadastrado e continua recusado, verifique plugins de login, sincronização de whitelist e cache de usuário. Teste em staging com uma conta fictícia e mantenha o acesso por console seguro para corrigir sem abrir o servidor inteiro.

Automatize sincronização com cuidado

Uma rede pode ter várias listas que precisam permanecer consistentes. Escolha fonte autoritativa e defina como as alterações são propagadas. Se sincronização ocorre por plugin ou script, monitore falhas, duplicatas e atraso; um estado parcialmente atualizado pode aceitar jogador num mundo e rejeitá-lo no próximo.

Proteja tokens de API e bot, limite quais canais ou pessoas podem gerar convite e registre responsável. A automação deve falhar fechada sem apagar os autorizados existentes. Faça backup antes de substituir lista inteira e teste cenários de rollback.

Quando um servidor fica offline para evento privado, confirme que proxy também aplica a regra ou que backend não pode ser acessado diretamente. Enforcement em Paper sem firewall não é uma barreira contra acesso ao backend se ele está exposto e a autenticação é alterada para proxy.

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.