共用方式為


使用 SSH 金鑰驗證

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

您可以透過macOS、Linux或 Windows 上的SSH連線到 Git 存放庫,以安全地與 Azure DevOps 連線。

重要

SSH URL 已變更,但舊的 SSH URL 仍可繼續運作。 如果您已經設定 SSH,請將遠端 URL 更新為新的格式:

最新的 SSH URL 開頭為 ssh.dev.azure.com。 先前的網址使用 vs-ssh.visualstudio.com

  • 確認哪些遠端使用 SSH。 請改為在殼層中執行 git remote -v 或使用 GUI 用戶端。
  • 瀏覽網路上的存放庫,然後選取 [ 複製]。
  • 選取 [SSH ],然後複製新的 SSH URL。
  • 在殼層 git remote set-url <remote name> <new SSH URL> 中,針對您想要更新之存放庫的每個遠端執行。 或者,使用 GUI 用戶端來更新遠端 URL。

SSH 金鑰驗證的運作方式

SSH 公鑰驗證可與產生的加密金鑰非對稱組搭配使用。 公鑰會與 Azure DevOps 共用,並用來驗證初始 SSH 連線。 私鑰會在您的系統上保持安全且安全。

設定 SSH 金鑰驗證

下列步驟涵蓋使用命令列在下列平台上設定 SSH 金鑰驗證 (也稱為 shell):

注意

從 Visual Studio 2017 開始,SSH 可用來連線到 Azure DevOps Git 存放庫。

提示

在 Windows 上,我們建議使用 Git 認證管理員個人存取令牌

步驟 1:建立 SSH 金鑰

注意

如果您已在系統上建立 RSA SSH 金鑰,請略過此步驟並 設定 SSH 金鑰。 若要確認這一點,請移至您的主目錄,並查看 .ssh 資料夾(%UserProfile%\.ssh\ 在 Windows 或 ~/.ssh/ Linux、macOS 和 Windows 上使用 Git Bash)。 如果您看到兩個名為的檔案 id_rsa ,並 id_rsa.pub 分別繼續 設定 SSH 金鑰

若要使用金鑰型驗證,您必須先為您的用戶端產生公開/私密金鑰組。 ssh-keygen.exe可用來產生密鑰檔案,而且可以指定 DSA、RSA、ECDSA 或 Ed25519 演算法。 如果未指定演算法,則會使用 Ed25519。

注意

Azure DevOps 唯一支援的 SSH 金鑰類型是 RSA

若要使用 Azure DevOps 支援的 RSA 演演算法產生密鑰檔案(RSA-SHA2-256 或 RSA-SHA2-512),請從 PowerShell 或用戶端上執行 bash 下列其中一個命令:

ssh-keygen -t rsa-sha2-256

Or

ssh-keygen -t rsa-sha2-512

命令輸出應該會顯示下列輸出(其中 username 是您的使用者名稱):

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

您可以按 Enter 鍵接受預設值,或指定您想要產生金鑰所在的路徑及或檔案名稱。 此時,系統會提示您使用複雜密碼來加密私鑰檔案。 複雜密碼可以是空的,但不建議使用。 複雜密碼可與金鑰檔案搭配使用,以提供雙因素驗證。

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

將上一個步驟中產生的公鑰與您的使用者識別碼產生關聯。

注意

您必須針對每個組織重複此作業,才能存取並想要搭配使用SSH。

  1. 流覽至入口網站並選取使用者介面右上角虛擬人偶旁的圖示,以開啟您的安全性設定。 選取 出現的功能表中的 [SSH 公鑰 ]。

    此螢幕快照顯示 SSH 公鑰菜單項,以及 Azure DevOps 中選取的使用者虛擬人偶。

  2. 選取 [+ 新增金鑰]。

    顯示 Azure DevOps 中安全性設定存取權的螢幕快照。

  3. 將您產生的公鑰id_rsa.pub內容複製到 [公鑰資料] 欄位中。

    重要

    避免在 [金鑰數據] 字段中新增空格元或新行,因為它們可能會導致 Azure DevOps 使用無效的公鑰。 在索引鍵中貼上時,通常會在結尾新增換行符。 如果發生這個換行符,請務必將其移除。

    顯示在 Azure DevOps 中設定公鑰的螢幕快照。

  4. 為金鑰提供有用的描述(此描述會顯示在設定檔的 SSH 公鑰 頁面上),以便稍後記住它。 選取 [ 儲存 ] 以儲存公鑰。 儲存之後,就無法變更密鑰。 您可以刪除金鑰,或為另一個金鑰建立新的專案。 您可以新增至使用者設定檔的金鑰數目沒有任何限制。 另請注意,儲存在 Azure DevOps 中的 SSH 金鑰會在一年後到期。 如果您的金鑰過期,您可以上傳新的金鑰或相同的密鑰,以透過 SSH 繼續存取 Azure DevOps。

  5. 在 [ SSH 公鑰 概觀] 頁面上,會顯示伺服器指紋。 請記下第一次透過 SSH 連線到 Azure DevOps 時要使用的 SHA256 指紋。

    在 Azure DevOps Services 中存取安全性設定的螢幕快照。

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

    比較指紋與先前提及 SSH 公鑰 頁面上顯示的 SHA256 指紋。 只有在符合時才繼續!

  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:使用 SSH 複製 Git 存放庫

