Utilizar a autenticação de chaves SSH

Azure DevOps Serviços | Azure DevOps Server | Azure DevOps Server 2022

Use SSH no macOS, Linux ou Windows para autenticar de forma segura nos repositórios Git do Repositórios do Azure no Azure DevOps.

Este artigo mostra como criar um par de chaves RSA, adicionar a chave pública ao seu perfil e clonar repositórios usando SSH.

Pré-requisitos

Como funciona a autenticação de chave SSH

A autenticação de chave pública SSH funciona com um par assimétrico de chaves de criptografia geradas. Partilhas a chave pública com o Azure DevOps para verificar a ligação inicial ao SSH. Mantenha a chave privada segura e protegida no seu sistema.

Configurar a autenticação de chave SSH

Para usar SSH com o Repositórios do Azure, gera um par de chaves RSA, adicione a chave pública ao seu perfil Azure DevOps, verifique a impressão digital do servidor e depois clone ou atualize o seu repositório para usar o URL do SSH.

Se só precisar do caminho mais rápido, conclua o Passo 1, o Passo 2 e o Passo 3 por esta ordem e, depois, use Resolver problemas de autenticação SSH apenas se algum comando falhar.

Os passos seguintes cobrem a configuração da autenticação de chaves SSH nas seguintes plataformas utilizando a linha de comandos (também chamada shell):

• Linux
• macOS
• Sistemas Windows a correr Git for Windows

Passo 1: Crie as suas chaves SSH

Para usar autenticação baseada em chaves, primeiro precisa de gerar um par de chaves pública/privada para o seu cliente. O OpenSSH pode gerar vários tipos de chaves, mas o Azure DevOps suporta chaves RSA para autenticação SSH.

Para gerar um par de chaves RSA para Azure DevOps, execute o seguinte comando a partir do PowerShell ou de outro shell, como bash no seu cliente:

ssh-keygen -t rsa -b 3072

A saída do comando deve exibir a seguinte saída (onde username é o seu nome de usuário):

Generating public/private rsa key pair.
Enter file in which to save the key (C:\Users\username/.ssh/id_rsa):

Prima Enter para aceitar o valor predefinido, ou especifique um caminho e/ou um nome de ficheiro onde pretende que as suas chaves sejam geradas. Neste ponto, você será solicitado a usar uma frase secreta para criptografar seus arquivos de chave privada. A palavra-passe pode estar vazia, mas não é recomendada. A palavra-passe adiciona outra camada de proteção para a sua chave privada caso o ficheiro seja exposto.

Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in C:\Users\username/.ssh/id_rsa.
Your public key has been saved in C:\Users\username/.ssh/id_rsa.pub.
The key fingerprint is:
SHA256:FHK6WjcUkcfQjdorarzlak1Ob/x7AmqQmmx5ryYYV+8 username@LOCAL-HOSTNAME
The key's randomart image is:
+---[RSA 3072]----+
|      . ** o     |
|       +.o= .    |
|      . o+       |
|      .+. .      |
|     .ooS  .     |
|  . .oo.=.o      |
|   =.= O.= .     |
|  . B BoE + . .  |
|   . *+*o. .o+   |
+----[SHA256]-----+

Agora tens um par de chaves RSA público/privado na localização que especificaste. Os .pub ficheiros são chaves públicas, e os ficheiros sem extensão são chaves privadas:

Mode                 LastWriteTime         Length Name
----                 -------------         ------ ----
-a----        10/11/2022   6:29 PM           2610 id_rsa
-a----        10/11/2022   6:29 PM            578 id_rsa.pub

Passo 2: Adicionar a chave pública ao Azure DevOps

Associe a chave pública gerada na etapa anterior ao seu ID de usuário.

1. Abra suas configurações de segurança navegando até o portal da Web e selecionando o ícone ao lado do avatar no canto superior direito da interface do usuário. Selecione chaves públicas SSH no menu que aparece.

   

2. Selecione + Nova Chave.

   

3. Copie o conteúdo da chave pública (por exemplo, id_rsa.pub) gerada para o campo Dados de Chave Pública .

   Importante

   Evite adicionar espaços extra ou quebras de linha no meio do valor da chave, pois podem tornar a chave inválida. Se o paste adicionar artefactos de formatação, remove-os antes de guardares.

   

