Использование проверки подлинности с ключом SSH

Службы Azure DevOps | Azure DevOps Server | Azure DevOps Server 2022

Используйте SSH в macOS, Linux или Windows для безопасной проверки подлинности в репозиториях Git Azure Repos в Azure DevOps.

В этой статье показано, как создать пару ключей RSA, добавить открытый ключ в профиль и клонировать репозитории с помощью SSH.

Предпосылки

Как работает проверка подлинности ключа SSH

Проверка подлинности открытого ключа SSH работает с асимметричной парой созданных ключей шифрования. Вы передаёте публичный ключ Azure DevOps для проверки исходного SSH-подключения. Храните закрытый ключ в безопасности в вашей системе.

Настройка проверки подлинности ключа SSH

Чтобы использовать SSH с Azure Repos, создайте пару ключей RSA, добавьте открытый ключ в профиль Azure DevOps, проверьте отпечатки сервера, а затем клонируйте или обновите репозиторий, чтобы использовать URL-адрес SSH.

Если вам нужен только самый быстрый путь, выполните шаг 1, шаг 2 и шаг 3, а затем используйте проверку подлинности SSH только в случае сбоя команды.

Ниже описана настройка проверки подлинности ключа SSH на следующих платформах с помощью командной строки (также называемой shell):

• Линукс
• macOS
• Системы Windows, на которых установлено Git для Windows

Шаг 1. Создание ключей SSH

Чтобы использовать проверку подлинности на основе ключей, сначала необходимо создать пару открытых и закрытых ключей для клиента. OpenSSH может создавать несколько типов ключей, но Azure DevOps поддерживает ключи RSA для проверки подлинности SSH.

Чтобы создать пару ключей RSA для Azure DevOps, выполните следующую команду из PowerShell или другой оболочки, например bash на клиенте:

ssh-keygen -t rsa -b 3072

Результат команды должен отображать следующее (где username обозначает ваше имя пользователя):

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

Нажмите клавишу ВВОД , чтобы принять значение по умолчанию или указать путь и /или имя файла, в котором нужно создать ключи. На этом этапе вам будет предложено использовать парольную фразу для шифрования файлов закрытого ключа. Парольная фраза может быть пустой, но не рекомендуется. Парольная фраза обеспечивает дополнительный уровень защиты вашего закрытого ключа, если файл станет доступен посторонним.

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]-----+

Теперь у вас есть пара открытого и закрытого ключей RSA в указанном вами расположении. Файлы .pub являются открытыми ключами, и файлы без расширения являются закрытыми ключами:

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

Шаг 2. Добавление открытого ключа в Azure DevOps

Свяжите открытый ключ, созданный на предыдущем шаге, с идентификатором пользователя.

1. Откройте параметры безопасности, перейдя на веб-портал и выбрав значок рядом с аватаром в правом верхнем углу пользовательского интерфейса. Выберите открытые ключи SSH в появившемся меню.

   

2. Щелкните + Создать ключ.

   

3. Скопируйте содержимое открытого ключа (например, id_rsa.pub), которое вы сгенерировали, в поле Данные открытого ключа.

   Внимание

   Избегайте добавления дополнительных пробелов или разрывов строк в середине значения ключа, так как они могут сделать ключ недопустимым. Если при вставке появляются артефакты форматирования, удалите их перед тем, как сохранить.

   

4. Присвойте ключу полезное описание (это описание отображается на странице открытых ключей SSH для профиля), чтобы вы могли запомнить его позже. Нажмите кнопку "Сохранить", чтобы сохранить открытый ключ. После сохранения ключ нельзя изменить. Ключ можно удалить или создать новую запись для другого ключа. Нет ограничений на количество ключей, которые можно добавить в профиль пользователя.

   Примечание.

   Политика организации может принудительно устанавливать срок действия ключей SSH. Дополнительные сведения см. в разделе "Изменение подключений к приложению и политик безопасности для организации".

5. На странице обзора открытых ключей SSH отображаются отпечатки пальцев сервера. Запишите отпечаток SHA256, используемый при первом подключении к Azure DevOps через SSH.

   

6. Проверьте подключение, выполнив следующую команду:

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

   Если вы подключаетесь в первый раз, вы получите следующие выходные данные:

   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])?
   

   Сравните этот отпечаток с отпечатком SHA256, показанным на странице открытых ключей SSH . Продолжайте только в том случае, если значения совпадают.

7. Введите yes , чтобы продолжить. Если все настроено правильно, выходные данные должны выглядеть следующим образом:

    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
   

   Если нет, см. раздел "Вопросы и устранение неполадок".

Шаг 3. Клонирование репозитория Git с помощью SSH

