使用個人存取權杖

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中使用，因為它們不適用於廣泛的公用用途。

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

   

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

重要

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

通知

在 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 以強制執行安全策略、合規性需求或組織令牌輪替排程。
• 用戶變更：當小組成員離開組織或變更角色且不再需要存取權時，撤銷 PAT。
• 縮小範圍：當您需要限制其存取功能時，請撤銷並重新建立具有縮減許可權的 PAT。
• 定期維護：撤銷 PAT 作為例行安全性衛生和令牌生命週期管理的一部分。

請執行下列步驟來撤銷 PAT：

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

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

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

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

   

PAT 生命週期管理 API

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

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

• 需要Microsoft Entra 存取令牌 才能存取此 API，因為在生成新令牌時，通常建議使用更強形式的驗證。
• 只有使用「代表使用者」流程的用戶或應用程式才能產生 PAT。 使用「代表應用程式」流程的應用程式或未發出Microsoft Entra 存取令牌的驗證流程，不適用於此 API。 因此， 服務主體或受控識別 無法建立或管理 PAT。
• 先前的 PAT 生命週期管理 API 僅支援 user_impersonation 範圍，但現在 vso.pats 已提供 ，且建議的範圍可搭配這些 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 儲存在安全的金鑰管理解決方案中，例如 Azure KeyVault。
• 透過 UI 或 PAT 生命週期管理 API 定期更新或重新生成您的 PAT。
• 不再需要時撤銷 PAT。
• 旋轉您的 PATs，使用 新的 PAT 格式，以便透過我們的第一方工具更佳地偵測和撤銷洩漏的秘密。

適用於系統管理員

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

常見問題集

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

答：登入您的 PAT 範圍所在組織。 當您登入相同 Microsoft Entra 識別碼中的任何組織時，您可以變更 存取範圍 篩選來檢視您的 PAT，但只能在登入特定組織時編輯組織範圍的 token。

問：如果停用用戶帳戶，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。 額外的標頭也必須包含 Base64 編碼的 user:PAT。

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。

問：在 Azure DevOps 令牌清單中，到期、撤銷或非使用中 PAT 的顯示時間長度為何？

答：已過期或撤銷的 PAT 無法再使用或重新產生。 這些非使用中的令牌會在到期或撤銷后持續顯示數個月，然後自動從顯示器中移除。

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

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

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

答：否，PAT 屬於使用者身分識別。 Microsoft Entra 服務主體或受控識別 可以產生短暫的 Microsoft Entra 令牌，您可以於大多數接受 PAT 的位置中使用。 深入瞭解 我們在 Azure DevOps 之間減少 PAT 使用量的努力 ，並探索使用 Microsoft Entra 令牌取代 PAT。

相關文章

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