使用個人存取權杖

發行項
12/27/2024

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

個人存取令牌（PAT）可作為驗證 Azure DevOps 的替代密碼。此 PAT 會識別您，並判斷存取範圍和範圍。因此，將 PAT 視為密碼的相同層級。

當您使用Microsoft工具時，Microsoft帳戶（MSA）或 Microsoft Entra 識別符是可辨識和支援的方法。如果您使用不支援Microsoft Entra 帳戶的工具，或不想與這些工具共用主要認證，PAT 可以是適當的替代方案。否則，我們建議盡可能使用 Microsoft Entra 令牌替代 PAT。

提示

建議您檢閱驗證指引，為您的需求選擇適當的驗證機制。本文件的頁面提供一些指引，說明在某些常見的 PAT 案例中，可能更適合使用 Microsoft Entra 的令牌。

您可以透過下列方法來管理 PAT：

使用者介面（UI）： 透過用戶設定，如本文所述。
PAT 生命週期管理 API
Git 憑證管理工具用於 Git 操作。認證管理員能促進令牌的管理。如果沒有，使用者每次都必須輸入其認證。

必要條件

權限：
- 有權存取和修改管理 PAT 的用戶設定。
  - 檢查許可權： 若要檢查您的許可權，請在 Azure DevOps 中執行下列其中一個程式：
    - 移至您的配置檔，然後選取 [用戶設定>個人存取令牌]。 如果您可以在這裡看到及管理您的 PAT，您具有必要的許可權。
    - 移至您的項目，然後選取 [項目設定>許可權]。 在清單中尋找您的用戶帳戶，並檢查指派給您的許可權。尋找與管理令牌或用戶設定相關的許可權。
- 如果您的組織有原則，Azure DevOps 系統管理員可能需要授與您特定許可權，或將您新增至允許清單以建立和管理 PAT。
- PAT 會連結到生成令牌的用戶帳戶。根據 PAT 所執行的工作，您自己可能需要更多的權限。
存取層級： 至少具有基本存取權。
安全性最佳做法：熟悉管理 PAT 安全性最佳做法。 只在必要時使用它們，並且一律定期輪替它們。

建立 PAT

登入您的組織 (https://dev.azure.com/{Your_Organization})。
從您的首頁開啟使用者設定，然後選取 [個人存取權杖]。
選取 [+ 新增權杖]。
為您的令牌命名、選取您想要使用令牌的組織，然後將令牌設定為在設定天數之後自動到期。
選取此令牌的範圍，以授權您的特定工作。

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

注意

您可能會受限於建立完整範圍的 PAT。如果是，您在 Microsoft Entra ID 中的 Azure DevOps 系統管理員已啟用原則，以將您限制為特定的自定義定義範圍集。如需詳細資訊，請參閱使用原則管理 PAT/限制建立完整範圍的 PAT。針對自定義定義的 PAT，存取元件治理 API vso.governance所需的範圍無法在 UI 中選取。
完成時，請複製權杖，並將其儲存在安全的位置。針對您的安全性，它不會再次顯示。

在 Azure DevOps 中驗證所需的任何位置使用 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 服務 Web 應用程式部署時，就會建立名為 “Service Hooks：： Azure App 服務：： Deploy Web app” 的令牌。
當您或系統管理員將 Web 負載測試設定為管線的一部分時，就會建立名為 “WebAppLoadTestCDIntToken” 的令牌。
設定Microsoft Teams整合延伸模組時，會建立名為“Microsoft Teams 整合”的令牌。

警告

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

使用 PAT

您的 PAT 可作為您的數位身分識別，就像密碼一樣。 PAT 可用來作為在本機執行一次性要求或建立應用程式的原型的快速方式。

重要

當您的程式代碼運作時，最好從基本身份驗證切換到 Microsoft Entra OAuth。 Microsoft Entra 令牌可以在任何使用 PAT 的地方使用，除非下面另有說明。

您可以在程式代碼中使用 PAT 來驗證 REST API 要求，並將工作流程自動化。若要這樣做，請在 HTTP 要求的授權標頭中包含 PAT。

Windows
Linux/macOS

若要透過 HTTP 標頭提供 PAT，請先將它 Base64 轉換成字串。下列範例示範如何使用 C# 轉換成 Base64 。


Authorization: Basic BASE64_USERNAME_PAT_STRING

然後，產生的字串可以做為 HTTP 標頭，格式如下。

下列範例使用 C# 中的 HttpClient 類別。

public static async void GetBuilds()
{
    try
    {
        var personalaccesstoken = "PATFROMWEB";

        using (HttpClient client = new HttpClient())
        {
            client.DefaultRequestHeaders.Accept.Add(
                new System.Net.Http.Headers.MediaTypeWithQualityHeaderValue("application/json"));

            client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic",
                Convert.ToBase64String(
                    System.Text.ASCIIEncoding.ASCII.GetBytes(
                        string.Format("{0}:{1}", "", personalaccesstoken))));

            using (HttpResponseMessage response = client.GetAsync(
                        "https://dev.azure.com/{organization}/{project}/_apis/build/builds?api-version=5.0").Result)
            {
                response.EnsureSuccessStatusCode();
                string responseBody = await response.Content.ReadAsStringAsync();
                Console.WriteLine(responseBody);
            }
        }
    }
    catch (Exception ex)
    {
        Console.WriteLine(ex.ToString());
    }
}