4. Dê à chave uma descrição útil (esta descrição é exibida na página de chaves públicas SSH do seu perfil) para que você possa lembrá-la mais tarde. Selecione Salvar para armazenar a chave pública. Uma vez salvo, você não pode alterar a chave. Você pode excluir a chave ou criar uma nova entrada para outra chave. Não há restrições sobre quantas chaves você pode adicionar ao seu perfil de usuário.

   Nota

   A política da organização pode impor a expiração da chave SSH. Para mais informações, consulte Alterar políticas de ligação e segurança à aplicação para a sua organização.

5. Na página de visão geral de Chaves Públicas SSH, as impressões digitais do servidor são exibidas. Anote a impressão digital SHA256 para utilizar quando se ligar ao Azure DevOps via SSH.

   

6. Teste a conexão executando o seguinte comando:

   ssh -T git@ssh.dev.azure.com
   

   Se você estiver se conectando pela primeira vez, deverá receber a seguinte saída:

   The authenticity of host 'ssh.dev.azure.com (<IP>)' can't be established.
   RSA key fingerprint is SHA256:ohD8VZEXGWo6Ez8GSEJQ9WpafgLFsOfLOtGGQCQo6Og.
   This key is not known by any other names
   Are you sure you want to continue connecting (yes/no/[fingerprint])?
   

   Compare essa impressão digital com a impressão digital SHA256 mostrada na página de chaves públicas do SSH . Continue apenas se os valores coincidirem.

7. Entre yes para continuar. Se tudo estiver configurado corretamente, a saída deverá ter esta aparência:

    Warning: Permanently added 'ssh.dev.azure.com' (RSA) to the list of known hosts.
    remote: Shell access is not supported.
    shell request failed on channel 0
   

   Caso contrário, consulte a secção Perguntas e resolução de problemas.

Passo 3: Clone o repositório Git usando SSH

1. Copie a URL de clonagem SSH do portal web. Neste exemplo, a URL de clone SSH é para um repositório em uma organização chamada fabrikam-fiber, conforme indicado pela primeira parte da URL após dev.azure.com.

   

   Nota

   Com Azure DevOps Services, o formato da URL do projeto é dev.azure.com/{your organization}/{your project}. No entanto, o formato anterior que faz referência ao visualstudio.com formato ainda é suportado. Para mais informações, consulte Apresentando o Azure DevOps, Mudar as organizações existentes para usarem o novo URL do nome de domínio.

2. Execute git clone a partir do prompt de comando.

   git clone git@ssh.dev.azure.com:v3/fabrikam-fiber/FabrikamFiber/FabrikamFiber
   

   Se não estiver a utilizar um Agente SSH, ser-lhe-á pedido que introduza a sua frase secreta:

   Cloning into 'FabrikamFiber'...
   Enter passphrase for key '/c/Users/username/.ssh/id_rsa':
   remote: Azure Repos
   remote: Found 127 objects to send. (50 ms)
   Receiving objects: 100% (127/127), 56.67 KiB | 2.58 MiB/s, done.
   Resolving deltas: 100% (15/15), done.
   

   Se, em vez disso, lhe pedirem para verificar uma impressão digital, leia Passo 2: Adicionar a chave pública ao Azure DevOps novamente. Para outros problemas, leia a seção Perguntas e solução de problemas.

Use IA para trabalhar com repositórios autenticados por SSH

Se usar repositórios Git com o GitHub Copilot ou o Azure DevOps MCP Server, pode usar prompts em linguagem natural para validar a sua configuração SSH e diagnosticar problemas de autenticação.

Resolução de problemas e perguntas frequentes

Use as secções seguintes para encontrar o problema que corresponde ao seu problema de configuração SSH.

• Se a sua chave expirou ou for inválida, comece por Chaves expiradas ou inválidas.
• Se o SSH não conseguir estabelecer ligação, comece por Falhas comuns de ligação.
• Se te for repetidamente pedida uma frase-passe, começa por problemas com o agente SSH e a frase-passe.
• Se estiveres a usar várias chaves ou organizações, vai a Gerir várias chaves e organizações.
• Se precisares de notificação ou orientação da conta, vai a Notificações e problemas da conta.

