"Permission denied (publickey)" no SSH e como interpretá-lo com ssh -v

O que é

O cliente OpenSSH exibe user@host: Permission denied (publickey). quando todos os métodos de autenticação que o servidor se dispôs a tentar terminaram em rejeição. Os nomes de métodos entre parênteses são apenas o que o servidor ofereceu para tentativa, e não o que falhou por um motivo específico; a mensagem em si não traz nenhum detalhe sobre qual chave foi tentada nem por que não funcionou.

Por que importa

A mensagem é genérica de propósito (revelar mais ajudaria um atacante a enumerar nomes de usuário ou chaves válidos). Por isso, tentar corrigir o problema por adivinhação só faz perder tempo: a causa real é uma entre poucas possibilidades, e o ssh -v a aponta diretamente, sem depender de tentativa e erro.

Como aplicar

• Comece diagnosticando com saída detalhada: ssh -v (ou -vvv para mais detalhes) mostra exatamente quais chaves o cliente ofereceu, em que ordem e como o servidor respondeu a cada uma ("Offering public key", "Server accepts key", "Authentications that can continue"). Leia essa saída antes de alterar qualquer configuração.
• Causas comuns, da correção menos invasiva à mais invasiva:
  1. Nome de usuário remoto errado: conectar com o nome da conta local quando o servidor espera outro (por exemplo, ec2-user, git). Passe -l user ou corrija a entrada User no bloco Host correspondente.
  2. A chave correta existe no disco, mas não estava entre as oferecidas. Por padrão, o ssh tenta as chaves de um agente e os nomes de arquivo padrão; indique explicitamente a chave certa com -i path/to/key junto com IdentitiesOnly yes (documentado em ssh_config(5)). Assim, o ssh não envia também chaves irrelevantes ao servidor, o que poderia esgotar o limite de tentativas do próprio servidor antes de chegar à chave certa.
  3. Permissões no servidor: o sshd_config(5) documenta o StrictModes, que faz o sshd rejeitar a autenticação se o diretório home, ~/.ssh ou authorized_keys puderem ser gravados por alguém que não seja o dono. Verifique e corrija o proprietário e as permissões (normalmente 700 para ~/.ssh e 600 para authorized_keys) no lado do servidor, usando o log de autenticação dele para confirmar que essa é a causa.
  4. Desde o OpenSSH 8.8, cliente e servidor deixam de usar por padrão assinaturas RSA com SHA-1 (o algoritmo ssh-rsa), conforme as notas de versão do OpenSSH 8.8. As chaves RSA em si continuam funcionando por meio de rsa-sha2-256/512, compatíveis desde o OpenSSH 7.2; as falhas aparecem quando uma ponta é 8.8 ou posterior e a outra só fala ssh-rsa (servidores muito antigos, appliances, bibliotecas SSH antigas). Prefira atualizar essa ponta ou trocar para uma chave ed25519; apenas como solução provisória, que enfraquece a segurança, reative o algoritmo para esse único host com PubkeyAcceptedAlgorithms +ssh-rsa (nome usado a partir do OpenSSH 8.5) em um bloco Host, e não de forma global.
• Não é solução: repetir a tentativa várias vezes, ou copiar uma chave privada de forma insegura entre máquinas em vez de provisionar uma chave adequada ou usar o encaminhamento de agente (agent forwarding).

Armadilhas

• Procurar uma correção no cliente quando a causa real são as permissões do authorized_keys no servidor, algo que só os logs do próprio servidor revelam.
• Supor que uma chave "ainda funciona" porque funcionou ontem, quando uma atualização do OpenSSH em qualquer uma das pontas mudou da noite para o dia os algoritmos aceitos.