Nonce WordPress

Nonce WordPress é um token de uso único, gerado pelo próprio core, que valida se uma requisição realmente partiu do usuário autenticado e não de um terceiro tentando se passar por ele. Aparece em formulários do wp-admin, em URLs de ações administrativas e em chamadas REST. É a defesa padrão do WordPress contra CSRF, Cross-Site Request Forgery, e protege ações como deletar posts, atualizar opções e ativar plugins.

O que é um nonce

O nome vem de “number used once”. Apesar do nome, no WordPress o nonce não é exatamente número e não é tecnicamente único: é uma string hash gerada a partir do ID do usuário, do timestamp atual e de uma ação específica. O ciclo de vida padrão é de 24 horas, dividido em duas janelas de 12 horas cada.

A função do nonce é responder a uma pergunta simples: a requisição que chegou ao servidor foi gerada por uma página real do site para um usuário logado, ou foi forjada por um atacante? Sem essa verificação, qualquer link clicado por um administrador autenticado poderia disparar ações silenciosas em nome dele.

Quem busca o que é nonce em fóruns de WordPress costuma estar tentando entender por que recebe “link expirou” ou “are you sure you want to do this?”. A resposta está sempre no nonce: ou ele expirou, ou foi enviado para a ação errada, ou simplesmente não existe na requisição.

O conceito de nonce não é exclusivo do WordPress. Aparece em OAuth, em criptografia simétrica, em protocolos de autenticação. No WordPress, a implementação é simplificada e usa o esquema clássico de hash baseado em chave secreta definida no wp-config.php.

Como nonces protegem o WordPress

O ataque que o nonce previne é o CSRF wordpress. Imagine que você está logado como administrador. Em outra aba, abre um link de um email malicioso. Esse link aponta para uma URL do seu próprio site que dispara a deleção de um post. Sem nonce, o WordPress aceita: a requisição vem com seu cookie de sessão válido, então parece legítima.

Com nonce, a história muda. Para deletar o post, a URL precisa conter o nonce correto, gerado a partir do seu ID de usuário e da ação específica de deleção. O atacante não tem como gerar esse nonce porque não tem acesso à chave secreta do site nem ao seu ID com timestamp atualizado.

Quando o WordPress recebe a requisição, recalcula o nonce esperado e compara com o enviado. Se baterem, a ação prossegue. Se não, retorna a tela “are you sure?”. É a mesma lógica usada na REST API WordPress, onde o cabeçalho X-WP-Nonce cumpre exatamente o mesmo papel.

Nonce não é autenticação

É comum confundir nonce com autenticação ou com proteção contra brute force. Não é nenhum dos dois. Nonce assume que o usuário já está autenticado e protege apenas contra requisições forjadas em nome dele. Para autenticação, o WordPress usa cookies. Para brute force, usa rate limiting e plugins de segurança.

Como implementar nonces no código

Em formulários do wp-admin, a função padrão é wp_nonce_field. Você passa o nome da ação e o nome do campo, e a função imprime um input hidden com o nonce gerado. No handler da action, você usa wp_verify_nonce ou check_admin_referer para validar antes de qualquer operação sensível.

Para URLs com parâmetros, use wp_nonce_url. Ela adiciona automaticamente o parâmetro _wpnonce à URL passada. No callback, o WordPress valida via check_admin_referer com a mesma ação. É o padrão para links de “deletar”, “ativar”, “aprovar” e similares no painel.

Em chamadas AJAX, o padrão é gerar o nonce com wp_create_nonce no PHP e passar via wp_localize_script para o JavaScript. O front-end envia o nonce no body da requisição, o handler valida com check_ajax_referer e processa. Sem isso, qualquer endpoint AJAX administrativo é uma porta aberta.

Em plugins que expõem novas ações administrativas, esse padrão precisa ser religioso. Cada handler que cria, atualiza ou deleta dado sensível valida nonce antes de qualquer query. Combine com sanitização de inputs e capability checks para fechar o ciclo de defesa.

Erros comuns com nonces

O erro mais comum é gerar o nonce com uma ação e validar com outra. wp_nonce_field(‘salvar_config’) no formulário e check_admin_referer(‘atualizar_config’) no handler nunca vão bater, porque o hash depende da string da ação. Sempre use a mesma ação dos dois lados.

O segundo erro é confiar em nonce sem capability check. Nonce só prova que a requisição veio do usuário autenticado, não que esse usuário tem permissão. Um Assinante autenticado pode ter um nonce válido para uma ação, mas não deveria poder executá-la. current_user_can é obrigatório como segunda camada.

Outro problema frequente é cachear páginas com nonces. Como o nonce expira em 12 a 24 horas, páginas em cache de longa duração entregam nonces velhos para visitantes. O resultado é “link expirou” em formulários públicos. A solução é excluir essas páginas do cache ou injetar o nonce via JavaScript depois do load.

Por fim, é comum ver plugins que usam nonces em endpoints que não precisam, e que esquecem nonce em endpoints críticos. A regra prática é simples: toda ação que muda estado, salva, deleta ou modifica precisa de nonce. Toda ação que apenas lê dado público pode dispensar.

Para times que estão construindo plugins customizados ou hardening em sites WordPress, a FULL Services entrega o AIOS (All-In-One Security) já licenciado e configurado dentro da stack profissional, com regras de firewall, hardening de wp-admin e proteção complementar contra CSRF que cobre o que nonce sozinho não resolve. Em vez de tratar segurança plugin a plugin, o site roda em uma camada validada em produção desde o começo.