Chaves expiradas ou inválidas

P: A minha chave SSH expirou. O que devo fazer?

R: Siga os passos anteriores para criar e carregar uma nova chave SSH.

Como opção alternativa, um Administrador da Coleção Project pode desativar a política que valida a data de expiração da chave SSH. Por padrão, a política de validação da expiração de chave SSH está habilitada. Para obter mais informações, consulte Políticas de chave SSH.

Recebe automaticamente uma notificação sete dias antes e quando a sua chave expira. Juntamente com estas notificações, vê as seguintes mensagens:

remote: Authentication failed: your SSH key has expired. To restore access, visit https://aka.ms/ado-ssh-public-key-expired for guidance.
remote: Public key authentication failed.
fatal:  Could not read from remote repository.

Falhas comuns de ligação

P: Vejo avisos relacionados ao ssh-rsa. O que devo fazer?

R: Pode ver uma das seguintes mensagens de aviso:

ssh-rsa is about to be deprecated and your request has been throttled. Please use rsa-sha2-256 or rsa-sha2-512 instead. Your session will continue automatically. For more details see https://devblogs.microsoft.com/devops/ssh-rsa-deprecation.

Ou

You’re using ssh-rsa that is about to be deprecated and your request has been blocked intentionally. Any SSH session using ssh-rsa is subject to brown out (failure during random time periods). Please use rsa-sha2-256 or rsa-sha2-512 instead. For more details see https://devblogs.microsoft.com/devops/ssh-rsa-deprecation.

Se modificaste a tua configuração SSH para rebaixar as definições de segurança para Azure DevOps adicionando o seguinte ao teu ficheiro ~/.ssh/config (%UserProfile%\.ssh\config em Windows):

Host ssh.dev.azure.com vs-ssh.visualstudio.com
  HostkeyAlgorithms +ssh-rsa

Remove estas linhas agora e certifica-te de que rsa-sha2-256 e rsa-sha2-512 são permitidos.

Para mais informações, veja a mensagem do blogue.

Esta remediação é a solução canónica para avisos obsoletos ssh-rsa e erros não suportados ssh-rsa . Usa-o como primeiro passo nesses cenários.

P: O SSH não consegue estabelecer uma ligação. O que devo fazer?

R: Pode deparar-se com vários problemas diferentes:

• Uso de ssh-rsa sem suporte

  You’re using ssh-rsa that is unsupported. Please use rsa-sha2-256 or rsa-sha2-512 instead. For more details see https://devblogs.microsoft.com/devops/ssh-rsa-deprecation.
  

  Aplique a mesma remediação descrita na questão anterior sobre os avisos de ssh-rsa: remova qualquer HostkeyAlgorithms +ssh-rsa substituição e utilize rsa-sha2-256 e/ou rsa-sha2-512.

• Nenhuma chave de host correspondente

  Este problema não deve acontecer no Azure DevOps Serviço nem em versões Azure DevOps Server mais recentes, como mencionado no artigo blog.

  Unable to negotiate with <IP> port 22: no matching host key type found. Their offer: ssh-rsa
  

  Modifique a sua configuração SSH para reduzir as definições de segurança para o Azure DevOps adicionando o seguinte ao seu ficheiro ~/.ssh/config (%UserProfile%\.ssh\config em Windows):

  Host ssh.dev.azure.com vs-ssh.visualstudio.com
     HostkeyAlgorithms +ssh-rsa
  

  Utilize esta solução de contorno apenas para cenários de compatibilidade com sistemas legados, normalmente em configurações mais antigas do Azure DevOps Server autoalojadas. No Azure DevOps Services, mantenha as predefinições seguras e evite substituições persistentes ssh-rsa.

  Importante

  O OpenSSH substituiu o algoritmo de assinatura de ssh-rsa chave pública na versão 8.2 e o desabilitou por padrão na versão 8.8.