注意

若要搭配先前透過 HTTPS 複製的存放庫使用 SSH,請參閱 將您的遠端更新為 SSH

  1. 從入口網站複製 SSH 複製 URL。 在此範例中,SSH 複製 URL 適用於名為 fabrikam-fiber 之組織中的存放庫,如 之後 dev.azure.comURL 的第一個部分所指示。

    顯示 Azure Repos SSH 複製 URL 的螢幕快照

    注意

    使用 Azure DevOps Services 時,專案 URL 的格式為 dev.azure.com/{your organization}/{your project}。 不過,仍支持參考格式的 visualstudio.com 先前格式。 如需詳細資訊,請參閱 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.
    

    如果您改為提示您驗證指紋,請閱讀 步驟 2:再次將公鑰新增至 Azure DevOps 。 如需其他問題,請閱讀問題與疑難解答一節

提示

若要充分利用 SSH,通常會使用 SSH 代理程式來管理您的 SSH 金鑰。 不過,設定代理程式已超出本文的範圍。

問題和疑難解答

答: 可以看到兩個不同的警告訊息:

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.

如果您已修改 SSH 組態,將下列內容新增至您的 ~/.ssh/config%UserProfile%\.ssh\config 在 Windows 上) 檔案,以降級 Azure DevOps 的安全性設定:

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

立即移除這些行,並確定 rsa-sha2-256 允許和/或 rsa-sha2-512

如需詳細資訊,請參閱部落格文章

問:SSH 無法建立連線。 我該怎麼做?

答: 您可能會遇到多個不同的問題:

  • 使用不支援的 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 組態,將下列內容新增至您的 ~/.ssh/config%UserProfile%\.ssh\config 在 Windows 上) 檔案,以降級 Azure DevOps 的安全性設定:

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

    立即移除這些行,並確定 rsa-sha2-256 允許和/或 rsa-sha2-512

    如需詳細資訊,請參閱部落格文章

  • 沒有相符的主機金鑰

    此問題不應該發生在 Azure DevOps Service 或較新的 Azure DevOps Server 版本上,如部落格文章中所述

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

    修改 SSH 組態,將下列內容新增至您的 ~/.ssh/config%UserProfile%\.ssh\config 在 Windows 上) 檔案,以降級 Azure DevOps 的安全性設定:

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

    重要

    OpenSSH 已ssh-rsa取代 8.2 版中的公鑰簽章演算法,並預設在 8.8 版中將其停用。

  • 沒有相符的 MAC

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

    修改 SSH 組態,將下列內容新增至您的 ~/.ssh/config%UserProfile%\.ssh\config 在 Windows 上) 檔案,以降級 Azure DevOps 的安全性設定:

    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 組態,將下列內容新增至您的 ~/.ssh/config%UserProfile%\.ssh\config 在 Windows 上) 檔案,以降級 Azure DevOps 的安全性設定:

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

    重要

    OpenSSH 6.9 版和 diffie-hellman-group14-sha1 8.2 版預設已停用密鑰交換演算法diffie-hellman-group1-sha1

提示

針對 Azure DevOps Server 和 TFS 的自我裝載實例,請使用行中的 Host 適當主機名,而不是 ssh.dev.azure.com vs-ssh.visualstudio.com

問:如何讓 Git 記住金鑰的複雜密碼?

答: 您可以使用 SSH 代理程式。 Linux、macOS 和 Windows(從 Windows 10 開始(組建 1809) 或使用 Git for Windows 搭配 Git Bash)全部隨附於 SSH 代理程式。 SSH 代理程式可用來快取 SSH 金鑰以供重複使用。 如需如何使用 SSH 廠商的詳細資訊,請參閱 SSH 廠商的手冊。

問:我使用 PuTTY 作為 SSH 用戶端,並使用 PuTTYgen 產生密鑰。 我可以搭配 Azure DevOps Services 使用這些密鑰嗎?

A: 可以。 使用 PuTTYgen 載入私鑰,移至 [轉換] 功能表,然後選取 [匯出 OpenSSH 金鑰]。 儲存私鑰檔案,然後遵循步驟來 設定非預設密鑰。 直接從 PuTTYgen 視窗複製您的公鑰,並貼到 安全性設定中的 [金鑰數據 ] 欄位。

問:如何確認我上傳的公鑰與本機金鑰相同?

答: 您可以使用命令行,透過下列 ssh-keygen 命令針對您的公鑰執行,來驗證上傳的公鑰指紋,並顯示於配置檔中。 如果您未使用預設值,則必須變更路徑和公鑰檔名。

注意

自 2024 年 8 月 /9 月起,我們會從 MD5 移轉至 SHA-256 哈希。 您可能需要在轉換期間選擇正確的函式。

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

