Usar autenticação de chave SSH

Azure DevOps Services | Azure DevOps Server 2020 | Azure DevOps Server 2019 | TFS 2018

Conexão para seus repositórios Git por meio de SSH em macOS, Linux ou Windows para se conectar com segurança usando a autenticação HTTPS. Em Windows, recomendamos o uso do Git Credential Manager ou tokens de acesso pessoal.

Importante

As URLs SSH foram alteradas, mas AS URLs SSH antigas continuarão funcionando. Se você já tiver configurado o SSH, deverá atualizar suas URLs remotas para o novo formato:

  • Verifique quais controles remotos estão usando o SSH executando git remote -v em seu cliente Git.
  • Visite seu repositório na Web e selecione o botão Clonar no canto superior direito.
  • Selecione SSH e copie a nova URL SSH.
  • No cliente Git, execute: git remote set-url <remote name, e.g. origin> <new SSH URL>. Como alternativa, em Visual Studio, vá para o Repositório Configurações e edite seus controles remotos.

Observação

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

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 Azure DevOps e usada para verificar a conexão ssh inicial. A chave privada é mantida segura e segura 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 seguintes plataformas:



Configure o SSH usando a linha de comando. bashé o shell comum no Linux e macOS e a instalação do Git for Windows adiciona um atalho ao Git Bash no menu Iniciar. Outros ambientes de shell funcionarão, mas não serão abordados neste artigo.

Etapa 1: Criar suas chaves SSH

Observação

Se você já tiver criado chaves SSH em seu sistema, ignore esta etapa e vá para configurar chaves SSH.

Os comandos aqui permitirão que você crie novas chaves SSH padrão, substituindo as chaves padrão existentes. Antes de continuar, verifique sua ~/.ssh pasta (por exemplo, /home/jamal/.ssh ou C:\Users\jamal\.ssh) e procure os seguintes arquivos:

  • id_rsa
  • id_rsa.pub

Se esses arquivos existirem, você já criou chaves SSH. Você pode substituir as chaves com os comandos a seguir ou ignorar esta etapa e ir para configurar chaves SSH para reutilizar essas chaves.

Crie suas chaves SSH com o ssh-keygen comando do bash prompt. Esse comando criará uma chave RSA de 3072 bits para uso com SSH. Você pode dar uma frase secreta para sua chave privada quando solicitado – essa frase secreta fornece outra camada de segurança para sua chave privada. Se você der uma frase secreta, certifique-se de configurar o agente SSH para armazenar em cache sua frase secreta para que você não precise inseri-la toda vez que se conectar.

$ ssh-keygen -C "jamal@fabrikam.com"
Generating public/private rsa key pair.
Enter file in which to save the key (/c/Users/jamal/.ssh/id_rsa):
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in /c/Users/jamal/.ssh/id_rsa.
Your public key has been saved in /c/Users/jamal/.ssh/id_rsa.pub.
The key fingerprint is:
SHA256:******************************************* jamal@fabrikam.com
The key's randomart image is:
+---[RSA 3072]----+
|+.   +yX*o .     |
|... ..E+*=o      |
|  ..o.=E=.o      |
|   . * =.o .     |
|    . S o o..    |
|       + .oo     |
|        S+.  .   |
|        ..+.+    |
|          o*..   |
+----[SHA256]-----+