• Sem MAC correspondente

  Unable to negotiate with <IP> port 22: no matching MAC found. Their offer: hmac-sha2-256,hmac-sha2-512
  

  Modifique a sua configuração SSH para reduzir as definições de segurança para o Azure DevOps adicionando o seguinte ao seu ficheiro ~/.ssh/config (%UserProfile%\.ssh\config em Windows):

  Host ssh.dev.azure.com vs-ssh.visualstudio.com
     MACs +hmac-sha2-512,+hmac-sha2-256
  

• Nenhum método de troca de chaves correspondente

  Unable to negotiate with <IP> 22: no matching key exchange method found. Their offer: diffie-hellman-group1-sha1,diffie-hellman-group14-sha1,diffie-hellman-group-exchange-sha256
  

  Modifique a sua configuração SSH para reduzir as definições de segurança para o Azure DevOps adicionando o seguinte ao seu ficheiro ~/.ssh/config (%UserProfile%\.ssh\config em Windows):

  Host ssh.dev.azure.com vs-ssh.visualstudio.com
     KexAlgorithms +diffie-hellman-group-exchange-sha256,+diffie-hellman-group14-sha1,+diffie-hellman-group1-sha1
  

  Importante

  O algoritmo diffie-hellman-group1-sha1 de troca de chaves está desativado por defeito na versão 6.9 do OpenSSH e diffie-hellman-group14-sha1 na versão 8.2.

Problemas com agentes SSH e frases de acesso

P: O agente SSH não está a correr, ou a minha chave não está carregada. O que devo fazer?

R: Se a tua chave existir mas o SSH ainda pedir uma palavra-passe sempre, ou se a clonagem falhar depois de a chave ser criada com sucesso, verifica se o agente SSH está a correr e se a tua chave está carregada.

Use o seguinte comando para ver que identidades o agente tem atualmente carregado:

ssh-add -l

Se a saída indicar que o agente não tem identidades, adicione a sua chave privada ao agente:

ssh-add ~/.ssh/id_rsa

No Windows, se estiveres a usar PowerShell com o agente OpenSSH incorporado, certifica-te de que o ssh-agent serviço está a correr antes de adicionares a chave. Se usares o Git Bash ou outro cliente SSH, consulta a documentação desse cliente para iniciar o agente e carregar as chaves.

Se preferires não usar um agente, o SSH ainda pode funcionar, mas é solicitado a usar a palavra-passe chave com mais frequência.

P: Como posso fazer com que o Git se lembre da senha da minha chave?

R: Usa um agente SSH. Linux, macOS e Windows (a partir de Windows 10 (build 1809) ou usando Git para Windows com Git Bash) são todos fornecidos com um Agente SSH. O Agente SSH pode armazenar em cache as suas chaves SSH para uso repetido. Consulte o manual do seu fornecedor de SSH para obter detalhes sobre como usá-lo.

P: Eu uso o PuTTY como meu cliente SSH e gerei minhas chaves com o PuTTYgen. Posso usar estas chaves com o Azure DevOps Services?

R: Sim. Carregue a chave privada com PuTTYgen, vá para o menu Conversões e selecione Exportar chave OpenSSH. Guarde o ficheiro da chave privada e depois siga a pergunta seguinte neste artigo sobre o uso de uma localização de chave não padrão. Copie a sua chave pública diretamente da janela PuTTYgen e cole no campo Dados da chave nas suas configurações de segurança.

P: Como posso verificar se a chave pública que carreguei é a mesma chave que a minha chave local?

R: Verifica a impressão digital da chave pública que carregaste comparando-a com a que aparece no teu perfil. Execute o comando seguinte ssh-keygen na sua chave pública usando a linha de comandos. Você precisa alterar o caminho e o nome do arquivo de chave pública se não estiver usando os padrões.

ssh-keygen -l -E md5 -f <path_to_your_public_key>

ssh-keygen -l -E sha256 -f <path_to_your_public_key>

Depois compara a assinatura com a do teu perfil. Esta verificação é útil se tiver problemas de ligação ou se tiver preocupações em colar incorretamente a chave pública no campo Key Data ao adicionar a chave ao Azure DevOps.

P: Como posso começar a usar SSH em um repositório onde estou usando HTTPS atualmente?

