Compartilhar via

Usar a autenticação de chave SSH

  • Artigo

Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019

Você pode se conectar aos repositórios Git por meio de SSH no macOS, Linux ou Windows para se conectar com segurança ao Azure DevOps.

Importante

As URLs SSH foram alteradas, mas as URLs SSH antigas continuam funcionando. Se você já configurou o SSH, atualize suas URLs remotas para o novo formato:

As URLs SSH atualizadas começam com ssh.dev.azure.com. As URLs anteriores usam vs-ssh.visualstudio.com.

  • Verifique quais remotos estão usando o SSH. Em vez disso, execute git remote -v no shell ou use um cliente GUI.
  • Visite seu repositório na Web e selecione Clonar.
  • Selecione SSH e copie a nova URL SSH.
  • Em seu shell, execute git remote set-url <remote name> <new SSH URL> para cada controle remoto de um repositório que você deseja atualizar. Como alternativa, use um cliente GUI para atualizar as URLs remotas.

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. A chave pública é compartilhada com o Azure DevOps e usada para verificar a conexão SSH inicial. A chave privada é mantida segura e protegida em seu sistema.

Configurar a autenticação de chave SSH

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):

Observação

A partir do Visual Studio 2017, o SSH pode ser usado para se conectar aos repositórios Git do Azure DevOps.

Dica

No Windows, recomendamos usar o Gerenciador de credenciais do Git ou os Tokens de acesso pessoal.

Etapa 1: crie suas chaves SSH

Observação

Se você já criou chaves SSH RSA em seu sistema, ignore esta etapa e configure suas chaves SSH. Para verificar isso, acesse o diretório inicial e examine a pasta .ssh (%UserProfile%\.ssh\ no Windows ou ~/.ssh/ no Linux, macOS e Windows com Git Bash). Se você vir dois arquivos nomeados id_rsa e id_rsa.pub respectivamente, continue com a configuração de suas chaves SSH.

Para usar a autenticação baseada em chave, primeiro você precisa gerar pares de chaves pública/privada para o cliente. ssh-keygen.exe é usado para gerar arquivos de chave e os algoritmos DSA, RSA, ECDSA ou Ed25519 podem ser especificados. Se nenhum algoritmo for especificado, o Ed25519 será usado.

Observação

O único tipo de chave SSH compatível com o Azure DevOps é RSA.

Para gerar arquivos de chave usando o algoritmo RSA compatível com Azure DevOps (RSA-SHA2-256 ou RSA-SHA2-512), execute um dos seguintes comandos em um PowerShell ou em outro shell, como bash em seu cliente:

ssh-keygen -t rsa-sha2-256

Ou

ssh-keygen -t rsa-sha2-512

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):

Você pode pressionar Enter para aceitar o padrão ou especificar um caminho e/ou nome de arquivo em que deseja que as chaves sejam geradas. Neste ponto, é solicitado que você use uma frase secreta para criptografar seus arquivos de chave privada. A senha pode estar vazia, mas não recomendada. A frase secreta funciona com o arquivo de chave para fornecer autenticação de dois fatores.

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ública/privada no local especificado. Os arquivos .pub 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

Importante

Nunca compartilhe o conteúdo da chave privada. Se a chave privada estiver comprometida, os invasores poderão usá-la para enganar os servidores, fazendo parecer que a conexão vem de você. Os arquivos de chave privada são equivalentes a uma senha e devem ser protegidos da mesma maneira.

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

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

Observação

Você precisa repetir essa operação para cada organização à qual você tem acesso e deseja usar o SSH.

  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.

    Captura de tela que mostra o item de menu de chaves públicas do SSH e o avatar do usuário selecionado no Azure DevOps.

  2. Selecione + Nova Chave.

    Captura de tela mostrando o acesso à Configuração de Segurança no Azure DevOps.

  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ço em branco ou novas linhas ao campo Dados de Chave, pois elas podem fazer com que o Azure DevOps use uma chave pública inválida. Ao colar na chave, uma nova linha geralmente é adicionada no final. Certifique-se de retirar essa nova linha se ela aparecer.

    Captura de tela mostrando a configuração de uma Chave Pública no Azure DevOps.

  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. Observe também que as chaves SSH armazenadas no Azure DevOps expiram após um ano. Se a chave expirar, você poderá carregar uma nova chave ou a mesma para continuar acessando o Azure DevOps via SSH.

  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 para usar quando se conectar pela primeira vez ao Azure DevOps via SSH.

    Captura de tela do acesso à configuração de segurança no Azure DevOps Services.

  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 a impressão digital com a impressão digital SHA256 exibida na página Chaves públicas SSH mencionadas anteriormente. Prossiga somente se 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: clone o repositório Git com SSH

Observação