然後,您可以將簽章與配置檔中的簽章進行比較。 如果您在將密鑰新增至 Azure DevOps 時,有連線問題,或擔心在公鑰中不正確地貼到 [金鑰數據 ] 字段中,這項檢查會很有用。

問:如何在目前使用 HTTPS 的存放庫中開始使用 SSH?

答: 您必須更新 origin Git 中的遠端,以從 HTTPS 變更為 SSH URL。 擁有 SSH 複製 URL 之後,請執行下列命令:

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

存取遠端的 origin Git 命令會使用 SSH。

問:我正在使用 Git LFS 搭配 Azure DevOps Services,且在提取 Git LFS 追蹤的檔案時,出現錯誤。

答: Azure DevOps Services 目前不支援透過 SSH 的 LFS。 使用 HTTPS 連線至具有 Git LFS 追蹤檔案的存放庫。

問:如何使用非預設密鑰位置,也就是不是 ~/.ssh/id_rsa 和 ~/.ssh/id_rsa.pub?

答: 若要使用儲存在與預設值不同的位置的密鑰,請執行下列兩項工作:

  1. 索引鍵必須位於只有您可以讀取或編輯的資料夾中。 如果資料夾具有較寬的許可權,SSH 不會使用金鑰。

  2. 例如,您必須將 SSH 指定為 SSH 組態中的「身分識別」,讓 SSH 知道金鑰的位置:

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

IdentitiesOnly yes 設定可確保 SSH 不會使用任何其他可用的身分識別進行驗證。 如果有多個身分識別可供使用,此設定就特別重要。

問:我有多個 SSH 金鑰。 如何? 針對 Azure DevOps 使用正確的 SSH 金鑰嗎?

答: 一般而言,當您為 SSH 用戶端設定多個金鑰時,用戶端會嘗試循序向每個金鑰進行驗證,直到 SSH 伺服器接受一個金鑰為止。

不過,此方法不適用於 Azure DevOps,因為與 SSH 通訊協定和 Git SSH URL 結構相關的技術條件約束。 Azure DevOps 會在驗證期間接受用戶端所提供的第一個密鑰。 如果要求的存放庫此金鑰無效,要求會失敗,而不會嘗試任何其他可用的金鑰,因而產生下列錯誤:

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

針對 Azure DevOps,您必須設定 SSH 以明確使用特定密鑰檔案。 此程式與使用儲存在非預設位置金鑰時相同。 告知 SSH 針對 Azure DevOps 主機使用正確的 SSH 密鑰。

問:如何? Azure DevOps 上的不同組織使用不同的 SSH 金鑰?

答: Azure DevOps 盲目地接受客戶端在驗證期間提供的第一個密鑰。 如果要求的存放庫該金鑰無效,要求會失敗,並出現下列錯誤:

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

此失敗是因為所有 Azure DevOps URL 共用相同的主機名 (ssh.dev.azure.com),因此 SSH 預設無法區分它們。 不過,您可以修改 SSH 組態,藉由為每個組織提供不同的密鑰來區分不同組織。 使用主機別名在 SSH 組態檔中建立個別 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.

# 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,而是將現有遠端 devops_fabrikam 中的主機名分別取代為 和 devops_contoso ,告訴 Git 您想要將每個存放庫的這些 URL 作為遠端。 例如,git@ssh.dev.azure.com:v3/Fabrikam/Project1/fab_repo 會變成 git@devops_fabrikam:v3/Fabrikam/Project1/fab_repo

問:我可能會收到關於 SSH 金鑰的哪些通知?

答: 當您向 Azure DevOps Services 註冊新的 SSH 金鑰時,您會收到電子郵件通知,通知您何時將新的 SSH 金鑰新增至您的帳戶。

SSH 通知範例

問:如果我相信我以外的人正在我的帳戶上新增 SSH 金鑰,該怎麼辦?

答: 如果您收到未起始的 SSH 金鑰註冊通知,您的認證可能會遭到入侵。

下一個步驟是調查您的密碼是否遭到入侵。 變更密碼一律是防禦此攻擊媒介的好第一步。 如果您是Microsoft Entra 使用者,請與您的系統管理員交談,以檢查您的帳戶是否從未知的來源/位置使用。

問:如果我仍然提示您輸入密碼並 GIT_SSH_COMMAND="ssh -v" git fetch 顯示 no mutual signature algorithmcorresponding algo not in PubkeyAcceptedAlgorithms,該怎麼辦?

答: 某些 Linux 散發套件,例如 Fedora Linux,具有比 Azure DevOps 支援的更強 SSH 簽章演算法的加密原則(截至 2021 年 1 月)。 有開啟 的功能要求 可新增此支援。

您可以將下列程式代碼新增至 SSH 組態(~/.ssh/config):

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

提示

針對 Azure DevOps Server 和 TFS 的自我裝載實例,請使用行中的 Host 適當主機名,而不是 ssh.dev.azure.com vs-ssh.visualstudio.com