R: Atualize o origin comando no Git para mudar de HTTPS para URL SSH. Depois de obteres o URL clone do SSH, executa o seguinte comando:

git remote set-url origin <SSH URL to your repository>

Os comandos do Git que acedem ao remoto denominado origin usam SSH.

Gerir múltiplas chaves e organizações

P: Estou a usar o Git LFS com o Azure DevOps Services e recebo erros ao puxar ficheiros rastreados pelo Git LFS.

A: Azure DevOps Services atualmente não suporta LFS via SSH. Use HTTPS para se conectar aos repositórios com ficheiros rastreados pelo Git LFS.

P: Como posso usar um local de chave não padrão, ou seja, não ~/.ssh/id_rsa e ~/.ssh/id_rsa.pub?

R: Para usar uma chave armazenada em um local diferente do padrão, execute estas duas tarefas:

1. As chaves devem estar em uma pasta que só você pode ler ou editar. Se a pasta tiver permissões mais amplas, o SSH não usará as chaves.

2. Você deve informar o SSH sobre o local da chave, por exemplo, especificando-o como uma "Identidade" na configuração do SSH:

   Host ssh.dev.azure.com
     IdentityFile ~/.ssh/id_rsa_azure
     IdentitiesOnly yes
   

A IdentitiesOnly yes configuração garante que o SSH não use nenhuma outra identidade disponível para autenticar. Esta configuração é particularmente importante se houver mais do que uma identidade disponível.

P: Tenho várias chaves SSH. Como posso usar a chave SSH correta para Azure DevOps?

R: Geralmente, quando você configura várias chaves para um cliente SSH, o cliente tenta autenticar com cada chave sequencialmente até que o servidor SSH aceite uma.

No entanto, esta abordagem não funciona com o Azure DevOps devido a restrições técnicas relacionadas com o protocolo SSH e a estrutura dos nossos URLs SSH Git. O Azure DevOps aceita a primeira chave fornecida pelo cliente durante a autenticação. Se essa chave for inválida para o repositório solicitado, a solicitação falhará sem tentar outras chaves disponíveis, resultando no seguinte erro:

remote: Public key authentication failed.
fatal: Could not read from remote repository.

Para Azure DevOps, precisas de configurar o SSH para usar explicitamente um ficheiro de chave específico. O procedimento é o mesmo que ao usar uma chave armazenada num local não padrão. Diz ao SSH para usar a chave SSH correta para o host do Azure DevOps.

P: Como posso usar diferentes chaves SSH para diferentes organizações no Azure DevOps?

R: O Azure DevOps aceita a primeira chave que o cliente fornece durante a autenticação. Se essa chave for inválida para o repositório solicitado, a solicitação falhará com o seguinte erro:

remote: Public key authentication failed.
fatal: Could not read from remote repository.

Esta falha ocorre porque todos os URLs do Azure DevOps partilham o mesmo nome de host (ssh.dev.azure.com), tornando impossível que o SSH os distinga por defeito. No entanto, você pode modificar sua configuração SSH para diferenciar entre diferentes organizações, fornecendo chaves distintas para cada uma. Use aliases de host para criar seções separadas Host em seu arquivo de configuração SSH.

# The settings in each Host section are applied to any Git SSH remote URL with a
# matching hostname.
# Generally:
# * SSH uses the first matching line for each parameter name, e.g. if there's
#   multiple values for a parameter across multiple matching Host sections
# * "IdentitiesOnly yes" prevents keys cached in ssh-agent from being tried before
#   the IdentityFile values we explicitly set.
# * On Windows, ~/.ssh/your_private_key maps to %USERPROFILE%\.ssh\your_private_key,
#   e.g. C:\Users\<username>\.ssh\your_private_key.