提示

當您使用變數時，請在字串開頭新增 $ ，如下列範例所示。

public static async void GetBuilds()
{
   try
  {
      var personalaccesstoken = "PATFROMWEB";

      using (HttpClient client = new HttpClient())
       {
           client.DefaultRequestHeaders.Accept.Add(
              new System.Net.Http.Headers.MediaTypeWithQualityHeaderValue("application/json"));

           client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic",
               Convert.ToBase64String(
                   System.Text.ASCIIEncoding.ASCII.GetBytes(
                       string.Format("{0}:{1}", "", personalaccesstoken))));

          using (HttpResponseMessage response = client.GetAsync(
                       $"https://dev.azure.com/{organization}/{project}/_apis/build/builds?api-version=5.0").Result)
           {
               response.EnsureSuccessStatusCode();
               string responseBody = await response.Content.ReadAsStringAsync();
               Console.WriteLine(responseBody);
           }
       }
   }
   catch (Exception ex)
   {
       Console.WriteLine(ex.ToString());
   }
}

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


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

如需如何使用 PAT 的更多範例，請參閱下列文章：

修改 PAT

請執行下列步驟：

重新產生 PAT 以建立新的權杖，使前一個令牌失效。
延長 PAT 以增加其有效期間。
變更 PAT 的範圍以變更其許可權。

從首頁開啟您的使用者設定，然後選取 [配置檔]。
在 [安全性] 底下，選取 [ 個人存取令牌]。選取您要修改的令牌，然後 選取 [編輯]。
編輯令牌名稱、令牌到期或與令牌相關聯的存取範圍，然後選取 [ 儲存]。

撤銷 PAT

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

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

從首頁開啟您的使用者設定，然後選取 [配置檔]。
在 [安全性] 底下，選取 [ 個人存取令牌]。選取您要撤銷存取權的令牌，然後選取 [ 撤銷]。
在確認對話框中選取 [ 撤銷 ]。

如需詳細資訊，請參閱撤銷系統管理員的使用者 PAT。

格式的變更

自 2024 年 7 月起，我們已大幅變更 Azure DevOps 所發行的 PAT 格式。這些變更可提供更多安全性優點，並透過我們洩露的 PAT 偵測工具，或合作夥伴供應專案取得的秘密偵測工具。這個新的 PAT 格式會遵循所有Microsoft產品的建議格式。包含更多可識別的位可改善這些秘密偵測工具的誤判偵測率，並讓我們更快速地減輕偵測到的洩漏。

重要變更：

增加令牌長度： 新的令牌現在 長度為84 個字元，且有52個字元是隨機化數據。這個增加的長度可改善整體 Entropy，讓令牌對潛在的暴力密碼破解攻擊更具抵抗力。
已修正簽章： 我們服務發出的令牌包含 76-80 位置的固定 AZDO 簽章。

需要採取動作：

重新產生現有的 PAT： 強烈建議重新產生目前使用的所有 PAT，以利用這些安全性增強功能。
整合者支援： 整合者應該更新其系統，以容納新的和現有的令牌長度。

重要

這兩種格式在可預見的未來仍然有效，但我們 積極鼓勵客戶轉換到新的84個字元格式。隨著新格式的採用增加，我們考慮淘汰舊版 52 個字元的格式，以及該樣式發行的所有令牌。

