Usar a autenticação de chave SSH

  • Artigo

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

Conecte-se aos seus repositórios Git por meio do SSH no macOS, Linux ou Windows com segurança usando autenticação HTTPS.

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 RSA 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, execute o seguinte comando de um PowerShell ou outro shell, como bash em seu cliente:

ssh-keygen

A saída do comando deve exibir a seguinte saída (onde username é substituída pelo 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, você será solicitado a usar uma frase secreta para criptografar seus arquivos de chave privada. A frase secreta pode ficar vazia, mas isso não é recomendado. 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 de visão geral, uma nota é exibida na parte superior que contém as impressões digitais do servidor. Anote-os porque eles serão necessários quando você 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 esta foi a primeira vez que você deve 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 a impressão digital fornecida com as impressões digitais oferecidas na página de configurações mencionada acima. Prossiga somente se corresponderem!

    Se tudo estiver configurado corretamente, a saída deverá ter esta aparência:

    remote: Shell access is not supported.

    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

    Agora você deve ser solicitado a inserir sua frase secreta para sua chave SSH antes de continuar, a menos que ela seja gerenciada por um Agente SSH:

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

or

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.

Você pode ter modificado anteriormente sua configuração SSH para fazer downgrade de suas configurações de segurança para o Azure DevOps adicionando o seguinte ao seu 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 rsa-sha2-256 e/ou rsa-sha2-512 são permitidas.

Para obter mais detalhes, consulte a postagem de blog.

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

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

  • Uso de SSH-RSA não suportado

    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.

    Você pode ter modificado anteriormente sua configuração SSH para fazer downgrade de suas configurações de segurança para o Azure DevOps adicionando o seguinte ao seu 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 rsa-sha2-256 e/ou rsa-sha2-512 são permitidas.

    Para obter mais detalhes, consulte a postagem de blog.

  • Nenhuma chave de host correspondente

    Isso não deve acontecer nem no Serviço de DevOps do Azure nem nas versões mais recentes do Servidor de DevOps do Azure, 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 para isso. 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 obter 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. 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ê poderá 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 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 alterar 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 agora usarão 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 tiver permissões mais amplas, o SSH não usará 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 usará nenhuma outra identidade disponível para autenticação. Isso é especialmente 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, 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 o Azure DevOps por motivos técnicos relacionados ao protocolo SSH e a como são estruturadas nossas URLs SSH do Git. O Azure DevOps aceitará cegamente a primeira chave que o cliente fornecer 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 devido ao seguinte erro:

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

No Azure DevOps, você precisará 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. Basta dizer 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 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.

No entanto, você pode modificar sua configuração SSH para diferenciar entre diferentes organizações e fornecer chaves diferentes para cada uma. Para fazer isso, você precisará usar aliases de host para criar seções Host separadas em sua configuração de SSH. Isso ocorre porque todas as URLs do Azure DevOps hospedadas têm o mesmo nome de host (ssh.dev.azure.com), portanto, o SSH não tem como distingui-las por padrão.

# 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 você registrar uma nova chave SSH com o Azure DevOps Services, receberá uma notificação por email informando que uma nova chave SSH foi 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 uma chave SSH que está sendo registrada e não a carregou manualmente no serviço, suas credenciais podem 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 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.