使用個人存取權杖

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

個人存取令牌 （PAT） 可作為驗證 Azure DevOps 的替代密碼。 此 PAT 會識別您，並判定您的可存取性和存取範圍。 以相同的謹慎態度對待 PAT，如同對待密碼。

當您使用 Microsoft 工具時，您的 Microsoft 帳戶（MSA）或 Microsoft Entra ID 會被辨識並支援。 如果您使用不支援Microsoft Entra 帳戶或不想共用主要認證的工具，PAT 可以是適當的替代方案。 不過，建議您盡可能使用 Microsoft Entra 令牌，而不是 PAT。

重要

我們建議使用更安全的 Microsoft Entra 令牌，而不是高風險的 個人存取令牌。 深入了解我們減少 PAT 使用量的努力。 檢 閱我們的驗證指引 ，為您的需求選擇正確的驗證機制。

必要條件

類別	要求
許可	存取及修改用於管理 PAT 之使用者設定的權限。 - 移至 設定檔，然後選取 [使用者設定]>[個人存取權杖]。 如果您可以在這裡看到及管理您的 PAT，那麼您就擁有必要的權限。 - 移至您的項目，然後選取 [項目設定]，>[許可權]。 在清單中尋找您的用戶帳戶，並檢查指派給您的許可權。 尋找與管理令牌或用戶設定相關的許可權。 - 如果您的 組織已設定原則，系統管理員可能需要授與您特定許可權，或將您新增至允許清單以建立和管理 PAT。 - PAT 會連結到生成該令牌的用戶帳戶。 根據 PAT 所執行的工作，您自己可能需要更多的權限。
存取層級	至少擁有 基本的 存取權限。
任務	請只在必要時使用 PAT，並一律定期輪替它們。 請參閱使用 PAT 時的最佳做法一節。

建立 PAT