Esse comando produz as duas chaves necessárias para a autenticação SSH: sua chave privada ( id_rsa ) e a chave pública ( id_rsa.pub ). É importante nunca compartilhar o conteúdo da chave privada. Se a chave privada estiver comprometida, os invasores poderão usá-la para enganar os servidores a pensar que a conexão está vindo de você.

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

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

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

    Screenshot that shows the SSH public keys menu item and the user avatar selected in Azure DevOps Services.

  2. Selecione + Nova Chave.

    Accessing Security Configuration in Azure DevOps Services

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

    Importante

    Evite adicionar espaço em branco ou novas linhas ao campo Dados de Chave, pois elas podem fazer com que Azure DevOps Services usem uma chave pública inválida. Ao colar na chave, uma nova linha geralmente é adicionada no final. Certifique-se de remover essa nova linha se ela ocorrer.

    Configuring Public Key in Azure DevOps Services

  4. Dê à chave uma descrição útil (essa descrição será exibida na página de 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 sobre quantas chaves você pode adicionar ao seu perfil de usuário. Observe também que as chaves SSH armazenadas em Azure DevOps expiram após cinco anos. Se a chave expirar, você poderá carregar uma nova chave ou a mesma para continuar acessando Azure DevOps via SSH.

  5. Teste a conexão executando o seguinte comando: ssh -T git@ssh.dev.azure.com. Se tudo estiver funcionando corretamente, você receberá uma resposta que diz: remote: Shell access is not supported. Se não, consulte a seção sobre perguntas e solução de problemas.

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

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

  1. Abra suas configurações de segurança navegando até o portal da Web e selecionando seu avatar no canto superior direito da interface do usuário. Selecione Segurança no menu exibido.

    Accessing User Profile in Azure DevOps Services

  2. Selecione + Nova Chave.

    Accessing Security Configuration in Azure DevOps Services

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

    Observação

    Você pode usar o comando $ cat ~/.ssh/id_rsa.pub para imprimir o conteúdo do arquivo id_rsa.pub no terminal e, em seguida, copiá-lo para sua área de transferência. Se o arquivo de chave pública SSH tiver um nome diferente do código de exemplo, modifique o nome do arquivo para corresponder à configuração atual. Ao copiar sua chave, não adicione nenhuma nova linha ou espaço em branco. Como alternativa, você pode localizar a pasta .ssh oculta, abrir o arquivo em seu editor de texto favorito e copiá-lo para sua área de transferência.

    Importante

    Evite adicionar espaço em branco ou novas linhas ao campo Dados de Chave, pois elas podem fazer com que Azure DevOps Services usem uma chave pública inválida. Ao colar na chave, uma nova linha geralmente é adicionada no final. Certifique-se de remover essa nova linha se ela ocorrer.

    Configuring Public Key in Azure DevOps Services

  4. Dê à chave uma descrição útil (essa descrição será exibida na página de 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 sobre quantas chaves você pode adicionar ao seu perfil de usuário.

  5. Teste a conexão executando o seguinte comando: ssh -T git@ssh.dev.azure.com. Se tudo estiver funcionando corretamente, você receberá uma resposta que diz: remote: Shell access is not supported. Se não, consulte a seção sobre perguntas e solução de problemas.

Etapa 3: Clonar o repositório Git com SSH

Observação

Para se conectar com o SSH de um repositório clonado existente, consulte a atualização dos controles remotos para o SSH.

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

    Azure Repos SSH Clone URL

    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 formato anterior que faz referência ao visualstudio.com formato. Para obter mais informações, consulte Introduçã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
    

O SSH pode exibir a impressão digital SSH do servidor e solicitar que você a verifique. Você deve verificar se a impressão digital exibida corresponde a uma das impressões digitais na página de chaves públicas do SSH .

O SSH exibe essa impressão digital quando se conecta a um host desconhecido para protegê-lo contra ataques man-in-the-middle. Depois de aceitar a impressão digital do host, o SSH não a solicitará novamente, a não ser que a impressão digital seja alterada.

$ git clone git@ssh.dev.azure.com:v3/fabrikam-fiber/FabrikamFiber/FabrikamFiber
Cloning into 'FabrikamFiber'...
The authenticity of host 'ssh.dev.azure.com (65.52.8.37)' can't be established.
RSA key fingerprint is SHA256:********************************************
Are you sure you want to continue connecting (yes/no)? yes
Warning: Permanently added 'ssh.dev.azure.com,65.52.8.37' (RSA) to the list of known hosts.
Enter passphrase for key '/c/Users/jamal/.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 perguntado se deseja continuar se conectando, digite yes. O Git clonará o repositório e configurará o origin controle remoto para se conectar ao SSH para comandos git futuros.

Dica

Para evitar problemas, Windows usuários devem executar um comando para que o Git reutilize a senha de chave SSH.

Perguntas e solução de problemas

P: Depois de executar git clone, recebo o seguinte erro. O que devo fazer?

Host key verification failed. 
fatal: Could not read from remote repository.

Um: Registre manualmente a chave SSH executando: ssh-keyscan -t rsa domain.com >> ~/.ssh/known_hosts

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

Um: Execute o comando a seguir incluído no Git para Windows para iniciar o ssh-agent processo no PowerShell ou no Prompt de Comando do Windows. ssh-agent armazenará em cache sua frase secreta para que você não precise fornecê-la sempre que se conectar ao repositório.

start-ssh-agent.cmd

Se você estiver usando o shell do Bash (incluindo o Git Bash), inicie o ssh-agent com:

eval `ssh-agent`

P: Uso o 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 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 fiz localmente?

Um: 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 a seguir ssh-keygen em sua chave pública usando a bash linha de comando. Você precisará 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 ~/.ssh/id_rsa.pub

Em seguida, você pode comparar a assinatura MD5 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 Services.

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

Um: Você precisará atualizar o origin controle remoto no Git para alterar de uma URL HTTPS para SSH. Depois de ter a URL de clone SSH, execute o seguinte comando:

git remote set-url origin git@ssh.dev.azure.com:v3/fabrikam-fiber/FabrikamFiber/FabrikamFiber

Agora você pode executar qualquer comando git que se conecte a origin.

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

R: Azure DevOps Services atualmente não dá suporte ao LFS por SSH. Use 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?

Um: Para usar chaves criadas em ssh-keygen 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 ao SSH o local das chaves. Você torna o SSH ciente das chaves por meio do ssh-add comando, fornecendo o caminho completo para a chave privada.
ssh-add /home/jamal/.ssh/id_jamal.rsa

No Windows, antes de executarssh-add, você precisará executar o seguinte comando de incluído no Git para Windows:

start-ssh-agent.cmd

Esse comando é executado no PowerShell e no Prompt de Comando. Se você estiver usando o Git Bash, o comando que você precisa usar será:

eval `ssh-agent`

Você pode encontrar ssh-add como parte da distribuição do Git para Windows e também executá-lo em qualquer ambiente de shell no Windows.

No macOS e no Linux, você também deve ter a ssh-agent execução antes de executarssh-add, mas o ambiente de comando nessas plataformas geralmente cuida de começar ssh-agent para você.

P: Tenho várias chaves SSH. Como fazer usar chaves SSH diferentes para servidores ou repositórios SSH diferentes?

Um: Em geral, se você configurar várias chaves para um cliente SSH e se conectar a um servidor SSH, o cliente poderá experimentar as chaves uma de cada vez até que o servidor aceite uma.

No entanto, isso não funciona com Azure DevOps por motivos técnicos relacionados ao protocolo SSH e como nossas URLs do Git SSH são estruturadas. Azure DevOps aceitará cegamente 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.

Para Azure DevOps, você precisará configurar o SSH para usar explicitamente um arquivo de chave específico. Uma maneira de fazer isso para editar seu ~/.ssh/config arquivo (por exemplo, /home/jamal/.ssh ou C:\Users\jamal\.ssh) da seguinte maneira:

# 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.

# Most common scenario: to use the same key across all hosted Azure DevOps
# organizations, add a Host entry like this:
Host ssh.dev.azure.com
  IdentityFile ~/.ssh/your_private_key
  IdentitiesOnly yes

# This model will also work if you still use the older SSH URLs with a
# hostname of vs-ssh.visualstudio.com:
Host vs-ssh.visualstudio.com
  IdentityFile ~/.ssh/your_private_key
  IdentitiesOnly yes

# Less common scenario: if you need different keys for different organizations,
# you'll need to use host aliases to create separate Host sections.
# This is because all hosted Azure DevOps URLs have the same hostname
# (ssh.dev.azure.com), so SSH has no way to distinguish them by default.
#
# 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
#
# Then, instead of using the real URLs, tell Git you want to use these URLs:
# * git@devops_fabrikam:v3/Fabrikam/Project1/fab_repo
# * git@devops_contoso:v3/Contoso/Project2/con_repo
#

# At the end of the file, you can put global defaults for other SSH hosts you
# may connect to.  Note that "*" also matches any hosts that match the sections
# above, and remember that SSH uses the first matching line for each parameter name.
Host *
# 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.

# Say your on-premises Azure DevOps Server instance has SSH URLs like this:
#   ssh://someHost:22/someCollection/some_project/_git/some_repo
# Add the following Host section:
Host someHost
  IdentityFile ~/.ssh/your_private_key
  IdentitiesOnly yes

# At the end of the file, you can put global defaults for other SSH hosts you
# may connect to.  Note that "*" also matches any hosts that match the sections
# above, and remember that SSH uses the first matching line for each parameter name.
Host *

P: Como fazer corrigir erros que mencionam "nenhum método de troca de chaves correspondente encontrado"?

Um: Git para Windows 2.25.1 fornecido com uma nova versão do OpenSSH que removeu alguns protocolos de troca de chaves por padrão. Especificamente, diffie-hellman-group14-sha1 foi identificado como problemático para alguns clientes Azure DevOps Server e TFS. Você pode contornar o problema adicionando o seguinte à configuração do SSH (~/.ssh/config):

Host <your-azure-devops-host>
    KexAlgorithms +diffie-hellman-group14-sha1

Substitua <your-azure-devops-host> pelo nome do host do servidor Azure DevOps ou TFS, como tfs.mycompany.com.

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

Um: Sempre que você registrar uma nova chave SSH com Azure DevOps Services, receberá uma notificação por email informando que uma nova chave SSH foi adicionada à sua conta.

SSH notification example

P: O que eu faço se eu acredito que alguém além de mim está adicionando chaves SSH na minha conta?

Um: Se você receber uma notificação de uma chave SSH sendo registrada e não a carregar manualmente no serviço, suas credenciais poderão ter sido comprometidas.

A próxima etapa seria investigar se sua senha foi 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 Azure Active Directory, 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?

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

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

Host ssh.dev.azure.com
  PubkeyAcceptedKeyTypes=ssh-rsa

Substitua ssh.dev.azure.com pelo nome correto do host se você usar Azure DevOps Server.