1. Скопируйте URL-адрес клона SSH на веб-портале. В этом примере URL-адрес клона SSH предназначен для репозитория в организации с именем fabrikam-fibre, как указано первой частью URL-адреса после dev.azure.com.

   

   Примечание.

   При использовании служб Azure DevOps формат URL-адреса проекта — dev.azure.com/{your organization}/{your project}. Однако предыдущий формат, ссылающийся на visualstudio.com формат, по-прежнему поддерживается. Дополнительные сведения см. в разделе Introducing Azure DevOps, переключение существующих организаций на использование нового URL-адреса доменного имени.

2. Выполните git clone в командной строке.

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

   Если вы не используете агент 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.
   

   Если вместо этого появится запрос на проверку отпечатка пальца, прочитайте Step 2: добавьте открытый ключ в Azure DevOps еще раз. Для других проблем ознакомьтесь с разделом " Вопросы и устранение неполадок".

Использование ИИ для работы с репозиториями, прошедшими проверку подлинности SSH

Если вы используете репозитории Git с GitHub Copilot или Azure DevOps MCP Server, вы можете использовать запросы естественного языка для проверки настройки SSH и диагностики проблем с проверкой подлинности.

Устранение неполадок и распространенных вопросов

Используйте следующие разделы, чтобы найти проблему, соответствующую проблеме установки SSH.

• Если срок действия вашего ключа истёк или сам ключ недействителен, начните с раздела Просроченные или недействительные ключи.
• Если SSH не удается подключиться, начните с распространенных сбоев подключения.
• Если вы неоднократно запрашиваете парольную фразу, начните с проблем агента SSH и парольной фразы.
• Если вы используете несколько ключей или организаций, перейдите к управлению несколькими ключами и организациями.
• Если вам нужны уведомления или рекомендации по учетной записи, перейдите к уведомлениям и проблемам с учетной записью.

Просроченные или недействительные ключи

Вопрос. Срок действия ключа SSH истек. Что делать?

A: Выполните описанные выше действия, чтобы создать и отправить новый ключ SSH.

В качестве альтернативного варианта администратор коллекции Project может отключить политику, которая проверяет дату окончания срока действия ключа SSH. По умолчанию включена политика проверки истечения срока действия ключа SSH. Дополнительные сведения см. в политиках ключей SSH.

Вы автоматически получаете уведомление за семь дней до истечения срока действия ключа. Наряду с этими уведомлениями вы увидите следующее сообщение:

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.

Распространенные сбои подключения

Вопрос. Я вижу предупреждения, связанные с ssh-rsa. Что делать?

A: Может появиться одно из следующих предупреждений:

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.

Или

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.

Если вы изменили конфигурацию SSH, чтобы понизить настройки безопасности для Azure DevOps, добавив следующее в файл ~/.ssh/config (%UserProfile%\.ssh\config в Windows):

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

Удалите эти строки сейчас и убедитесь, что rsa-sha2-256 и rsa-sha2-512 разрешены.

Дополнительные сведения см. в этой записи блога.

Этот способ устранения является стандартным решением для предупреждений о том, что ssh-rsa устарел, и ошибок о том, что ssh-rsa не поддерживается. Используйте его в качестве первого шага для этих сценариев.

Вопрос. SSH не может установить подключение. Что делать?

A: Вы можете столкнуться с несколькими различными проблемами:

• Использование неподдерживаемого ssh-rsa

  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.
  

  Примените то же исправление, описанное в предыдущем вопросе о предупреждениях ssh-rsa: удалите все переопределения HostkeyAlgorithms +ssh-rsa и используйте rsa-sha2-256 и/или rsa-sha2-512.

• Ключ узла не совпадает

  Эта проблема не должна происходить в службе Azure DevOps или на более поздних версиях Azure DevOps Server, как упоминалось в записи blog.

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

  Измените конфигурацию SSH, чтобы изменить параметры безопасности для Azure DevOps, добавив следующую команду в файл ~/.ssh/config (%UserProfile%\.ssh\config в файле Windows):

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

  Используйте это решение только для устаревших сценариев совместимости, как правило, для старых конфигураций локального Azure DevOps Server. В Azure DevOps Services сохраняйте безопасные параметры по умолчанию и избегайте постоянного использования переопределений ssh-rsa.

  Внимание

  OpenSSH устарел алгоритм подписи открытого ключа в ssh-rsa и отключил его по умолчанию в версии 8.8.

• Не соответствует MAC

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

  Измените конфигурацию SSH, чтобы изменить параметры безопасности для Azure DevOps, добавив следующую команду в файл ~/.ssh/config (%UserProfile%\.ssh\config в файле Windows):

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

