Usar a autenticação de chave SSH

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

Use o SSH no macOS, Linux ou Windows para se autenticar com segurança em repositórios Git do Azure Repos 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. Você compartilha a chave pública com Azure DevOps para verificar a conexão SSH inicial. Mantenha a chave privada segura e segura em seu sistema.

Configurar a autenticação de chave SSH

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

Se você precisar apenas do caminho mais rápido, conclua a Etapa 1, a Etapa 2 e a Etapa 3 em ordem e use solucionar problemas de autenticação SSH somente se um comando falhar.

As etapas a seguir abrangem a configuração da autenticação de chave SSH nas plataformas a seguir usando a linha de comando (também chamada shell):

• Linux
• macOS
• Sistemas Windows que executam Git para Windows

Etapa 1: crie suas chaves SSH

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

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

ssh-keygen -t rsa -b 3072

A saída do comando deve exibir a seguinte saída (onde username está 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):

Pressione Enter para aceitar o padrão ou especifique um caminho e/ou nome de arquivo em que você deseja que suas chaves sejam geradas. Neste ponto, é solicitado que você use uma frase secreta para criptografar seus arquivos de chave privada. A frase secreta pode estar vazia, mas não é recomendada. A frase secreta adiciona outra camada de proteção para sua chave privada se o arquivo for 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 você tem um par de chaves RSA público/privado no local especificado. Os .pub arquivos são chaves públicas e os arquivos sem uma 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

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

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

1. Abra as 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 exibido.

   

2. Selecione + Nova Chave.

   

3. Copie o conteúdo da chave pública (por exemplo, id_rsa.pub) que você gerou no campo Dados da Chave Pública.

   Importante

   Evite adicionar espaços extras ou quebras de linha no meio do valor da chave, pois elas podem tornar a chave inválida. Se, ao colar, forem adicionados artefatos de formatação, remova-os antes de salvar.

   

4. Dê à chave uma descrição útil (essa descrição é exibida na página chaves públicas SSH do seu perfil) para que você possa se lembrar dela mais tarde. Selecione Salvar para armazenar a chave pública. Depois de 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 a respeito de quantas chaves você pode adicionar ao seu perfil de usuário.

   Observação

   A política de organização pode impor a expiração da chave SSH. Para obter mais informações, consulte Alterar as políticas de conexão e segurança do aplicativo para sua organização.

5. Na página Visão geral das chaves públicas SSH, as impressões digitais do servidor são exibidas. Anote a impressão digital SHA256 a ser usada quando você se conectar pela primeira vez ao Azure DevOps via SSH.

   

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

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

   Se está se conectando pela primeira vez, você verá o seguinte:

   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 SSH . Continue somente se os valores corresponderem.

7. Insira yes para continuar. Se tudo estiver configurado corretamente, você verá o seguinte:

    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 seção sobre Perguntas e solução de problemas.

Etapa 3: Clonar o repositório Git usando SSH

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

   

   Observação

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

2. Execute git clone no prompt de comando.

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

   Se você não estiver usando um agente SSH, será solicitado que você insira sua senha:

   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 você for solicitado a verificar uma impressão digital, leia Step 2: Adicionar a chave pública ao Azure DevOps novamente. Para outros problemas, leia a seção sobre Perguntas e solução de problemas.

Usar a IA para trabalhar com repositórios autenticados em SSH

Se você usar repositórios Git com GitHub Copilot ou o servidor MCP Azure DevOps, poderá usar prompts de linguagem natural para validar a configuração do SSH e diagnosticar problemas de autenticação.

Solução de problemas e perguntas comuns

Use as seções a seguir para encontrar o problema que corresponde ao problema de configuração do SSH.

• Se a chave expirou ou é inválida, comece com chaves expiradas ou inválidas.
• Se o SSH não se conectar, comece com falhas de conexão comuns.
• Se for solicitado repetidamente que você digite uma senha secreta, consulte primeiro Problemas com o agente SSH e a senha secreta.
• Se você estiver usando várias chaves ou organizações, vá para Gerenciar várias chaves e organizações.
• Se você precisar de notificação ou orientação de conta, acesse Notificações e problemas de conta.

Chaves expiradas ou inválidas

P: Minha chave SSH expirou. O que devo fazer?

A: Siga as etapas anteriores para criar e fazer upload de uma nova chave SSH.