1. 登入您的組織 (https://dev.azure.com/{Your_Organization})。

2. 從您的首頁開啟使用者設定 ，然後選取 [個人存取權杖]。

   

3. 選取 + 新增代幣。

   

4. 為您的令牌命名、選取您想要使用令牌的組織，然後將令牌設定為在設定天數之後自動到期。

   

5. 選擇此令牌的範圍以授權用於您的特定工作。

   例如，若要為組建和發行代理程式建立令牌以向 Azure DevOps 進行驗證，請將令牌的範圍設定為代理程式集區（讀取及管理）。 若要讀取稽核記錄事件及管理或刪除數據流，請選取 [讀取稽核記錄]，然後選取 [ 建立]。

   

   注意

   您的系統管理員可能會 限制您建立完整範圍的 PAT，或將您限制為僅限封裝範圍的 PAT。 如果您需要其他範圍的存取權，請連絡系統管理員以取得允許清單。 某些範圍，例如 vso.governance，如果UI中不適用於廣泛的公用用途，則可能無法在UI中使用。

6. 完成時，請複製權杖，並將其儲存在安全的位置。 針對您的安全性，它不會再次顯示。

   

在任何需要使用您用戶憑證進行驗證的 Azure DevOps 位置中使用您的 PAT。

重要

• 請將 PAT 與密碼一樣謹慎處理並保密。 請勿共用 PAT。
• 針對由 Microsoft Entra 識別碼所支援的組織，您必須在 90 天內使用新的 PAT 登入，否則它將會變成非使用中狀態。 如需詳細資訊，請參閱 條件式存取的使用者登入頻率。

通知

在 PAT 的存續期間，使用者會收到兩個通知：在建立期間和到期前三天。

建立 PAT 之後，您可能會收到類似下面的通知。 此通知可確認您的 PAT 已成功新增至您的組織。

到期通知電子郵件會在到期前三天傳送。 如果您的系統管理員 已移除在組織中建立 PAT 的能力，電子郵件會指出您無法再重新產生 PAT。 請連絡 您的專案集合管理員 ，以包含在允許清單中，以取得該組織中持續 PAT 建立許可權。

如需詳細資訊，請參閱 設定 SMTP 伺服器並自定義警示和意見反應要求的電子郵件。

未預期的通知

如果您收到非預期的 PAT 通知，這可能表示系統管理員或工具為您建立 PAT。 以下是一些範例：

• 當您透過 git.exe 連線到 Azure DevOps Git 存放庫時，會建立名為 「git： https://dev.azure.com/{Your_Organization} on YourMachine」 的令牌。
• 當您或系統管理員設定 Azure App Service Web 應用程式部署時，就會建立名為「服務勾點：Azure App Service：部署 Web 應用程式」的令牌。
• 當您或系統管理員將 Web 負載測試設定為管線的一部分時，會建立名為 “WebAppLoadTestCDIntToken” 的令牌。
• 當設定 Microsoft Teams Integration Messaging 擴充功能時，會建立一個名為 "Microsoft Teams Integration" 的令牌。

警告

• 如果您懷疑它存在錯誤，請撤銷 PAT（並變更密碼）。
• 如果您是 Microsoft Entra 使用者，請洽詢系統管理員，以查看未知的來源或位置是否存取您的組織。
• 檢閱意外 PAT 簽入至公用 GitHub 存放庫的常見問題。

使用 PAT

您的 PAT 可作為您的數位身分識別，就像密碼一樣。 您可以使用 PAT 作為快速的方式，在本機執行一次性要求或建立應用程式的原型。 在您的程式代碼中使用 PAT 來驗證 REST API 要求，並藉由在要求的授權標頭中包含 PAT 來自動化工作流程。

重要

一旦應用程式程式代碼運作後，請切換至 Microsoft Entra OAuth，以代表您應用程式的使用者或服務主體或受控識別取得令牌，以取得令牌作為應用程式。 不建議長期使用 PAT 來執行應用程式或腳本。 Microsoft Entra 令牌可用於任何使用 PAT 的地方。 請考慮 透過 Azure CLI 取得Microsoft Entra 令牌 以進行臨機作要求。

Windows 作業系統

若要透過 HTTP 標頭提供 PAT，您必須先將它 Base64 轉換成字串。 然後，它就可以以下列格式提供為 HTTP 標頭。

Authorization: Basic BASE64_USERNAME_PAT_STRING

Linux/macOS

下列範例會取得使用 curl 的組建清單。

curl -u :{PAT} https://dev.azure.com/{organization}/_apis/build-release/builds

修改 PAT

請執行下列步驟：

• 重新生成 PAT 以創建新的令牌，從而使先前的令牌失效。
• 延長 PAT 以增加其有效期間。
• 變更 PAT 的範圍以變更其許可權。

1. 從您的首頁開啟使用者設定 ，然後選取 [個人存取權杖]。

2. 選取您要修改的代幣，然後點選 "編輯"。

   

3. 編輯令牌名稱、令牌到期或與令牌相關聯的存取範圍，然後選取 [ 儲存]。

   

撤銷 PAT

您可以隨時撤銷 PAT，原因如下：

• 如果您懷疑 PAT 已遭入侵，請撤銷它。
• 當不再需要 PAT 時撤銷它。
• 撤銷 PAT 以強制執行安全策略或合規性需求。

1. 從您的首頁開啟使用者設定 ，然後選取 [個人存取權杖]。

2. 在 [安全性] 底下，選取 [ 個人存取令牌]。 選取您要撤銷存取權的令牌，然後選取 [ 撤銷]。

   顯示選擇撤銷單一令牌或所有令牌的螢幕快照。

3. 在確認對話框中選取 [ 撤銷 ]。

   

PAT 生命週期管理 API

當透過界面管理大量令牌變得不可持續時，PAT生命週期管理 API可能會非常有用。 以程序設計方式管理 PAT 輪替也可讓您定期輪替 PAT，並縮短其預設生命週期。 我們的 範例 Python 應用程式 可以與您的 Microsoft Entra 租戶和 Azure DevOps 組織進行設定。

這些 API 需要注意的一些事項：

• 需要Microsoft Entra 存取令牌 才能存取此 API，因為在生成新令牌時，通常建議使用更強形式的驗證。
• 只有使用「代表使用者」流程的用戶或應用程式才能產生 PAT。 使用「代表應用程式」流程的應用程式或未發出Microsoft Entra 存取令牌的驗證流程，不適用於此 API。 因此， 服務主體或受控識別 無法建立或管理 PAT。
• 先前的 PAT 生命週期管理 API 僅支援 user_impersonation 範圍，但現在 vso.tokens 已提供 ，且建議的範圍可搭配這些 API 使用。 縮小範圍使用之前依賴 user_impersonation 呼叫這些 API 的所有應用程式。

格式的變更

自 2024 年 7 月起，我們已更新 PAT 字串的格式，以改善我們洩露的 PAT 偵測工具和合作夥伴供應專案中的秘密偵測。 這個新的 PAT 格式包含更多可識別的位，以提高這些偵測工具中的誤判偵測準確性，並更快減少已偵測洩漏的影響。

• 新的令牌現在長度 為84 個字元，有52個字元是隨機化數據。 這可改善整體熵，讓令牌對暴力攻擊更具抵抗性。
• 由我們的服務簽發的令牌包含在第76至80位置的固定AZDO簽章。

如果您使用在那個日期之前發佈的 PAT，請重新生成您的 PAT。 如果您與 PAT 整合並內建 PAT 驗證，請更新驗證程式代碼以容納新的和現有的令牌長度。

警告

這兩種格式在可預見的未來仍將有效。 隨著新格式的採用增加，我們可能會淘汰舊版 52 個字元的 PAT。

使用 PAT 的最佳做法

考慮替代方案

• 透過 Azure CLI 取得 Microsoft Entra 令牌以進行臨時請求，而不是生成有效期較長的 PAT。
• 使用 Git 認證管理員 或 Azure Artifacts Credential Manager 之類的認證管理員來簡化認證管理，並將驗證設定為 oauth 或 Microsoft Entra 令牌。

建立 PAT

• 請勿將個人資料放在 PAT 名稱中。 請勿將 PAT 名稱重新命名為包含部分或所有實際 PAT 令牌。
• 除非所有組織都有必要，否則請避免建立全域 PAT。
• 在每個流程或使用者情境中使用不同的 token。
• 為每個 PAT 選擇最少需要的範圍。 為每個流程建立具有較少範圍的個別 PAT，而不是針對所有流程建立單一完整範圍的 PAT。 如果您的 PAT 需要只讀許可權，除非必要，否則請勿提供寫入許可權。
• 請將 PAT 的使用期限保持在短期內（每週為理想，甚至更短更好）。

管理 PAT

• 不要共用您的 PAT！
• 將您的 PAT 儲存在安全的金鑰管理解決方案中，例如 Azure KeyVault。
• 透過 UI 或 PAT 生命週期管理 API 定期更新或重新生成您的 PAT。
• 不再需要時撤銷 PAT。
• 旋轉您的 PATs，使用 新的 PAT 格式，以便透過我們的第一方工具更佳地偵測和撤銷洩漏的秘密。

適用於系統管理員

• 租戶管理員可以設定 原則來限制 全域 PAT 建立、完整範圍的 PAT 建立，以及長時間有效的 PAT。
• 如果 PAT 遭到洩露時，租戶系統管理員可以 撤銷其組織使用者的 PAT。
• 組織管理員可以 限制在組織中建立 PAT。 如果仍然需要 PAT，請將其建立限制為僅允許清單上的那些。

常見問題集

問：為什麼我無法編輯或重新產生限定於單一組織的 PAT？

答：登入您的 PAT 範圍所在組織。 您可以藉由變更 存取範圍 篩選，在登入具有相同 Microsoft Entra ID 的任何組織時檢視所有 PAT，但您只能在登入特定組織時編輯僅限於該組織的令牌。

問：如果停用用戶帳戶，PAT 會發生什麼事？

答：當使用者從 Azure DevOps 移除時，PAT 會在 1 小時內失效。 如果您的組織已連線到 Microsoft Entra ID，PAT 也會在 Microsoft Entra ID 中失效，因為它屬於用戶。 我們建議將 PAT 轉移至另一個使用者或服務帳戶，以保持服務的運行。

問：我可以搭配所有 Azure DevOps REST API 使用 PAT 嗎？

A: 不可以。 您可以搭配大部分的 Azure DevOps REST API 使用 PAT，但 組織和配置檔 和 PAT 管理生命週期 API 僅支援 Microsoft Entra 令牌。

問：如果我不小心將 PAT 簽入 GitHub 上的公用存放庫，會發生什麼事？

答：Azure DevOps 會掃描簽入 GitHub 上的公用存放庫的 PAT。 當我們找到流失的令牌時，我們會立即傳送詳細的電子郵件通知給令牌擁有者，並在 Azure DevOps 組織的 稽核記錄中記錄事件。 我們鼓勵受影響的使用者撤銷洩露的令牌，並將它取代為新的令牌，以減輕問題。

除非您停用了自動撤銷洩露的個人存取令牌原則，否則我們會立即撤銷洩露的個人存取令牌。 如需詳細資訊，請參閱 自動撤銷外洩的 PAT。

問：是否可以使用個人存取令牌作為 ApiKey，使用 dotnet/nuget.exe 命令行將 NuGet 套件發佈至 Azure Artifacts 摘要？

A: 不可以。 Azure Artifacts 不支援將 PAT 傳遞為 ApiKey。 使用本機開發環境時，建議您安裝 Azure Artifacts 認證提供者 向 Azure Artifacts 進行驗證。 如需詳細資訊，請參閱下列範例：dotnet、NuGet.exe。 如果您想要使用 Azure Pipelines 發佈套件，請使用 NuGet 驗證 任務來驗證您的供應來源。 請參閱 範例。

問：為什麼我的 PAT 停止運作？

答：PAT 驗證會要求您定期使用完整驗證流程登入 Azure DevOps。 每 30 天登入一次就足以供許多使用者使用，但視您的 Microsoft Entra 設定而定，您可能需要更頻繁地登入。 如果您的 PAT 停止運作，請先嘗試登入您的組織，並完成完整的驗證提示。 如果您的 PAT 仍然無法運作，請檢查它是否已過期。

啟用 IIS 基本身份驗證會導致 Azure DevOps Server 的 PAT 無效。 建議您一律關閉IIS 基本身份驗證。

警告

如果您使用 Git 搭配 IIS 基本身份驗證，Git 會中斷，因為它需要 PAT 來進行用戶驗證。 您可以將額外的標頭新增至 Git 要求，以搭配 IIS 基本身份驗證使用，但不建議這麼做。 額外的標頭必須用於所有 Azure DevOps Server 安裝，因為 Windows 驗證也會防止使用 PAT。 額外的標頭也必須包含 「user：PAT」 的基底 64 編碼。

git -c http.extraheader='Authorization: Basic [base 64 encoding of "user:password"]' ls-remote http://tfsserver:8080/tfs/DefaultCollection/_git/projectName

問：如何建立不與特定個人關聯的存取令牌？

答：所有 PAT 都會與建立它的使用者身分識別相關聯。 應用程式無法建立 PAT。

在 Azure DevOps 中，您可以使用由 Microsoft Entra 所發行的令牌來建立未系結至特定人員的存取令牌，這些令牌是由 應用程式服務主體或受控識別 所建立的。 在管線內，使用服務連線。

問：如何透過 API 重新產生/輪替 PAT？ 我在UI中看到該選項，但我在 API 中看不到類似的方法。

UI 中提供的「重新產生」功能實際上會完成一些動作，可透過 API 進行複寫。

若要輪替 PAT，請執行下列步驟：

1. 請參閱使用 GET 呼叫的 PAT 元數據，
2. 使用 POST 呼叫建立具有舊 PAT 識別元的新 PAT，
3. 使用 DELETE 呼叫撤銷舊的 PAT。

問：當我嘗試使用 Entra 應用程式呼叫 PAT 生命週期管理 API 時，我會看到「需要系統管理員核准」彈出視窗。

您的租使用者安全策略需要系統管理員同意，應用程式才能存取組織中的組織資源。 請聯絡您的租戶管理員。

問：我可以使用服務主體來建立或管理 PAT 嗎？

否，個人存取令牌屬於使用者身分識別。 Entra 服務主體或受管理的身份 能夠產生短期的 Entra 令牌，這些令牌可用於大多數接受 PAT 的地方。 深入瞭解 我們在 Azure DevOps 之間減少 PAT 使用量的努力 ，並探索使用 Entra 令牌取代 PAT。

相關文章

• 使用原則來管理用戶的個人存取令牌
• 復原使用者 PAT （適用於系統管理員 ）
• 使用 Microsoft Entra 令牌進行驗證