Como Configurar a Autenticação Apache htpasswd no Ubuntu

A autenticação `htpasswd` do Apache fornece Autenticação Básica HTTP — um mecanismo de controlo de acesso do lado do servidor que solicita a qualquer pedido do navegador um prompt de nome de utilizador/palavra-passe antes de servir conteúdo. Não requer nenhum código na camada de aplicação, opera inteiramente dentro do sistema de módulos do Apache e é aplicada ao nível do servidor web antes de qualquer lógica de backend PHP, Python ou Node.js ser executada.

Isto torna-o o método mais rápido e fiável para proteger ambientes de staging, painéis de administração internos, builds de desenvolvimento e qualquer diretório que deva estar oculto da internet pública sem implementar um fornecedor de identidade completo.

Quando o htpasswd É a Ferramenta Certa — e Quando Não É

Antes de tocar num único comando, compreenda o modelo de ameaça. A Autenticação Básica HTTP transmite credenciais como uma string codificada em Base64 no cabeçalho `Authorization`. Base64 não é encriptação — é trivialmente reversível. Isto significa que a autenticação htpasswd só é segura quando implementada sobre HTTPS. Sem TLS, as credenciais ficam expostas em texto simples a qualquer observador da rede.

Casos de utilização adequados:

• Ambientes de staging e pré-produção
• Ferramentas e dashboards internos de desenvolvimento
• Restrição temporária de um site durante manutenção
• Adição de uma camada de autenticação secundária à frente de uma aplicação com o seu próprio login
• Proteção do `wp-admin` ou `xmlrpc.php` do WordPress ao nível do servidor

Casos de utilização inadequados:

• Autenticação primária para aplicações públicas que processam dados sensíveis de utilizadores
• Ambientes onde a rotação de credenciais deve ser auditada e registada
• Sistemas multi-tenant que requerem controlo de acesso baseado em funções

Se o seu caso de utilização envolve contas de utilizadores em produção, considere OAuth2, LDAP ou gestão de sessões ao nível da aplicação.

Pré-requisitos

• Um servidor Ubuntu 20.04, 22.04 ou 24.04 com acesso root ou `sudo`
• Apache 2.4 instalado ou instalável via `apt`
• Um domínio registado com DNS apontando para o seu servidor (fortemente recomendado para SSL)
• Familiaridade básica com a linha de comandos Linux e editores de texto

Se está a começar do zero, um ambiente de VPS Hosting oferece-lhe acesso root completo e uma imagem Ubuntu limpa — a base ideal para esta configuração.

Passo 1: Instalar o Apache2

Se o Apache ainda não estiver instalado, atualize o índice de pacotes e instale-o:

“`bash

sudo apt update && sudo apt install apache2 -y

“`

Verifique a instalação e confirme que o serviço está em execução:

“`bash

sudo systemctl status apache2

apache2 -v

“`

Ative o Apache para iniciar automaticamente no arranque:

“`bash

sudo systemctl enable apache2

“`

O diretório raiz de documentos padrão do Apache é `/var/www/html`. A configuração principal do site encontra-se em `/etc/apache2/sites-available/000-default.conf`.

Passo 2: Instalar o Pacote apache2-utils

O binário `htpasswd` faz parte do pacote `apache2-utils`. Na maioria das instalações Ubuntu este pacote é instalado juntamente com o Apache, mas confirme explicitamente a sua presença:

“`bash

which htpasswd

“`

Se o comando não retornar nada, instale o pacote:

“`bash

sudo apt install apache2-utils -y

“`

O pacote `apache2-utils` também fornece `htdigest` (para Autenticação Digest), `ab` (Apache Bench para testes de carga) e `htdbm` (para ficheiros de palavras-passe em formato DBM). Para a maioria dos cenários, `htpasswd` com o hashing padrão bcrypt ou MD5 é suficiente.

Passo 3: Criar o Ficheiro .htpasswd e Adicionar Utilizadores

Escolher um Algoritmo de Hashing de Palavras-passe

Este é um detalhe que a documentação original quase universalmente omite. O utilitário `htpasswd` suporta múltiplos esquemas de hashing, e a escolha tem implicações reais de segurança:

