Guia para a Autenticação da API REST do WordPress

Introdução à autenticação da API REST do WordPress

A interface API do WordPress, a API REST, é uma ferramenta poderosa que permite o acesso ao conteúdo e às funcionalidades do WordPress através de pedidos HTTP a partir de qualquer aplicação, seja uma aplicação móvel, um frontend em JavaScript, um serviço externo ou uma aplicação web totalmente independente. No entanto, embora a leitura de conteúdo público esteja normalmente disponível sem autenticação, criar, atualizar e eliminar conteúdo exige que o utilizador se autentique para que o WordPress saiba quem está a executar a ação e se tem as permissões necessárias.

O WordPress suporta vários métodos de autenticação para a API REST, e cada um tem as suas vantagens, desvantagens e cenários de utilização ideais. A escolha do método certo depende de quem acede à API (frontend no mesmo site, aplicação externa, aplicação móvel), de que nível de segurança é necessário e de quão complexa é a integração que pretende implementar. Neste guia, percorremos cada método em detalhe com exemplos práticos.

Autenticação por cookie com nonce

A autenticação por cookie é o método predefinido para pedidos que provêm do próprio site WordPress, normalmente de código JavaScript no painel de administração ou no frontend. Quando o utilizador está autenticado no WordPress, o navegador envia automaticamente um cookie com cada pedido e a API REST do WordPress utiliza-o para identificar o utilizador. No entanto, o cookie por si só não é suficiente, pois isso permitiria ataques CSRF em que um site malicioso poderia desencadear pedidos em nome do utilizador autenticado.

Como funciona o nonce

O WordPress utiliza o nonce (number used once) como uma camada adicional de proteção contra ataques CSRF. O nonce é um token de duração limitada que o WordPress gera para o utilizador autenticado e que deve ser enviado com cada pedido que altera dados (POST, PUT, DELETE). O código JavaScript obtém-no através da função wp_localize_script() ou da variável global wpApiSettings.nonce no painel de administração.

• Geração - wp_create_nonce('wp_rest') do lado do servidor
• Encaminhamento - wp_localize_script() para passar o nonce ao JavaScript
• Envio - cabeçalho X-WP-Nonce ou parâmetro de consulta _wpnonce
• Validade - o nonce expira após 24 horas (dois períodos de nonce do WordPress de 12h)
• Revalidação - para sessões de longa duração, solicite periodicamente um novo nonce através da API

A autenticação por cookie é ideal para código JavaScript executado no próprio site WordPress porque não exige qualquer configuração adicional além de passar corretamente o nonce. Não é adequada para aplicações externas porque estas não conseguem aceder ao cookie do WordPress. Tenha também em conta que o nonce expira e que sessões de longa duração exigem um mecanismo de renovação do token para que o utilizador não receba um erro 403 a meio do trabalho.

Application Passwords

As Application Passwords foram introduzidas no WordPress 5.6 como um método integrado para autenticar aplicações externas sem fornecer a palavra-passe principal do utilizador. Cada utilizador pode criar várias palavras-passe de aplicação com nomes descritivos (por exemplo, Mobile App, Zapier Integration, Custom Script) e cada uma pode ser revogada de forma independente sem afetar as outras nem a palavra-passe principal do utilizador.

Criação e utilização

A palavra-passe de aplicação é criada no painel de administração do WordPress em Utilizadores, Editar Utilizador, secção Application Passwords. Introduz o nome da aplicação e o WordPress gera uma palavra-passe de 24 caracteres agrupada em 4 grupos de 6 caracteres separados por espaço. Esta palavra-passe é utilizada para a autenticação HTTP Basic Authentication, em que o nome de utilizador e a palavra-passe de aplicação são enviados no cabeçalho Authorization codificados em formato base64.

Um pedido com Application Password tem o aspeto de uma HTTP Basic Auth padrão: o cabeçalho Authorization contém Basic seguido da cadeia codificada em base64 nome_utilizador:palavra_passe_aplicacao. Os espaços na palavra-passe são ignorados, por isso pode removê-los ou deixá-los. O WordPress reconhece automaticamente que se trata de uma Application Password e não da palavra-passe principal do utilizador e aplica as permissões adequadas.

Vantagens e limitações

• Simplicidade - funcionalidade integrada sem necessidade de plugins
• Controlo granular - cada aplicação tem a sua própria palavra-passe que pode ser revogada
• Registo - o WordPress regista a última utilização de cada palavra-passe de aplicação
• Limitação - funciona apenas através de HTTPS porque a Basic Auth envia as credenciais em cada pedido
• Limitação - não há granularidade de scope ou de permissões para além do papel do utilizador

As Application Passwords são uma excelente escolha para integrações server-to-server, ideais para ambientes de VPS hosting, scripts de automação e aplicações onde a simplicidade é mais importante do que o controlo de acesso granular. Utilize sempre HTTPS porque as credenciais são enviadas em cada pedido e, sem HTTPS, podem ser intercetadas. Para integrações de produção, crie um utilizador WordPress separado com as permissões mínimas necessárias em vez de usar uma conta de administrador.