Como uma opção alternativa, um administrador de coleção de Project pode desabilitar a política que valida a data de validade da chave SSH. Por padrão, a política de validação da expiração da chave SSH está habilitada. Para obter mais informações, consulte as políticas de chave SSH.

Você recebe automaticamente uma notificação sete dias antes e quando sua chave expira. Junto com essas notificações, você verá 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 conexão

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

A: Você 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 você modificou a configuração SSH para reduzir as configurações de segurança específicas do Azure DevOps, adicionando o seguinte ao arquivo ~/.ssh/config (%UserProfile%\.ssh\config no Windows):

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

Remova essas linhas agora e verifique se rsa-sha2-256 e rsa-sha2-512 são permitidas.

Para obter mais informações, confira a postagem no blog.

Essa correção é a correção canônica para avisos preteridos ssh-rsa e erros sem suporte ssh-rsa . Use-o como sua primeira etapa para esses cenários.

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

A: Você pode encontrar vários problemas:

• Uso de ssh-rsa incompatível

  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 correção descrita na pergunta anterior sobre os avisos de ssh-rsa: remova qualquer sobrescrita de HostkeyAlgorithms +ssh-rsa e use rsa-sha2-256 e/ou rsa-sha2-512.

• Nenhuma chave de host correspondente

  Esse problema não deve ocorrer no serviço de Azure DevOps ou em versões mais recentes de Azure DevOps Server, conforme mencionado na postagem blog.

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

  Modifique a configuração SSH para rebaixar as configurações de segurança do Azure DevOps adicionando o seguinte ao arquivo ~/.ssh/config (%UserProfile%\.ssh\config no Windows):

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

  Use essa solução alternativa apenas para cenários de compatibilidade herdados, normalmente para configurações de Azure DevOps Server auto-hospedadas mais antigas. Para Azure DevOps Services, mantenha padrões seguros e evite substituições persistentesssh-rsa.

  Importante

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

