Linux / Comando ssh-copy-id: cadastrar a chave pública e testar o acesso

O comando ssh-copy-id adiciona uma chave pública SSH à lista de chaves autorizadas de uma conta remota, normalmente em ~/.ssh/authorized_keys. Ele prepara a autenticação por chave pública; a chave privada permanece no computador de origem.

É necessário já conseguir autenticar-se na conta de destino, por senha ou outro método permitido. A ferramenta não contorna as regras do servidor nem cria uma conta. Use -i para escolher explicitamente a chave pública que deseja cadastrar, evitando a seleção automática de outras chaves locais ou de um agente SSH, programa que disponibiliza identidades ao cliente.

Sintaxe e pré-requisitos

ssh-copy-id [opções] [usuário@]host

Essa linha descreve a sintaxe, não um comando pronto. Confira man ssh-copy-id no seu ambiente: a presença do programa e opções como -n e -s dependem da implementação. Tenha um par de chaves utilizável, a conta remota correta, a porta do serviço SSH e autorização para alterar a lista de chaves dessa conta.

Se ainda não houver um par adequado, o guia do ssh-keygen para gerar chaves e conferir impressões digitais explica como criá-lo sem sobrescrever outro par. Para a conexão, compare a chave de host do servidor com uma referência confiável, conforme o guia do comando ssh e da verificação do servidor. A chave do servidor e a sua chave de usuário têm funções diferentes.

Os nomes server.example.com e server.example.test, bem como as contas alice e user, são ilustrativos. Substitua-os por um destino autorizado. Os caminhos com ~/.ssh/ abaixo usam a convenção de diretório pessoal de um shell Unix.

Conferir, simular e cadastrar

Conferir a chave pública: confirme que o arquivo escolhido é a parte pública do par e verifique sua impressão digital completa. O sufixo .pub é uma convenção de nome, não uma garantia do conteúdo.

ssh-keygen -lf ~/.ssh/id_ed25519_work.pub

Simular o cadastro: nas implementações com -n, o programa mostra as chaves que seriam instaladas, sem adicioná-las à lista remota. Isso não significa uma operação totalmente offline: a ferramenta pode conectar-se para verificar quais chaves já permitem autenticação e pedir uma frase secreta.

ssh-copy-id -n -i ~/.ssh/id_ed25519_work.pub alice@server.example.com

Confira se as chaves mostradas são as pretendidas e se o host e a conta estão corretos. A simulação não garante que um cadastro posterior terá sucesso, pois permissões, configuração e estado do destino podem mudar.

Adicionar a chave pública: depois de verificar a identidade do servidor e o plano, execute sem -n. Pode ser solicitado o método de autenticação já disponível para a conta, como a senha do servidor.

ssh-copy-id -i ~/.ssh/id_ed25519_work.pub alice@server.example.com

No comportamento padrão documentado, a ferramenta verifica as chaves que já conseguem autenticar-se e acrescenta as restantes ao authorized_keys remoto, criando o arquivo e o diretório quando necessário. Ela pode precisar da chave privada correspondente localmente para fazer essa verificação; isso não significa enviá-la ao servidor.

Verificar o resultado do cadastro

O exemplo seguinte usa outra conta ilustrativa. Ele altera a autorização dessa conta remota e só deve ser executado depois das mesmas verificações de identidade, chave e permissões.

ssh-copy-id -i ~/.ssh/id_ed25519_work.pub user@server.example.test

Quando uma chave é acrescentada, pode aparecer a mensagem abaixo. Ela é um exemplo do texto do programa, não o resultado de um cadastro real realizado neste artigo. Se a chave já funciona, a ferramenta pode não precisar acrescentá-la novamente.

Number of key(s) added: 1

Depois, abra outro terminal e teste ssh -i ~/.ssh/id_ed25519_work user@server.example.test. Um login bem-sucedido com esse comando, sozinho, não comprova que a chave pretendida foi usada: a configuração, o agente ou uma autenticação alternativa podem participar.

Para limitar o teste ao método de chave pública, pode usar ssh -o PreferredAuthentications=publickey -o IdentitiesOnly=yes -i ~/.ssh/id_ed25519_work user@server.example.test. O IdentitiesOnly=yes limita as identidades às configuradas, incluindo as selecionadas no comando; outras identidades explicitamente configuradas ainda podem existir. Se necessário, use o diagnóstico -v e confira qual chave foi aceita, preservando a confidencialidade dos registros. Políticas que exigem chave e um segundo fator podem impedir que esse teste restrito conclua o login.

1. Mantenha a sessão administrativa atual aberta e confirme uma forma autorizada de recuperação.
2. Confira a chave pública, o destino e a identidade do servidor; revise a simulação quando ela for suportada.
3. Cadastre a chave e teste em uma nova sessão, verificando o método e a chave realmente aceitos.
4. Somente depois de confirmar o acesso e a recuperação, avalie mudanças na política de autenticação com o administrador responsável.

Opções principais

Senha, permissões e remoção de uma chave

Uma solicitação de senha da conta durante o primeiro cadastro pode ser normal. Uma solicitação da frase secreta da chave privada é diferente: ela desbloqueia a chave local e pode continuar existindo mesmo com autenticação por chave pública funcionando. Leia a solicitação antes de concluir que o cadastro falhou.

Se a autenticação esperada falhar após o cadastro, confira a conta e o host usados, o par privado correspondente, as permissões de ~/.ssh/ e authorized_keys, a propriedade dos arquivos e as regras do serviço SSH. O servidor pode usar outro local para chaves autorizadas ou exigir fatores adicionais. A criação do arquivo padrão não garante que a política do servidor o utilize.

Não ignore avisos de chave de host alterada nem desative a autenticação por senha apenas porque apareceu uma mensagem de sucesso. Antes de mudar políticas, teste uma nova sessão e confirme outros acessos administrativos e a recuperação. O cadastro de uma chave e a alteração da política de autenticação são operações distintas.

Para retirar uma autorização, faça primeiro um backup do arquivo utilizado pela conta remota e identifique a linha da chave pública exata. Remova somente essa entrada, preservando as outras chaves, restrições e comentários necessários. Se houver entradas duplicadas da mesma chave, retirar apenas uma pode deixar outra autorização ativa. Verifique o resultado sem encerrar prematuramente sua sessão de recuperação.

Na verificação deste artigo, o ssh-copy-id estava disponível no Git Bash do Windows, mas não havia um servidor remoto de teste autorizado. Sete comandos passaram na análise de sintaxe do Bash; uma consulta local ssh -G -F none confirmou a interpretação das opções de método e identidades. Não houve execução de cadastro, transferência de chave, login remoto, alteração de authorized_keys nem teste nativo do Linux.

Pergunta frequente

Por que o ssh-copy-id ainda pede uma senha?

O cadastro inicial precisa de um acesso já autorizado e pode pedir a senha da conta. Depois do cadastro, diferencie essa senha da frase secreta que desbloqueia a chave privada local. Se o servidor continuar exigindo uma autenticação inesperada, confira a chave realmente aceita, a conta, as permissões e a política do serviço; alguns ambientes exigem fatores adicionais.

Documentação

O manual do ssh-copy-id reproduzido pelo man7.org descreve as opções. O código-fonte do manual no repositório oficial OpenSSH Portable permite conferir as condições do modo padrão, da simulação e do SFTP. A documentação oficial de configuração do cliente SSH detalha PreferredAuthentications e IdentitiesOnly.