• Метод обмена ключами не соответствует

  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
  

  Измените конфигурацию SSH, чтобы изменить параметры безопасности для Azure DevOps, добавив следующую команду в файл ~/.ssh/config (%UserProfile%\.ssh\config в файле Windows):

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

  Внимание

  Алгоритм diffie-hellman-group1-sha1 обмена ключами по умолчанию отключен в версии 6.9 OpenSSH и diffie-hellman-group14-sha1 версии 8.2.

Проблемы с агентом SSH и парольной фразой

Вопрос. Агент SSH не запущен или мой ключ не загружен. Что делать?

A: Если ключ существует, но SSH по-прежнему запрашивает парольную фразу каждый раз или если клонирование завершается сбоем после успешного создания ключа, проверьте, запущен ли агент SSH и загружается ли ключ.

Используйте следующую команду, чтобы просмотреть, какие идентификаторы в данный момент загружены в агент:

ssh-add -l

Если в выводе указано, что у агента нет идентификационных данных, добавьте свой приватный ключ в агент:

ssh-add ~/.ssh/id_rsa

Windows Если вы используете PowerShell со встроенным агентом OpenSSH, убедитесь, что ssh-agent служба запущена перед добавлением ключа. Если вы используете Git Bash или другой клиент SSH, обратитесь к документации клиента для запуска агента и загрузки ключей.

Если вы предпочитаете не использовать агент, SSH по-прежнему может работать, но вам чаще предлагается использовать парольную фразу.

Вопрос: Как заставить Git запомнить парольную фразу для моего ключа?

A: Используйте агент SSH. Linux, macOS и Windows (начиная с Windows 10 (сборка 1809) или с помощью Git для Windows с Git Bash) все поставляются с агентом SSH. Агент SSH может кэшировать ключи SSH для многократного использования. Ознакомьтесь с руководством поставщика SSH, чтобы узнать, как его использовать.

Вопрос. Я использую PuTTY в качестве клиента SSH и создал мои ключи с помощью PuTTYgen. Можно ли использовать эти ключи с службами Azure DevOps?

Ответ. Да. Загрузите закрытый ключ с помощью PuTTYgen, перейдите в меню "Преобразования" и выберите "Экспорт openSSH". Сохраните файл закрытого ключа, а затем обратитесь к следующему далее в этой статье вопросу об использовании нестандартного расположения ключа. Скопируйте открытый ключ непосредственно из окна PuTTYgen и вставьте его в поле "Данные ключа" в параметрах безопасности.

Вопрос. Как проверить, что отправленный открытый ключ совпадает с локальным ключом?

A: Проверьте отпечаток открытого ключа, который вы загрузили, сравнив его с тем, который отображается в профиле. Выполните следующую ssh-keygen команду для открытого ключа с помощью командной строки. Если вы не используете значения по умолчанию, необходимо изменить путь и имя файла открытого ключа.

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

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

Затем сравните сигнатуру с подписью в профиле. Эта проверка полезна при возникновении проблем с подключением или неправильном вставке открытого ключа в поле "Данные ключей" при добавлении ключа в Azure DevOps.

Вопрос. Как начать использовать SSH в репозитории, где сейчас используется ПРОТОКОЛ HTTPS?

A: Обновите URL-адрес удалённого репозитория origin в Git, заменив HTTPS-адрес на SSH. После получения URL-адреса клона SSH выполните следующую команду:

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

Команды Git, обращающиеся к удалённому репозиторию с именем origin, используют SSH.

Управление несколькими ключами и организациями

Вопрос. Я использую Git LFS с службами Azure DevOps и получаю ошибки при извлечении файлов, отслеживаемых Git LFS.

A: Azure DevOps Службы в настоящее время не поддерживают LFS по протоколу SSH. Используйте протокол HTTPS для подключения к репозиториям с отслеживаемыми файлами Git LFS.

Вопрос. Как использовать недефакторное расположение ключа, то есть не ~/.ssh/id_rsa и ~/.ssh/id_rsa.pub?

Ответ. Чтобы использовать ключ, хранящийся в другом месте по умолчанию, выполните следующие две задачи:

1. Ключи должны находиться в папке, которую можно прочитать или изменить. Если папка имеет более широкие разрешения, SSH не использует ключи.

2. Необходимо сообщить SSH о расположении ключа, например, указав его в качестве удостоверения в конфигурации SSH:

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

Этот IdentitiesOnly yes параметр гарантирует, что SSH не использует другое доступное удостоверение для проверки подлинности. Этот параметр особенно важен, если доступно несколько удостоверений.

Вопрос. У меня есть несколько ключей SSH. Как использовать правильный ключ SSH для Azure DevOps?

Ответ. Как правило, при настройке нескольких ключей для клиента SSH клиент пытается выполнить проверку подлинности с каждым ключом последовательно, пока сервер SSH не примет один.

