SSH Permission denied (publickey): a correção certa

Às 02:10 um deploy morreu numa linha que já digitei mil vezes: ssh deploy@staging → Permission denied (publickey). A chave estava certa. A oferta, não.

TL;DR: Permission denied (publickey) significa que cada chave que o cliente ofereceu foi recusada pelo servidor — um veredito de negociação, não uma senha errada. Diagnostique com ssh -vvv (quais chaves foram oferecidas) e o log do servidor journalctl -u ssh (quais foram recusadas, e por quê). Depois corrija uma das quatro causas: usuário errado, chave ausente do authorized_keys, permissões muito abertas, ou uma chave ssh-rsa recusada pelo OpenSSH 8.8+. ssh-copy-id evita a maioria das recaídas.

$ ssh -T [email protected]
[email protected]: Permission denied (publickey).

O erro é um veredito, não uma pista: tudo o que estava na oferta foi recusado.

Por que o SSH diz “Permission denied (publickey)“?

A autenticação por chave pública é uma negociação de oferta e recusa. O cliente propõe toda chave que consegue encontrar — identidades do agente, do seu ~/.ssh/config, nomes de arquivo padrão (id_ed25519, id_rsa) e tudo o que passar com -i. O servidor confere cada oferta contra o ~/.ssh/authorized_keys da conta alvo. Quando nada corresponde, e a autenticação por senha está desativada ou esgotada, o cliente imprime a linha que todo engenheiro devops tem decorada.

Dois fatos importam para depurar. Primeiro, a mensagem não diz qual usuário você atingiu — metade dos casos é uma chave perfeitamente boa sentada no authorized_keys da conta errada. Segundo, o servidor já disse o porquê: o sshd registra cada oferta recusada. O stack trace que ninguém pediu e todo mundo precisa é o -vvv.

Como vejo qual chave o SSH está realmente oferecendo?

ssh -vvv deploy@staging 2>&1 | grep -iE "offering|identity|denied|authentications"
# debug1: Offering public key: /home/you/.ssh/id_ed25519 RSA-SHA256 (explicit)
# debug1: Authentications that can continue: publickey
# deploy@staging: Permission denied (publickey).

Leia três linhas: Offering public key (o que o cliente propôs), Authentications that can continue (o que o servidor ainda aceita — se password não aparece, nenhum pedido de senha chegará jamais) e o veredito final. Se a sua chave nunca aparece na lista de ofertas, o problema está no cliente: caminho -i errado, um IdentityFile esquecido no ~/.ssh/config, ou um agente (ssh-add -l) segurando uma identidade obsoleta que responde primeiro.

Quais são as quatro causas reais?

Causa	Sinal	Correção
Usuário errado	A chave funciona para root@host, falha para deploy@host	A chave deve estar no ~/.ssh/authorized_keys daquele usuário
Chave não instalada	O log do servidor mostra Failed publickey em cada oferta	ssh-copy-id user@host
Permissões muito abertas	Cliente: WARNING: UNPROTECTED PRIVATE KEY FILE — a chave é descartada, nunca oferecida	chmod 700 ~/.ssh; chmod 600 ~/.ssh/*
Chave ssh-rsa antiga	Servidor com OpenSSH 8.8+; chave RSA velha nunca aceita	Regenerar como ed25519, ou modernizar a chave

A causa das permissões merece nota à parte, porque o OpenSSH a aplica com rigor: uma chave privada legível pelo grupo ou por outros é recusada pelo próprio cliente e sai silenciosamente da oferta. A correção são dois comandos:

chmod 700 ~/.ssh
chmod 600 ~/.ssh/id_ed25519 ~/.ssh/authorized_keys

A causa ssh-rsa tropeça em imagens de CI antigas e Raspberry Pi: o OpenSSH 8.8 (lançado em 2021-10-01, openssh.com/txt/release-8.8) desativou por padrão as assinaturas ssh-rsa — a variante baseada em SHA-1. Nas palavras das release notes, “the ssh-rsa signature scheme is … disabled by default”. Uma chave RSA gerada em 2018 não está quebrada; o formato de assinatura dela simplesmente não é mais falado. Gerar uma chave ed25519 (ssh-keygen -t ed25519) é a resposta duradoura, e os consoles de nuvem oferecem um console serial para quando você se trancar fora no meio do conserto.

Se o sshd se recusa a iniciar enquanto você edita a configuração dele, essa é outra caçada — veja systemd service not starting.

Como vejo por que o servidor recusou a chave?

O log do servidor é a testemunha honesta. No Ubuntu (systemd), o sshd registra o veredito de cada oferta:

journalctl -u ssh -n 50 --no-pager | grep -iE "publickey|denied|accepted"
# sshd[4421]: Failed publickey for deploy from 203.0.113.7 port 51422 ssh2: RSA SHA256:...
# sshd[4421]: Accepted publickey for deploy from 203.0.113.7 port 51422 ssh2: ED25519 SHA256:...

Um Failed publickey com uma impressão digital inesperada significa que o cliente ofereceu uma chave diferente da que você pensava — de volta ao -vvv. Um Failed publickey com a sua impressão significa que a chave está certa mas não está instalada para aquela conta, ou que as permissões do home no lado do servidor estão erradas (a mesma regra 700/600 vale para o ~/.ssh e o ~/.ssh/authorized_keys do servidor).

Como instalo a minha chave corretamente?

ssh-copy-id deploy@staging
# Number of key(s) added: 1
ssh -o BatchMode=yes deploy@staging 'echo ok'   # prova não interativa

O ssh-copy-id adiciona a sua chave pública ao authorized_keys da conta alvo com permissões sãs — existe porque colar à mão no authorized_keys falha na medida certa, por uma quebra de linha final ou um diretório que não existe. O teste com BatchMode é a prova real: desativa todos os prompts, então o sucesso significa que a chave sozinha carregou o login. Com a chave funcionando, scp e rsync herdam a mesma autenticação de graça — a escolha entre eles é banda, não credenciais (rsync vs scp).

A triagem de 30 segundos

ssh -vvv user@host 2>&1 | grep -i offering      # 1. quais chaves foram oferecidas?
journalctl -u ssh -n 50 | grep -i publickey     # 2. por que foram recusadas?
ls -ld ~/.ssh ~/.ssh/authorized_keys            # 3. 700 / 600?
ssh-copy-id user@host                           # 4. instalar, e verificar com BatchMode

Permission denied (publickey) é um resultado de negociação, não um pedido de senha — o servidor recusou cada chave da oferta, e o log dele já sabe o porquê.

Os quatro comandos na ordem e a falha deixa de ser mistério: um deles aponta o culpado todas as vezes. O meu era uma identidade de agente obsoleta respondendo antes da chave certa — ssh-add -d, e o deploy ficou verde às 02:31.