OAuth 2.0

O OAuth 2.0 é uma norma da indústria para autorização utilizada pela Google, Facebook, GitHub e muitos outros serviços. O WordPress não tem suporte integrado para OAuth, mas está disponível através de plugins como o WP OAuth Server e o OAuth 2.0 Provider. O OAuth é ideal para cenários em que pretende permitir que aplicações de terceiros acedam à sua API do WordPress com um controlo preciso de permissões e sem partilhar as credenciais do utilizador.

Fluxo OAuth 2.0

O fluxo OAuth mais comum para aplicações web é o Authorization Code flow, composto por vários passos. A aplicação redireciona o utilizador para o endpoint authorize do WordPress, onde o utilizador aprova o acesso. O WordPress redireciona o utilizador de volta para a aplicação com um authorization code. A aplicação troca o código por um access token ao chamar o token endpoint. O access token é depois utilizado nos pedidos à API no cabeçalho Authorization Bearer.

• Authorization Code - o fluxo mais seguro para aplicações web com lado servidor
• Implicit - para aplicações SPA sem servidor (menos seguro, geralmente não recomendado)
• Client Credentials - para comunicação server-to-server sem contexto de utilizador
• PKCE - Proof Key for Code Exchange, melhora a segurança para aplicações móveis e SPA

O OAuth proporciona o mais alto nível de controlo e segurança, mas também é o mais complexo de implementar. Os access tokens têm duração limitada e os refresh tokens são utilizados para obter novos sem voltar a autorizar o utilizador. O parâmetro scope define quais as permissões que a aplicação solicita, dando ao utilizador transparência sobre o que a aplicação pode fazer com os seus dados.

JWT (JSON Web Tokens)

A autenticação JWT é uma alternativa popular para o acesso à API REST que utiliza tokens em vez de sessões. Um token JWT é uma cadeia assinada que contém informação sobre o utilizador e as permissões, enviada no cabeçalho Authorization de cada pedido. O WordPress não tem suporte integrado para JWT, mas está disponível através de plugins como o JWT Authentication for WP REST API e o Simple JWT Login.

Como funciona o JWT

O utilizador envia o nome de utilizador e a palavra-passe para o token endpoint (normalmente /wp-json/jwt-auth/v1/token) e recebe um token JWT como resposta. Este token é depois enviado no cabeçalho Authorization: Bearer de todos os pedidos à API. O servidor verifica a assinatura do token e extrai a informação do utilizador sem necessidade de consultar a base de dados, o que torna o JWT mais eficiente para APIs com cargas elevadas.

O token JWT é composto por três partes separadas por pontos: o header (algoritmo e tipo de token), o payload (dados do utilizador, tempo de expiração, emissor) e a signature (assinatura criptográfica que garante a integridade do token). O token pode ser descodificado do lado do cliente, mas não pode ser forjado sem a chave secreta conhecida apenas pelo servidor. Isto permite que o cliente leia a informação do utilizador a partir do token sem uma chamada adicional à API.

Vantagens do JWT

• Stateless - o servidor não armazena sessões, facilitando o escalonamento
• Self-contained - o token contém toda a informação necessária do utilizador
• Cross-domain - funciona com diferentes domínios sem os problemas de CORS associados aos cookies
• Aplicações móveis - ideal para aplicações móveis que não utilizam cookies
• Desempenho - a verificação do token não exige consulta à base de dados

Comparação dos métodos de autenticação

A escolha do método de autenticação depende do seu cenário específico. O cookie e o nonce são ideais para JavaScript no mesmo site porque não exigem configuração adicional. Consulte os nossos planos de WordPress hosting para um ambiente otimizado. As Application Passwords são as melhores para integrações server-to-server simples e scripts porque são integradas e fáceis de usar. O OAuth 2.0 é a escolha certa para aplicações de terceiros onde são necessários um controlo de acesso granular e a autorização do utilizador. O JWT é o ideal para aplicações móveis e frameworks SPA que comunicam com o WordPress como um headless CMS.

Recomendações de segurança

• Utilize sempre HTTPS - todos os métodos de autenticação exigem uma ligação encriptada
• Permissões mínimas - crie utilizadores apenas com as permissões necessárias para o acesso à API
• Rotação de tokens - implemente refresh tokens e uma curta expiração dos access tokens
• Rate limiting - limite o número de pedidos por utilizador para proteção contra ataques de força bruta
• Registo - registe todos os pedidos à API para auditoria e deteção de atividades maliciosas
• Configuração de CORS - restrinja o acesso à API apenas a partir de domínios permitidos

Para aplicações de produção, recomendamos uma combinação de vários métodos em que cada um cobre um cenário diferente. Autenticação por cookie para interações no painel de administração e no frontend, Application Passwords para scripts internos e automação, JWT para aplicações móveis e OAuth para integrações de terceiros. Reveja regularmente os tokens e as palavras-passe de aplicação ativos e revogue os que já não estão em uso, pois cada token ativo é um potencial vetor de ataque.