WordPress REST API - Basic Auth

Um plugin WordPress que força a autenticação Basic Auth em todos os endpoints da REST API.

Índice

• Características
• Requisitos
• Instalação
• Como Usar
• Painel de Administração
• Configuração
• Segurança
• Desenvolvimento
• Licença

Características

• Autenticação obrigatória: Força Basic Authentication em todos os endpoints da REST API
• Múltiplos métodos de autenticação: Suporte a username/password, email/password e Application Passwords
• Painel de administração: Interface gráfica em Configurações › REST Basic Auth para gerenciar endpoints públicos, proxies confiáveis e visualizar logs de falha
• Log de segurança persistente: Até 50 tentativas de autenticação falhadas armazenadas no banco de dados, visíveis diretamente no painel
• Detecção de HTTPS: Alerta no painel administrativo se o site não está usando HTTPS
• Suporte a proxies reversos: Detecção de IP real por trás de CDNs/Load Balancers (Cloudflare, Nginx, etc.)
• Endpoints públicos: Configuráveis via painel admin ou via filtro PHP — sem necessidade de editar código
• Respostas de erro padronizadas: Mensagens de erro claras e consistentes (incluindo headers RFC 7235)
• Compatibilidade total: Funciona com todas as versões do WordPress 5.0+
• Código limpo: Arquitetura moderna com namespaces PSR-4
• Internacionalização: Pronto para tradução
• Extensível via filtros: Endpoints públicos, proxies confiáveis e cookie auth configuráveis

Requisitos

• WordPress: 5.0 ou superior
• PHP: 7.4 ou superior
• Servidor web: Apache, Nginx ou similar com suporte a cabeçalhos HTTP

Instalação

Instalação Manual

1. Faça o download do plugin
2. Extraia os arquivos para /wp-content/plugins/wp-rest-basic-auth/
3. Ative o plugin no painel administrativo do WordPress
4. O plugin começará a funcionar imediatamente

Verificação da Instalação

Após a ativação, faça uma requisição para qualquer endpoint da REST API sem autenticação:

curl -X GET https://seusite.com/wp-json/wp/v2/posts

Você deve receber uma resposta de erro 401 solicitando autenticação.

Como Usar

Autenticação Básica

Para acessar qualquer endpoint da REST API, inclua o cabeçalho Authorization com credenciais válidas:

curl -X GET https://seusite.com/wp-json/wp/v2/posts \
  -H "Authorization: Basic $(echo -n 'username:password' | base64)"

Métodos de Autenticação Suportados

1. Username e Password:

   Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

2. Email e Password:

   Authorization: Basic ZW1haWxAdGVzdC5jb206cGFzc3dvcmQ=

3. Application Passwords (WordPress 5.6+):

   Authorization: Basic dXNlcm5hbWU6YXBwX3Bhc3N3b3Jk

Painel de Administração

Acesse Configurações › REST Basic Auth no painel do WordPress para visualizar e gerenciar o plugin sem editar código.

Cards de Status

Card	Descrição
HTTPS / SSL	Indica se o site usa HTTPS
Falhas registradas	Total de tentativas com falha armazenadas (máx. 50)
IPs únicos (24 h)	Quantidade de IPs distintos que falharam nas últimas 24 horas
Endpoints públicos	Total de endpoints configurados sem autenticação
Cookie auth (admin)	Estado do filtro wp_rest_basic_auth_allow_cookie_auth

Endpoints Públicos

A tabela exibe todos os endpoints públicos ativos, distinguindo a origem de cada um:

• Painel (azul) — adicionado pela interface; pode ser removido pelo painel
• Código (filtro) (laranja) — registrado via filtro PHP; somente leitura

Use o formulário na parte inferior da seção para adicionar novos endpoints. O caminho deve começar com / e não pode conter .. ou //.

Proxies Confiáveis

Adicione os endereços IPv4 dos seus proxies reversos (Cloudflare, Nginx, Load Balancer) para que o plugin identifique corretamente o IP real dos clientes nos logs.

Nota: O painel aceita apenas endereços IPv4. Para IPv6 ou ranges CIDR, utilize o filtro PHP wp_rest_basic_auth_trusted_proxies.

Log de Tentativas com Falha

Exibe as últimas 50 tentativas de autenticação falhadas com data/hora, IP do cliente e URI. O botão Limpar logs remove todos os registros via AJAX sem recarregar a página.

Configuração

O plugin funciona sem necessidade de configuração adicional. Após a ativação:

• ✅ Remove a autenticação por cookies da REST API para requisições externas
• ✅ Remove a autenticação por Application Passwords padrão
• ✅ Força a autenticação Basic Auth em todos os endpoints
• ✅ Retorna erros padronizados para requisições não autenticadas
• ✅ Exibe alerta no admin se HTTPS não estiver ativo
• ✅ Registra tentativas falhadas no banco de dados e no error log