Utilize sempre bcrypt para novos ficheiros `.htpasswd`:

“`bash

sudo htpasswd -cB /etc/apache2/.htpasswd your_username

“`

Explicação das flags:

• `-c` — Cria um novo ficheiro. Aviso crítico: Se o ficheiro já existir, `-c` substitui-o silenciosamente, eliminando todos os utilizadores existentes. Utilize `-c` apenas uma vez, ao criar o ficheiro pela primeira vez.
• `-B` — Força o hashing bcrypt
• `/etc/apache2/.htpasswd` — O caminho do ficheiro de destino, intencionalmente fora do diretório raiz web
• `your_username` — Substitua pelo nome de utilizador real

Será solicitado que introduza e confirme a palavra-passe. A entrada resultante no ficheiro tem o seguinte aspeto:

“`

your_username:$2y$05$randomsaltandhashedpasswordstring

“`

Adicionar Utilizadores Adicionais

Para adicionar mais utilizadores a um ficheiro existente, omita a flag `-c`:

“`bash

sudo htpasswd -B /etc/apache2/.htpasswd second_user

sudo htpasswd -B /etc/apache2/.htpasswd third_user

“`

Remover um Utilizador

“`bash

sudo htpasswd -D /etc/apache2/.htpasswd username_to_remove

“`

Verificar o Conteúdo do Ficheiro

“`bash

sudo cat /etc/apache2/.htpasswd

“`

Cada linha representa um utilizador no formato `username:hashed_password`.

Passo 4: Configurar o Apache para Proteção por Palavra-passe

Existem dois métodos para aplicar a autenticação htpasswd: através de ficheiros `.htaccess` ou diretamente na configuração do virtual host. Cada um tem implicações distintas de desempenho e manutenção.

Comparação de Métodos

Num Servidor Dedicado ou VPS onde tem acesso root completo, o método de configuração do virtual host é sempre preferível pelo desempenho e manutenibilidade.

Opção 1: Utilizar Ficheiros .htaccess

Este método requer que `AllowOverride` esteja ativado para o diretório de destino. Primeiro, edite a configuração do site:

“`bash

sudo nano /etc/apache2/sites-available/000-default.conf

“`

Localize ou adicione o bloco `<Directory>` para o seu diretório raiz web e defina `AllowOverride All`:

“`apache

<VirtualHost *:80>

ServerAdmin webmaster@localhost

DocumentRoot /var/www/html

<Directory /var/www/html>

AllowOverride All

Options -Indexes +FollowSymLinks

Require all granted

</Directory>

</VirtualHost>

“`

Reinicie o Apache para aplicar a alteração de configuração:

“`bash

sudo systemctl restart apache2

“`

Agora crie o ficheiro `.htaccess` dentro do diretório que pretende proteger:

“`bash

sudo nano /var/www/html/.htaccess

“`

Adicione as seguintes diretivas de autenticação:

“`apache

AuthType Basic

AuthName "Restricted Access — Authorized Personnel Only"

AuthUserFile /etc/apache2/.htpasswd

Require valid-user

“`

Explicação das diretivas:

• `AuthType Basic` — Ativa a Autenticação Básica HTTP. A alternativa é `Digest`, que evita o envio de credenciais em Base64 mas tem problemas de compatibilidade mais amplos.
• `AuthName` — A string de realm exibida no diálogo de login do navegador. Torne-a suficientemente descritiva para que os utilizadores legítimos compreendam o que estão a aceder.
• `AuthUserFile` — Caminho absoluto para o ficheiro `.htpasswd`. Deve ser legível pelo utilizador do processo Apache (`www-data`).
• `Require valid-user` — Concede acesso a qualquer utilizador presente no ficheiro `.htpasswd`. Pode restringir ainda mais com `Require user alice bob` para permitir apenas contas específicas.

Guarde e feche o ficheiro. Não é necessário reiniciar o Apache — as alterações em `.htaccess` têm efeito imediato.

Opção 2: Configuração Direta do Virtual Host (Recomendado)

