使用 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
):
- Linux
- macOS
- 執行 Git for Windows 的 Windows 系統
注意
從 Visual Studio 2017 開始,SSH 可用來連線到 Azure DevOps 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。
流覽至入口網站並選取使用者介面右上角虛擬人偶旁的圖示,以開啟您的安全性設定。 選取 出現的功能表中的 [SSH 公鑰 ]。
選取 [+ 新增金鑰]。
將您產生的公鑰
id_rsa.pub
內容複製到 [公鑰資料] 欄位中。重要
避免在 [金鑰數據] 字段中新增空格元或新行,因為它們可能會導致 Azure DevOps 使用無效的公鑰。 在索引鍵中貼上時,通常會在結尾新增換行符。 如果發生這個換行符,請務必將其移除。
為金鑰提供有用的描述(此描述會顯示在設定檔的 SSH 公鑰 頁面上),以便稍後記住它。 選取 [ 儲存 ] 以儲存公鑰。 儲存之後,就無法變更密鑰。 您可以刪除金鑰,或為另一個金鑰建立新的專案。 您可以新增至使用者設定檔的金鑰數目沒有任何限制。 另請注意,儲存在 Azure DevOps 中的 SSH 金鑰會在一年後到期。 如果您的金鑰過期,您可以上傳新的金鑰或相同的密鑰,以透過 SSH 繼續存取 Azure DevOps。
在 [ SSH 公鑰 概觀] 頁面上,會顯示伺服器指紋。 請記下第一次透過 SSH 連線到 Azure DevOps 時要使用的 SHA256 指紋。
執行下列命令來測試連線:
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 指紋。 只有在符合時才繼續!
輸入
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。
從入口網站複製 SSH 複製 URL。 在此範例中,SSH 複製 URL 適用於名為 fabrikam-fiber 之組織中的存放庫,如 之後
dev.azure.com
URL 的第一個部分所指示。注意
使用 Azure DevOps Services 時,專案 URL 的格式為
dev.azure.com/{your organization}/{your project}
。 不過,仍支持參考格式的visualstudio.com
先前格式。 如需詳細資訊,請參閱 Azure DevOps 簡介,將現有組織切換為使用新的功能變數名稱 URL。從命令提示字元執行
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 相關警告。 我該怎麼做?
答: 可以看到兩個不同的警告訊息:
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
沒有相符的 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?
答: 若要使用儲存在與預設值不同的位置的密鑰,請執行下列兩項工作:
索引鍵必須位於只有您可以讀取或編輯的資料夾中。 如果資料夾具有較寬的許可權,SSH 不會使用金鑰。
例如,您必須將 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 金鑰註冊通知,您的認證可能會遭到入侵。
下一個步驟是調查您的密碼是否遭到入侵。 變更密碼一律是防禦此攻擊媒介的好第一步。 如果您是Microsoft Entra 使用者,請與您的系統管理員交談,以檢查您的帳戶是否從未知的來源/位置使用。
問:如果我仍然提示您輸入密碼並 GIT_SSH_COMMAND="ssh -v" git fetch
顯示 no mutual signature algorithm
或 corresponding 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
。