• Nenhum MAC correspondente

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

  Modifique a configuração SSH para rebaixar as configurações de segurança do Azure DevOps adicionando o seguinte ao arquivo ~/.ssh/config (%UserProfile%\.ssh\config no 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 configuração SSH para rebaixar as configurações de segurança do Azure DevOps adicionando o seguinte ao arquivo ~/.ssh/config (%UserProfile%\.ssh\config no 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 é desabilitado por padrão na versão 6.9 do OpenSSH e diffie-hellman-group14-sha1 na versão 8.2.

Problemas de senha e agente SSH

P: O agente SSH não está em execução ou minha chave não está carregada. O que devo fazer?

A: Se a sua chave existir, mas o SSH ainda solicitar uma senha sempre, ou se a clonagem falhar depois que a chave for criada com êxito, verifique se o agente SSH está em execução e se a sua chave foi carregada.

Use o seguinte comando para ver quais identidades o agente carregou no momento:

ssh-add -l

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

ssh-add ~/.ssh/id_rsa

No Windows, se você estiver usando o PowerShell com o agente OpenSSH interno, verifique se o ssh-agent serviço está em execução antes de adicionar a chave. Se você usar o Git Bash ou outro cliente SSH, consulte a documentação desse cliente para iniciar seu agente e carregar chaves.

Se você preferir não usar um agente, o SSH ainda poderá funcionar, mas você será solicitado a usar a frase secreta com mais frequência.

P: Como fazer com que o Git se lembre da frase secreta da minha chave?

A: Use um agente SSH. Linux, macOS e Windows (começando com Windows 10 (build 1809) ou usando o Git para Windows com Git Bash) todos vêm com um Agente SSH. O Agente SSH pode armazenar em cache suas chaves SSH para uso repetido. Consulte o manual do fornecedor SSH para conferir detalhes sobre como usá-lo.

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

R: Sim. Carregue a chave privada com o PuTTYgen, vá para o menu Conversões e selecione Exportar chave OpenSSH. Salve o arquivo de chave privada e, em seguida, siga a pergunta posterior neste artigo sobre como usar um local de chave não padrão. Copie sua chave pública diretamente da janela PuTTYgen e cole no campo Dados de Chave em 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?

A: Verifique a impressão digital da chave pública que você enviou, comparando-a com a exibida no seu perfil. Execute o comando a seguir ssh-keygen em sua chave pública usando a linha de comando. Altere o caminho e o nome do arquivo de chave pública se não estiver usando os valores que são padrão.

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

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

Em seguida, compare a assinatura com a do seu perfil. Essa verificação será útil se você tiver problemas de conexão ou tiver preocupações sobre colar incorretamente a chave pública no campo Dados de Chave ao adicionar a chave a Azure DevOps.

P: Como posso começar a usar o SSH em um repositório em que estou usando HTTPS no momento?

Um: Atualize o origin remoto no Git para alterar de uma URL HTTPS para SSH. Depois de obter a URL de clone SSH, execute o seguinte comando:

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

Os comandos git que acessam o remoto chamado origin usam SSH.

Gerenciar várias chaves e organizações

P: Estou usando o Git LFS com Azure DevOps Services e recebo erros ao efetuar pull de arquivos rastreados pelo Git LFS.

A: Azure DevOps Services atualmente não dá suporte ao LFS por SSH. Use o HTTPS para se conectar a repositórios com arquivos controlados 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 somente você possa ler ou editar. Se a pasta tem permissões mais amplas, o SSH não usa as chaves.

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

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

A configuração IdentitiesOnly yes garante que o SSH não usa nenhuma outra identidade disponível para autenticação. Essa configuração é particularmente importante se mais de uma identidade estiver 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 fazer a autenticação com cada chave em sequência até que o servidor SSH aceite uma delas.

No entanto, essa abordagem não funciona com Azure DevOps devido a restrições técnicas relacionadas ao protocolo SSH e à estrutura de nossas URLs SSH do Git. Azure DevOps aceita a primeira chave fornecida pelo cliente durante a autenticação. Se essa chave é inválida para o repositório solicitado, a solicitação falha 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, você precisa configurar o SSH para usar explicitamente um arquivo de chave específico. O procedimento é o mesmo que ao usar uma chave armazenada em um local não padrão. Diga ao SSH para usar a chave SSH correta para o host Azure DevOps.

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

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

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

Essa falha ocorre porque todas as URLs Azure DevOps compartilham o mesmo nome de host (ssh.dev.azure.com), tornando impossível para o SSH distinguir entre elas por padrão. No entanto, você pode modificar sua configuração de SSH para diferenciar entre organizações distintas fornecendo chaves diferentes para cada uma delas. Use aliases de host para criar seções Host separadas no 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

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

Notificações e problemas de conta

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

Um: Você pode receber algumas notificações sobre suas chaves SSH.

• Uma nova chave SSH foi adicionada à 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 não é mais válida para autenticação.

  Notificação de exemplo

  

P: O que fazer se eu achar que alguém diferente de mim está adicionando chaves SSH na minha conta?

Um: Se você receber uma notificação de registro de chave SSH que não iniciou, suas credenciais poderão ser comprometidas.

A próxima etapa é investigar se sua senha está comprometida. Alterar sua senha é sempre uma boa primeira etapa para se defender desse vetor de ataque. Se você for um usuário Microsoft Entra, converse com o administrador para verificar se sua conta foi usada de uma origem ou local desconhecido.

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

Um: Algumas distribuições do Linux, como Fedora Linux, impõem políticas de criptografia que exigem algoritmos de assinatura SSH mais fortes do que a configuração atual do SSH do Azure DevOps permite.

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

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

Se sua versão do OpenSSH oferecer suporte apenas ao nome de configuração mais antigo, use PubkeyAcceptedKeyTypes em vez disso.

Use esse código como uma solução alternativa de compatibilidade temporária. Se possível, atualize a configuração do cliente ou servidor SSH e remova essa substituição após o teste.

Perguntas gerais

P: Posso usar o SSH com Azure DevOps Server?

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

P: Por que minha chave SSH dos Serviços de Azure DevOps parou de funcionar?

R: A autenticação de chave SSH exige que você entre regularmente no Azure DevOps Services usando o fluxo de autenticação completo (Web). Entrar uma vez a cada 30 dias é suficiente para muitos usuários, mas talvez seja necessário entrar com mais frequência dependendo da configuração do Microsoft Entra. Se a chave SSH parar de funcionar, primeiro tente entrar em sua organização e concluir o prompt de autenticação completo. Se sua chave SSH ainda não funcionar, verifique se ela expirou.

Conteúdo relacionado

• Configurar gerenciadores de credenciais
• Visão geral do Servidor MCP do Azure DevOps
• Gerenciar arquivos grandes
• Definir permissões do repositório Git