Esta é a abordagem de nível de produção. Edite o ficheiro de configuração do virtual host diretamente:

“`bash

sudo nano /etc/apache2/sites-available/000-default.conf

“`

Adicione um bloco `<Directory>` com diretivas de autenticação dentro do bloco `<VirtualHost>`:

“`apache

<VirtualHost *:80>

ServerAdmin webmaster@localhost

DocumentRoot /var/www/html

ServerName yourdomain.com

<Directory "/var/www/html/protected">

AuthType Basic

AuthName "Internal Tools"

AuthUserFile /etc/apache2/.htpasswd

Require valid-user

Options -Indexes

</Directory>

</VirtualHost>

“`

Note a utilização de `/var/www/html/protected` em vez de todo o diretório raiz web. Limitar a autenticação a um subdiretório é muito mais comum na prática — protege `/admin`, `/staging` ou `/api-docs` enquanto mantém o site público acessível.

Valide a sintaxe da configuração antes de reiniciar:

“`bash

sudo apachectl configtest

“`

Deverá ver `Syntax OK`. Se houver erros, o Apache descreve-os com precisão. Nunca reinicie o Apache sem passar por esta verificação em produção.

Reinicie o Apache:

“`bash

sudo systemctl restart apache2

“`

Proteger Tipos de Ficheiros Específicos em Vez de Diretórios

Um padrão menos conhecido mas altamente prático é utilizar `<FilesMatch>` para restringir o acesso a extensões de ficheiros específicas em vez de diretórios inteiros:

“`apache

<FilesMatch ".(env|log|sql|bak)$">

AuthType Basic

AuthName "Restricted Files"

AuthUserFile /etc/apache2/.htpasswd

Require valid-user

</FilesMatch>

“`

Isto é particularmente útil para bloquear o acesso direto a ficheiros `.env`, dumps de bases de dados ou ficheiros de log que possam existir no diretório raiz web por razões de legado.

Passo 5: Ativar SSL Antes de Colocar em Produção

Como estabelecido anteriormente, a Autenticação Básica HTTP sobre HTTP simples é insegura. Antes de expor qualquer recurso protegido por htpasswd à internet, imponha HTTPS.

Instale o Certbot para certificados Let’s Encrypt:

“`bash

sudo apt install certbot python3-certbot-apache -y

sudo certbot –apache -d yourdomain.com

“`

O Certbot modificará automaticamente a sua configuração Apache para redirecionar HTTP para HTTPS e instalar o certificado. Em alternativa, pode provisionar um certificado comercial através de Certificados SSL para domínios que requerem validação estendida ou cobertura wildcard.

Após ativar SSL, adicione um redirecionamento HTTPS ao seu virtual host HTTP:

“`apache

<VirtualHost *:80>

ServerName yourdomain.com

Redirect permanent / https://yourdomain.com/

</VirtualHost>

“`

Passo 6: Reforçar as Permissões do Ficheiro .htpasswd

O ficheiro `.htpasswd` contém credenciais com hash. Mesmo que os hashes bcrypt sejam computacionalmente dispendiosos de quebrar, o ficheiro deve ser protegido ao nível do sistema de ficheiros.

Defina a propriedade para o utilizador do processo Apache e restrinja as permissões de leitura:

“`bash

sudo chown root:www-data /etc/apache2/.htpasswd

sudo chmod 640 /etc/apache2/.htpasswd

“`

Esta configuração significa:

• `root` é proprietário do ficheiro e pode lê-lo/escrevê-lo
• `www-data` (o processo Apache) pode lê-lo
• Todos os outros utilizadores não têm acesso

Verifique as permissões:

“`bash

ls -la /etc/apache2/.htpasswd

“`

Resultado esperado:

“`

-rw-r—– 1 root www-data 89 Jan 15 10:23 /etc/apache2/.htpasswd

“`

Bloquear o Acesso Web Direto ao .htpasswd

Se por alguma razão o ficheiro `.htpasswd` estiver dentro do diretório raiz web, adicione uma regra de negação explícita à sua configuração Apache ou `.htaccess`:

“`apache

<Files ".htpasswd">

Require all denied

</Files>

“`