Однако этот подход не работает с Azure DevOps из-за технических ограничений, связанных с протоколом SSH и структурой URL-адресов SSH Git. Azure DevOps принимает первый ключ, предоставленный клиентом во время проверки подлинности. Если этот ключ недопустим для запрошенного репозитория, запрос завершается ошибкой без попытки других доступных ключей, что приводит к следующей ошибке:

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

Для Azure DevOps необходимо настроить SSH для явного использования определенного файла ключа. Процедура аналогична использованию ключа, хранящегося в недефакторном расположении. Сообщите SSH использовать правильный ключ SSH для узла Azure DevOps.

Вопрос. Как использовать разные ключи SSH для разных организаций на Azure DevOps?

Ответ. Azure DevOps принимает первый ключ, который клиент предоставляет во время проверки подлинности. Если этот ключ недействителен для запрошенного репозитория, запрос завершается со следующей ошибкой:

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

Эта ошибка возникает из-за того, что все URL-адреса Azure DevOps используют одно и то же имя узла (ssh.dev.azure.com), что делает невозможной для SSH различать их по умолчанию. Однако вы можете изменить конфигурацию SSH, чтобы различать разные организации, предоставляя отдельные ключи для каждого. Используйте алиасы узлов для создания отдельных Host разделов в файле конфигурации 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

После этого вместо использования реальных URL-адресов сообщите Git, что вы хотите использовать эти URL-адреса для каждого репозитория в качестве удаленного, заменив имя хоста в существующих удаленных адресах на devops_fabrikam и devops_contoso соответственно. Например, git@ssh.dev.azure.com:v3/Fabrikam/Project1/fab_repo преобразуется в git@devops_fabrikam:v3/Fabrikam/Project1/fab_repo.

Уведомления и проблемы с учетной записью

Вопрос. Какие уведомления можно получить о ключах SSH?

A: Вы можете получить несколько уведомлений о ключах SSH.

• В организацию добавлен новый ключ SSH.

• Срок действия ключа SSH, связанного с вашей учетной записью, истекает через 7 дней и не действителен для проверки подлинности.

• Ключ SSH, связанный с учетной записью, истек и больше не действителен для проверки подлинности.

  Пример уведомления

  

Вопрос. Что делать, если я верю, что кто-то, кроме меня, добавляет ключи SSH в свою учетную запись?

A: Если вы получили уведомление о регистрации ключей SSH, которые вы не инициировали, ваши учетные данные могут быть скомпрометированы.

Следующий шаг — выяснить, скомпрометирован ли пароль. Изменение пароля всегда является хорошим шагом для защиты от этого вектора атаки. Если вы являетесь пользователем Microsoft Entra, обратитесь к администратору, чтобы проверить, использовалась ли учетная запись из неизвестного источника или расположения.

Вопрос. Что делать, если мне по-прежнему предлагается пароль и GIT_SSH_COMMAND="ssh -v" git fetch отображается no mutual signature algorithm или corresponding algo not in PubkeyAcceptedAlgorithms?

A: Некоторые дистрибутивы Linux, такие как Fedora Linux, применяют политики шифрования, требующие более сильных алгоритмов подписи SSH, чем в текущей конфигурации SSH Azure DevOps.

Чтобы обойти проблему, добавьте следующий код в конфигурацию SSH (~/.ssh/config):

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

Если версия OpenSSH поддерживает только старое имя параметра, используйте PubkeyAcceptedKeyTypes вместо этого.

Используйте этот код как временное решение для обеспечения совместимости. По возможности обновите SSH-клиент или конфигурацию сервера и удалите это переопределение после тестирования.

Общие вопросы

Вопрос. Можно ли использовать SSH с Azure DevOps Server?

Ответ. Да. Для самостоятельно размещенных экземпляров Azure DevOps Server используйте имя узла сервера в конфигурации SSH и в удаленных URL-адресах вместо ssh.dev.azure.com. Там, где в этой статье указано ssh.dev.azure.com или vs-ssh.visualstudio.com, подставьте имя хоста вашего сервера.

Вопрос. Почему ключ SSH службы Azure DevOps перестал работать?

A: Проверка подлинности ключа SSH требует регулярного входа в службы Azure DevOps с помощью полного потока проверки подлинности (веб-сайт). Для многих пользователей достаточно входить только раз в 30 дней, но в зависимости от конфигурации Microsoft Entra может потребоваться выполнять вход чаще. Если ключ SSH перестает работать, сначала попробуйте войти в свою организацию и выполнить полный запрос проверки подлинности. Если ключ SSH по-прежнему не работает, проверьте, истек ли срок действия.

Связанный контент

• Настройка диспетчеров учетных данных
• Общие сведения о сервере MCP Azure DevOps
• Управление большими файлами
• Установите разрешения для репозитория Git