Para usar o SSH com um repositório clonado anteriormente via HTTPS, consulte atualizar seus controles remotos para 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.

    Captura de tela mostrando a URL clonada de SSH do Azure Repos

    Observação

    Com Azure DevOps Services, o formato da URL do projeto é dev.azure.com/{your organization}/{your project}. No entanto, ainda há suporte para o visualstudio.comformato anterior que faz referência ao formato. Para obter mais informações, consulte Apresentando o Azure DevOps, Alternar 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 for solicitado que você verifique uma impressão digital, leia a Etapa 2: Adicionar a chave pública ao Azure DevOps novamente. Para outros problemas, leia a seção sobre Perguntas e solução de problemas.

Dica

Para aproveitar ao máximo o SSH, é comum usar um agente SSH para gerenciar suas chaves SSH. No entanto, a configuração de um agente está além do escopo deste artigo.

Perguntas e solução de problemas

R: Há duas mensagens de aviso diferentes que você pode ver:

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ê tiver modificado sua configuração SSH para fazer downgrade das 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

Remova essas linhas agora e certifique-se de que há permissão para rsa-sha2-256 e/ou rsa-sha2-512.

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

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

R: Há vários problemas diferentes que você poderia enfrentar:

  • Uso de ssh-rsa não aceito

    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.

    Se você tiver modificado sua configuração SSH para fazer downgrade das 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

    Remova essas linhas agora e certifique-se de que há permissão para rsa-sha2-256 e/ou rsa-sha2-512.

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

  • Nenhuma chave de host correspondente

    Este problema não deve acontecer no Azure DevOps Service nem nas versões mais recentes do Azure DevOps Server, conforme mencionado na postagem de blog.

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

    Modifique sua configuração SSH para fazer downgrade das 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

    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.

  • Sem conciliação de MAC

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

    Modifique sua configuração SSH para fazer downgrade das 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 sua configuração SSH para fazer downgrade das 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 foi desabilitado por padrão na versão 6.9 do OpenSSH e diffie-hellman-group14-sha1 na versão 8.2.

Dica

Para instâncias auto-hospedadas do Azure DevOps Server e do TFS, use o nome do host apropriado na linha Host em vez de ssh.dev.azure.com vs-ssh.visualstudio.com.

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

R: Você pode usar um agente SSH. Linux, macOS e Windows (começando com o Windows 10 (build 1809) ou usando o Git para Windows com Git Bash) são fornecidos com um Agente SSH. O Agente SSH pode ser usado para 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 o 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 siga as etapas para configurar chaves 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?

R: Você pode verificar a impressão digital da chave pública carregada com a exibida em seu perfil por meio da execução de comando ssh-keygen a seguir 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.

Observação

A partir de agosto/setembro de 2024, estamos migrando de hashes MD5 para SHA-256. Pode ser necessário escolher a função correta durante o período de transição.

ssh-keygen -l -E md5 -f <path_to_your_public_key> -- use this for MD5 fingerprints
ssh-keygen -l -E sha256 -f <path_to_your_public_key> -- use this for SHA-256 fingerprints

Você pode então comparar 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 na chave pública no campo Dados de Chave ao adicionar a chave ao Azure DevOps.

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

R: Você precisará atualizar o remoto origin no Git para mudar de uma URL HTTPS para SSH. Assim que tiver a URL do clone SSH, execute o seguinte comando:

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

Os comandos do Git que acessam o remoto chamado origin usam o SSH.

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

R: no momento, o Azure DevOps Services não é compatível com o LFS sobre 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 o 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 o Azure DevOps devido a restrições técnicas relacionadas ao protocolo SSH e à estrutura das nossas URLs SSH do Git. O 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 sem tentar outras chaves disponíveis, resultando no seguinte erro:

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

No 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 do Azure DevOps.

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

R: O Azure DevOps aceita cegamente 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 do 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 devops_fabrikam e devops_contoso, respectivamente, por. Por exemplo, git@ssh.dev.azure.com:v3/Fabrikam/Project1/fab_repo se tornaria git@devops_fabrikam:v3/Fabrikam/Project1/fab_repo.

P: Quais notificações posso receber a respeito de minhas chaves SSH?

R: Sempre que registra uma nova chave SSH com o Azure DevOps Services, você recebe uma notificação por email informando quando uma nova chave SSH é adicionada à sua conta.

Exemplo de notificação SSH

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

R: Se você receber uma notificação de registro de chave SSH que não foi você quem iniciou, talvez suas credenciais estejam comprometidas.

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

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?

R: Algumas distribuições do Linux, como Fedora Linux, possuem políticas de criptografia que exigem algoritmos de assinatura SSH mais fortes do que os compatíveis com o Azure DevOps (a partir de janeiro de 2021). Há uma solicitação de recurso aberta para adicionar esse suporte.

Você pode contornar o problema adicionando o código seguinte à sua configuração de SSH (~/.ssh/config):

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

Dica

Para instâncias auto-hospedadas do Azure DevOps Server e do TFS, use o nome do host apropriado na linha Host em vez de ssh.dev.azure.com vs-ssh.visualstudio.com.