Esta é uma medida de defesa em profundidade. O ficheiro nunca deveria estar dentro do diretório raiz web, mas esta regra garante que, mesmo que esteja, o Apache retornará uma resposta 403 Forbidden em vez de servir o ficheiro.

Passo 7: Testar a Autenticação

Abra um navegador e navegue para o URL protegido:

“`

http://your_server_ip_or_domain/protected/

“`

Deverá ver um diálogo de autenticação nativo do navegador. Introduza as credenciais que criou com `htpasswd`. A autenticação bem-sucedida concede acesso; credenciais incorretas retornam uma resposta HTTP 401 Unauthorized.

Testar a partir da Linha de Comandos

Utilize `curl` para verificar o comportamento de autenticação sem um navegador:

“`bash

Test with correct credentials — should return 200 OK

curl -u your_username:your_password -I http://yourdomain.com/protected/

Test without credentials — should return 401 Unauthorized

curl -I http://yourdomain.com/protected/

Test with wrong credentials — should return 401 Unauthorized

curl -u your_username:wrongpassword -I http://yourdomain.com/protected/

“`

Isto é particularmente útil em pipelines CI/CD ou scripts de monitorização automatizados onde precisa de verificar que a autenticação é aplicada corretamente após implementações.

Padrões de Configuração Avançados

Combinar htpasswd com Controlo de Acesso Baseado em IP

Pode combinar autenticação por palavra-passe com listas brancas de IP utilizando blocos `RequireAll` ou `RequireAny`:

“`apache

<Directory "/var/www/html/admin">

AuthType Basic

AuthName "Admin Panel"

AuthUserFile /etc/apache2/.htpasswd

Allow access if EITHER condition is met

<RequireAny>

Require ip 192.168.1.0/24

Require valid-user

</RequireAny>

</Directory>

“`

Ou requerer AMBAS as condições simultaneamente (o IP deve corresponder E as credenciais devem ser válidas):

“`apache

<RequireAll>

Require ip 203.0.113.0/24

Require valid-user

</RequireAll>

“`

Este padrão é extremamente eficaz para painéis de administração: os utilizadores da rede interna obtêm acesso com prompt de palavra-passe, enquanto os IPs externos são bloqueados completamente independentemente das credenciais.

Limitar a Taxa de Tentativas de Autenticação

A Autenticação Básica HTTP não tem proteção integrada contra força bruta. Mitigue isto com `mod_evasive` ou `fail2ban`:

“`bash

sudo apt install fail2ban -y

“`

Crie um filtro Fail2ban personalizado para falhas de autenticação Apache em `/etc/fail2ban/filter.d/apache-auth.conf`:

“`ini

[Definition]

failregex = ^<HOST> -.*"(GET|POST|HEAD).*" 401

ignoreregex =

“`

Adicione uma configuração de jail em `/etc/fail2ban/jail.local`:

“`ini

[apache-auth]

enabled = true

port = http,https

filter = apache-auth

logpath = /var/log/apache2/access.log

maxretry = 5

bantime = 3600

findtime = 600

“`

Reinicie o Fail2ban:

“`bash

sudo systemctl restart fail2ban

“`

Isto bane qualquer IP que gere cinco respostas 401 em dez minutos durante uma hora — um dissuasor significativo contra o preenchimento automatizado de credenciais.

Utilizar Blocos Location para Proteção Baseada em URL

Para aplicações onde o conteúdo protegido é servido a partir de um caminho URL específico em vez de um diretório do sistema de ficheiros, utilize `<Location>` em vez de `<Directory>`:

“`apache

<Location "/api/internal">

AuthType Basic

AuthName "Internal API"

AuthUserFile /etc/apache2/.htpasswd

Require user api_user service_account

</Location>

“`

Note a utilização de `Require user` com nomes de utilizador específicos em vez de `Require valid-user` — isto restringe o endpoint apenas a essas duas contas mesmo que o ficheiro `.htpasswd` contenha utilizadores adicionais.

Matriz de Decisão Prática

Utilize esta matriz para determinar a abordagem de configuração correta para o seu cenário:

Principais Conclusões Técnicas

• Utilize sempre bcrypt (flag `-B`) ao criar ficheiros `.htpasswd`. Os hashes MD5 e SHA-1 legados são quebráveis com hardware GPU moderno em segundos.
• Nunca implemente htpasswd sobre HTTP em qualquer ambiente acessível a partir da internet. A codificação Base64 das credenciais de Autenticação Básica não fornece qualquer confidencialidade.
• Prefira a configuração do virtual host em vez de `.htaccess` em qualquer servidor onde tenha acesso root. A diferença de desempenho é mensurável sob carga porque o Apache relê os ficheiros `.htaccess` em cada pedido individual.
• Limite a proteção ao diretório ou caminho URL mínimo necessário. Proteger `/var/www/html` inteiramente quando apenas `/var/www/html/admin` necessita de proteção adiciona fricção desnecessária.
• Defina as permissões de `.htpasswd` para `640` com propriedade `root:www-data`. O ficheiro nunca deve ser legível por todos.
• Implemente o Fail2ban para prevenir ataques de força bruta. A Autenticação Básica HTTP não tem mecanismo nativo de limitação de taxa ou bloqueio de conta.
• Valide a configuração Apache com `apachectl configtest` antes de cada reinício em ambientes de produção.
• Combine htpasswd com a sua infraestrutura de domínio. Um domínio devidamente configurado com DNS e SSL é a base — gira o seu através de Registo de Domínios para manter todos os componentes de infraestrutura num único fornecedor.

Para equipas que gerem múltiplos ambientes protegidos, um VPS com cPanel fornece uma interface gráfica para gerir diretórios protegidos por palavra-passe sem acesso direto à linha de comandos, o que pode reduzir erros de configuração em equipas menos técnicas.

FAQ

A autenticação htpasswd funciona com todos os navegadores?

Sim. A Autenticação Básica HTTP está definida na RFC 7617 e é suportada por todos os navegadores modernos, incluindo Chrome, Firefox, Safari e Edge. Os navegadores móveis também a suportam. A aparência do diálogo nativo do navegador varia consoante o navegador e o sistema operativo, mas o comportamento do protocolo subjacente é idêntico.

O que acontece se o caminho do ficheiro .htpasswd estiver errado na configuração Apache?

O Apache retornará um Erro Interno do Servidor 500 para qualquer pedido ao recurso protegido e registará um erro semelhante a `Could not open password file: /path/to/.htpasswd` em `/var/log/apache2/error.log`. Verifique sempre se o caminho absoluto está correto e se o utilizador `www-data` tem permissão de leitura no ficheiro.

Posso usar htpasswd para proteger a área de administração de um site WordPress?

Sim, e é uma prática de reforço recomendada. Adicionar proteção htpasswd a `/wp-admin/` e restringir o acesso a `xmlrpc.php` adiciona uma camada de autenticação ao nível do servidor antes de a própria lógica de login do WordPress ser executada, bloqueando bots automatizados e scripts de força bruta que nunca chegam ao PHP. Configure-o como um bloco `<Directory>` no seu virtual host em vez de `.htaccess` para melhor desempenho.

Como atualizo a palavra-passe de um utilizador num ficheiro .htpasswd existente?

Execute `htpasswd` sem a flag `-c` e especifique o nome de utilizador existente: `sudo htpasswd -B /etc/apache2/.htpasswd existing_user`. Será solicitado que introduza a nova palavra-passe. O comando substitui apenas a entrada desse utilizador, deixando todos os outros utilizadores intactos.

Existe um limite para o número de utilizadores que podem ser armazenados num ficheiro .htpasswd?

Não existe um limite rígido imposto pelo Apache. No entanto, como o Apache realiza uma pesquisa linear do ficheiro para cada pedido de autenticação, o desempenho degrada-se visivelmente com ficheiros muito grandes — tipicamente acima de várias centenas de utilizadores. Para ambientes que requerem autenticação para dezenas ou centenas de utilizadores, considere `mod_authn_dbd` com um backend de base de dados, ou autenticação LDAP via `mod_authnz_ldap`, que são concebidos para escala.