Proteger uma pasta com palavra-passe (htpasswd) no VPS

A autenticação básica é a forma mais rápida de esconder um site de testes, uma pasta de administração ou uma ferramenta privada atrás de um pedido de login. Este guia cobre Apache e Nginx no seu VPS Linux Infrawire, com um ficheiro de palavras-passe criado com htpasswd.

📋 Pré-requisitos

• Um VPS Linux (Ubuntu 24.04 / Debian 12 ou AlmaLinux 9 / Rocky 9) com acesso SSH root. O IP e a palavra-passe root estão na sua área de cliente.
• Apache ou Nginx a servir já um site.
• Um certificado HTTPS válido para example.com. A autenticação básica envia a palavra-passe codificada em Base64, o que não é cifragem: nunca a use em HTTP simples.

📦 Instalar a ferramenta htpasswd

O comando htpasswd vem de um pequeno pacote, mesmo que use Nginx:

Bash
1# Debian / Ubuntu
2sudo apt install -y apache2-utils
3
4# AlmaLinux / Rocky
5sudo dnf install -y httpd-tools

🔐 Criar o ficheiro de palavras-passe

Guarde o ficheiro fora de qualquer raiz web, para que ninguém o possa descarregar:

Bash
1sudo mkdir -p /etc/htpasswd
2sudo htpasswd -c -B /etc/htpasswd/example.com USER

-B usa bcrypt. -c cria o ficheiro: use-o só para o primeiro utilizador, pois num ficheiro existente apaga tudo (destrutivo). Adicione mais utilizadores sem -c:

Bash
1sudo htpasswd -B /etc/htpasswd/example.com USER2

O servidor web tem de conseguir ler o ficheiro:

Bash
1# Debian / Ubuntu (Apache e Nginx correm como www-data)
2sudo chown root:www-data /etc/htpasswd/example.com
3# AlmaLinux / Rocky: grupo apache (Apache) ou nginx (Nginx)
4sudo chmod 640 /etc/htpasswd/example.com

Para remover um utilizador: sudo htpasswd -D /etc/htpasswd/example.com USER2.

🪶 Opção A: Apache com .htaccess

Coloque um ficheiro .htaccess na pasta a proteger, por exemplo /var/www/example.com/private/.htaccess:

Apache
AuthType Basic
AuthName "Área restrita"
AuthUserFile /etc/htpasswd/example.com
Require valid-user

Os ficheiros .htaccess são ignorados se o virtual host não os permitir. No seu bloco <Directory> (ficheiro em /etc/apache2/sites-available/ no Debian/Ubuntu, /etc/httpd/conf.d/ no AlmaLinux/Rocky):

Apache
<Directory /var/www/example.com>
    AllowOverride AuthConfig
</Directory>

Depois teste e recarregue:

Bash
1sudo apachectl configtest
2sudo systemctl reload apache2   # Debian / Ubuntu
3sudo systemctl reload httpd     # AlmaLinux / Rocky

Se preferir não usar .htaccess, coloque as quatro linhas de autenticação diretamente num bloco <Directory> ou <Location>: é mais rápido e seguro.

🚀 Opção B: Nginx com auth_basic

O Nginx não lê .htaccess. Adicione as diretivas ao bloco server:

Nginx
1server {
2    listen 443 ssl;
3    server_name example.com;
4    # linhas ssl_certificate aqui
5
6    location /private/ {
7        auth_basic           "Área restrita";
8        auth_basic_user_file /etc/htpasswd/example.com;
9    }
10}

Para proteger o site todo, ponha essas duas linhas no bloco server. Para deixar um caminho público dentro de um site protegido (por exemplo um webhook), adicione auth_basic off; no seu próprio location. Depois:

Bash
1sudo nginx -t && sudo systemctl reload nginx

✅ Testar

Sem credenciais deve obter um 401 e com credenciais um 200:

Bash
1curl -I https://example.com/private/
2curl -I -u USER https://example.com/private/

Primeira resposta esperada:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Basic realm="Área restrita"

O curl pede a palavra-passe quando indica apenas -u USER, o que evita deixá-la no histórico da shell.

🛠️ Resolução de problemas

Não aparece o pedido de login no Apache. O AllowOverride continua em None, ou o .htaccess está na pasta errada. Reveja o bloco <Directory> e recarregue.

Sempre 401 com a palavra-passe certa. O servidor web não consegue ler o ficheiro (verifique chown e chmod), ou o caminho em AuthUserFile ou auth_basic_user_file está errado. O registo de erros indica-o: /var/log/apache2/error.log, /var/log/httpd/error_log ou /var/log/nginx/error.log.

Erro 500 depois de adicionar o .htaccess. Uma diretiva é inválida ou falta um módulo. Execute sudo apachectl configtest e leia a mensagem.

Pedido de palavra-passe em HTTP. Redirecione primeiro HTTP para HTTPS, para que as credenciais nunca circulem em claro.

---

🎉 A sua pasta privada pede agora login, com palavras-passe em hash guardadas fora de alcance e servidas apenas por HTTPS.