PAT 最佳做法

ALWAYS 將您的 PAT 儲存在安全密鑰管理解決方案中，例如 Azure KeyVault。
請盡可能使用認證管理員，例如 Git 認證管理員或 Azure Artifacts Credential Manager，讓認證管理變得簡單。這些工具可以選擇使用 Microsoft Entra 令牌，而不是 PAT。
建立 PAT 時，請勿將任何個人標識資訊（PII）放在 PAT 名稱中。請勿將 PAT 令牌字串重新命名為令牌的名稱。
如果您的 PAT 不需要存取多個組織，請只選擇它需要存取的組織。如果您有需要 PAT 才能存取多個組織的工作流程，請只針對該工作流程建立個別的全域 PAT。
僅針對每個 PAT 選擇所需的範圍。如果可能，為每個工作流程建立多個範圍較小的 PAT，而不是單一完整範圍的 PAT。如果您的 PAT 只需要讀取許可權，除非有必要，否則請勿提供寫入許可權。
保持 PAT 的有效期限短（每週），並定期更換或重生它們。在UI上或透過 PAT 生命週期管理 API執行此動作。
租用戶管理員可以設定原則，以限制全域 PAT 的建立、完整範圍 PAT 的建立，以及長期 PAT 的有效期限。它們也可以讓原則自動撤銷在公用存放庫中偵測到的外洩 PAT。使用這些原則來改善公司的安全性。
不再需要 PAT 時撤銷。如果 PAT 遭到入侵，租使用者管理員可以撤銷其組織使用者的 PAT。
更換您的 PAT，以使用新的 PAT 格式，以便更好地偵測洩漏的秘密。

常見問題集

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

答：請確定您已登入已設定 PAT 範圍的組織。您可以在登入相同Microsoft Entra 識別符的任何組織時，檢視所有 PAT，但是當您登入其範圍所在的組織時，您只能編輯組織範圍的令牌。

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

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

問：是否有辦法透過 REST API 更新 PAT？

答：是，有一種方式可以使用我們的 PAT 生命週期管理 API 來更新、管理及建立 PAT。

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

A: 不可以。您可以搭配大部分的 Azure DevOps REST API 使用基本身份驗證，但組織和設定檔，以及 PAT 管理生命週期 API僅支援 Microsoft Entra OAuth。如需如何設定 Entra 應用程式以呼叫這類 API 的範例，請參閱使用 REST API 管理 PAT 檔案。

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

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

如需詳細資訊，請參閱自動撤銷外洩的 PAT。

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

A: 不可以。 Azure Artifacts 不支援傳遞個人存取權杖做為 ApiKey。使用本機開發環境時，建議您安裝 Azure Artifacts Credential Provider，以向 Azure Artifacts 進行驗證。如需詳細資訊，請參閱下列範例：dotnet、NuGet.exe。如果您想要使用 Azure Pipelines 發佈套件，請使用 NuGet 驗證工作來向摘要範例進行驗證。

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

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

PAT 可能失敗的一些已知原因：

針對 Azure DevOps Server，啟用 IIS 基本身份驗證會使使用 PAT 失效。請參閱在內部部署的 Azure DevOps 中使用 IIS 基本身份驗證。

問：如何? 建立未系結至特定人員以進行部署的存取密鑰？

答：在 Azure DevOps 中，您可以使用服務主體或管理身分識別，建立未繫結至特定人員的存取密鑰。如需詳細資訊，請參閱管理服務連線、在 Azure Pipelines 中使用 Azure 金鑰保存庫秘密。

：：： moniker-end

共用方式為

使用個人存取權杖

必要條件

建立 PAT

通知

未預期的通知

使用 PAT

修改 PAT

撤銷 PAT

格式的變更

PAT 最佳做法

常見問題集

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

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

問：是否有辦法透過 REST API 更新 PAT？

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

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

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

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

問：如何? 建立未系結至特定人員以進行部署的存取密鑰？

意見反應

其他資源

共用方式為

使用個人存取權杖

必要條件

建立 PAT

通知

未預期的通知

使用 PAT

修改 PAT

撤銷 PAT

格式的變更

PAT 最佳做法

常見問題集

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

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

問：是否有辦法透過 REST API 更新 PAT？

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

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

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

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

問：如何? 建立未系結至特定人員以進行部署的存取密鑰？

相關文章

意見反應

其他資源