# Imagine that we have the following two SSH URLs:
# * git@ssh.dev.azure.com:v3/Fabrikam/Project1/fab_repo
#   * For this, we want to use `fabrikamkey`, so we'll create `devops_fabrikam` as
#     a Host alias and tell SSH to use `fabrikamkey`.
# * git@ssh.dev.azure.com:v3/Contoso/Project2/con_repo
#   * For this, we want to use `contosokey`, so we'll create `devops_contoso` as
#     a Host alias and tell SSH to use `contosokey`.
#
# To set explicit keys for the two host aliases and to tell SSH to use the correct
# actual hostname, add the next two Host sections:
Host devops_fabrikam
  HostName ssh.dev.azure.com
  IdentityFile ~/.ssh/private_key_for_fabrikam
  IdentitiesOnly yes

Host devops_contoso
  HostName ssh.dev.azure.com
  IdentityFile ~/.ssh/private_key_for_contoso
  IdentitiesOnly yes

Depois, em vez de usar as URLs reais, diga ao Git que deseja usar essas URLs para cada repositório como remoto, substituindo o nome do host nos controles remotos existentes por devops_fabrikam e devops_contoso respectivamente. Por exemplo, git@ssh.dev.azure.com:v3/Fabrikam/Project1/fab_repo passa a git@devops_fabrikam:v3/Fabrikam/Project1/fab_repo.

Notificações e problemas de conta

P: Que notificações posso receber sobre as minhas chaves SSH?

R: Pode receber algumas notificações sobre as suas chaves SSH.

• Foi adicionada uma nova chave SSH à sua organização.

• Uma chave SSH associada à sua conta expira em 7 dias e não é válida para autenticação.

• Uma chave SSH associada à sua conta expirou e já não é válida para autenticação.

  Exemplo de notificação

  

P: O que devo fazer se acreditar que alguém além de mim está a adicionar chaves SSH à minha conta?

R: Se receber uma notificação de registo de chave SSH que não iniciou, as suas credenciais podem ser comprometidas.

O passo seguinte é investigar se a sua palavra-passe foi comprometida. Alterar a sua palavra-passe é sempre um bom primeiro passo para se defender contra este vetor de ataque. Se for utilizador da Microsoft Entra, fale com o seu administrador para verificar se a sua conta foi usada de uma fonte ou localização desconhecida.

P: O que devo fazer se ainda me for solicitada a minha palavra-passe e GIT_SSH_COMMAND="ssh -v" git fetch mostrar no mutual signature algorithm ou corresponding algo not in PubkeyAcceptedAlgorithms?

R: Algumas distribuições Linux, como o Fedora Linux, aplicam políticas criptográficas que exigem algoritmos de assinatura SSH mais fortes do que a configuração atual do Azure DevOps SSH permite.

Para contornar o problema, adicione o seguinte código à sua configuração SSH (~/.ssh/config):

Host ssh.dev.azure.com vs-ssh.visualstudio.com
   PubkeyAcceptedAlgorithms +ssh-rsa

Se a sua versão OpenSSH só suporta o nome da configuração mais antiga, use PubkeyAcceptedKeyTypes em vez disso.

Use este código como uma solução temporária de compatibilidade. Se possível, atualize a configuração do seu cliente ou servidor SSH e remova esta sobreposição após testes.

Perguntas gerais

P: Posso usar SSH com o Azure DevOps Server?

R: Sim. Para instâncias do Azure DevOps Server auto-hospedadas, use o nome de host do seu servidor na configuração SSH e URLs remotas em vez de ssh.dev.azure.com. Onde este artigo apresentar ssh.dev.azure.com ou vs-ssh.visualstudio.com, substitua pelo nome do anfitrião do seu servidor.

P: Porque é que a minha chave SSH do Azure DevOps Services deixou de funcionar?

R: A autenticação de chaves SSH exige que faça login regular no Azure DevOps Services usando o fluxo completo de autenticação (web). Iniciar sessão uma vez a cada 30 dias é suficiente para muitos utilizadores, mas pode ser necessário iniciar sessão com mais frequência dependendo da configuração do Microsoft Entra. Se a sua chave SSH deixar de funcionar, tente primeiro iniciar sessão na sua organização e preencher o prompt completo de autenticação. Se a tua chave SSH continuar sem funcionar, verifica se expirou.

Conteúdo relacionado

• Criar gestores de credenciais
• Visão geral do Azure DevOps MCP Server
• Gerir ficheiros grandes
• Definir as permissões do repositório do Git