Filtros Disponíveis

O plugin oferece filtros para personalizar o comportamento sem alterar o código-fonte:

Endpoints Públicos

Permita que endpoints específicos sejam acessados sem autenticação:

add_filter('wp_rest_basic_auth_public_endpoints', function ($endpoints) {
    $endpoints[] = '/wp-json/wp/v2/posts';
    $endpoints[] = '/wp-json/custom/v1/public';
    return $endpoints;
});

Endpoints adicionados via filtro aparecem como Código (filtro) no painel e não podem ser removidos pela interface — apenas pelo código.

Proxies Confiáveis

Configure IPs de proxies reversos para detecção correta do IP do cliente:

add_filter('wp_rest_basic_auth_trusted_proxies', function ($proxies) {
    $proxies[] = '172.16.0.1';      // IP do load balancer
    $proxies[] = '103.21.244.0';    // IP de entrada do Cloudflare
    return $proxies;
});

Proxies adicionados via filtro aparecem como Código (filtro) no painel e não podem ser removidos pela interface.

Cookie Auth para Requisições Internas

Por padrão, o plugin remove a autenticação por cookie da REST API. Para reativá-la (útil para requisições feitas pelo próprio painel do WordPress):

add_filter('wp_rest_basic_auth_allow_cookie_auth', '__return_true');

Segurança

Considerações Importantes

⚠️ HTTPS Obrigatório: Sempre use HTTPS em produção. A autenticação Basic Auth transmite credenciais em Base64, que é facilmente decodificável. O plugin exibe um alerta no painel administrativo se HTTPS não estiver ativo.

⚠️ Application Passwords: Recomendado usar Application Passwords em vez de senhas principais para APIs.

Criando Application Passwords

1. Acesse o perfil do usuário no WordPress
2. Role até a seção "Application Passwords"
3. Digite um nome para a aplicação
4. Clique em "Add New Application Password"
5. Use a senha gerada nas requisições da API

Mensagens de Erro

O plugin retorna mensagens específicas para diferentes cenários:

Código	HTTP Status	Descrição
missing_authorization	401	Cabeçalho Authorization ausente
invalid_auth_method	401	Método de autenticação não é Basic Auth
invalid_credentials	401	Credenciais inválidas

Respostas 401 incluem o header WWW-Authenticate: Basic realm="..." conforme RFC 7235.

Requisições HTTP OPTIONS (preflight CORS) são permitidas sem autenticação.

Logging

Todas as tentativas de autenticação falhadas são:

1. Armazenadas no banco de dados (wp_options) — visíveis no painel em Configurações › REST Basic Auth, com data/hora, IP e URI (máximo de 50 entradas, as mais antigas são descartadas).
2. Registradas no error log do PHP/WordPress com o formato:

[WP REST Basic Auth] Failed authentication attempt from IP: x.x.x.x for URI: /wp-json/...

Dados Armazenados no Banco

O plugin cria as seguintes chaves em wp_options:

Chave	Conteúdo
wp_rest_basic_auth_failed_attempts	Array com as últimas 50 tentativas falhadas
wp_rest_basic_auth_saved_endpoints	Endpoints públicos adicionados via painel
wp_rest_basic_auth_saved_proxies	IPs de proxies confiáveis adicionados via painel

Desenvolvimento

Estrutura do Projeto

wp-rest-basic-auth/
├── wp-rest-basic-auth.php         # Arquivo principal do plugin
└── src/
    ├── Admin/
    │   ├── AdminPage.php          # Página de administração (CRUD endpoints/proxies, AJAX handlers)
    │   ├── StatsCollector.php     # Persistência de tentativas falhadas no banco de dados
    │   └── views/
    │       └── dashboard.php      # Template HTML do painel
    ├── Auth/
    │   ├── AuthHandler.php        # Manipulador de autenticação
    │   └── BasicAuthenticator.php # Classe de autenticação
    ├── Contracts/
    │   └── AuthenticatorInterface.php # Interface de autenticação
    ├── Core/
    │   ├── Autoloader.php         # Autoloader PSR-4
    │   └── Plugin.php             # Classe principal do plugin
    ├── Http/
    │   └── ErrorResponse.php      # Respostas de erro padronizadas
    └── Utils/
        └── RequestHelper.php      # Utilitários para requisições HTTP

Licença

Este plugin é licenciado sob a GPL v2 ou posterior. Veja o arquivo LICENSE para mais detalhes.

---

Contribuindo

Contribuições são bem-vindas! Por favor:

1. Faça fork do projeto
2. Crie uma branch para sua feature (git checkout -b feature/AmazingFeature)
3. Commit suas mudanças (git commit -m 'Add some AmazingFeature')
4. Push para a branch (git push origin feature/AmazingFeature)
5. Abra um Pull Request