使用個人存取權杖

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

您可以使用個人存取權杖 (PAT) 作為替代密碼,向 Azure DevOps 進行驗證。 在本文中,我們會示範如何建立、使用、修改和撤銷 Azure DevOps 的 PAT。

關於 PAT

個人存取權杖包含 Azure DevOps 的安全性認證。 PAT 可識別您、您可存取的組織,以及存取範圍。 其與密碼一樣重要,因此應該以相同的方式看待。

如果您是在 Microsoft 工具內工作,則您的 Microsoft 帳戶 (MSA) 或 Azure Active Directory (Azure AD) 是可接受的良好支援方法。 但是,如果您使用不支援 Microsoft 或 Azure AD 帳戶的協力廠商工具,或不想將主要認證提供給工具,請使用 PAT 來限制您的風險。

您可以透過下列其中一種方式來建立和管理 PAT:

若要為非Microsoft工具設定 PAT,請使用Git 認證管理員或手動建立它們。 建議您檢閱我們的 驗證指引 ,以協助您選擇正確的驗證機制。 對於較不需要健全解決方案的較小專案,PAT 是簡單的替代方案。 除非您的使用者使用認證管理員,否則他們必須每次輸入其認證。

建立 PAT

注意

您從入口網站看到的影像可能與本文中看到的影像不同。 這些差異源自對 Azure DevOps 或已啟用預覽功能的更新。 我們已啟用 [新增帳戶管理員] 頁面 功能。 除非您明確提及,否則可用的基本功能會維持不變。

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

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

    顯示選取專案個人存取權杖的螢幕擷取畫面。

  3. 選取 [+ 新增權杖]。

    顯示選取專案[新增權杖] 的螢幕擷取畫面。

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

    顯示基本權杖資訊專案的螢幕擷取畫面。

  5. 選取此權杖 的範圍 ,以授權 您的特定工作

    例如,若要建立權杖,讓組建和發行代理程式能夠向Azure DevOps Services進行驗證,請將權杖的範圍限制為代理程式組件區, (讀取 & 管理) 。 若要讀取稽核記錄事件,以及管理和刪除資料流程,請選取 [ 讀取稽核記錄],然後選取 [ 建立]。

    顯示 PAT 所選範圍的螢幕擷取畫面。

    注意

    您可能會在建立完整範圍的 PAT 上受到限制。 如果是,表示您 Azure AD 中的 Azure DevOps 管理員已啟用原則,將您限制在一組特定的自訂定義範圍。 如需詳細資訊,請參閱 使用原則管理 PAT/限制建立完整範圍的 PAT。 針對自訂定義的 PAT,在 UI 中無法選取存取元件控管 API vso.governance 的必要範圍。

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

    顯示如何將權杖複製到剪貼簿的螢幕擷取畫面。

警告

請像密碼一樣處理並使用 PAT,並將它保留為秘密。

  1. 登入您的入口網站 (https://{server}:8080/tfs/) 。

  2. 從首頁開啟您的設定檔。 移至您的安全性詳細資料。

    顯示首頁、開啟設定檔和 [安全性] 按鈕的螢幕擷取畫面。

  3. 建立個人存取權杖。

    顯示新增個人存取權杖的螢幕擷取畫面。

  4. 為您的權杖命名。 選取權杖的生命週期。

    如果您有多個組織,您也可以選取想要使用權杖的組織。

    顯示資訊專案的螢幕擷取畫面,包括權杖名稱和存留期。

  5. 選取此權杖 的範圍 ,以授權 您的特定工作

    例如,若要建立權杖以啟用 組建和發行代理程式 進行驗證,請將權杖的範圍限制為代理程式組件區, (讀取、管理)

  6. 當您完成時,請務必 複製權杖。 針對您的安全性,系統不會再次顯示。 使用此權杖作為密碼。 選取 [關閉]。

    顯示已建立權杖的螢幕擷取畫面。

在 Azure DevOps 中驗證需要使用者認證的任何位置使用 PAT。

重要

對於 Azure Active Directory 所支援的組織,您有 90 天的時間可以使用新的 PAT 登入,否則會被視為非使用中。 如需詳細資訊,請參閱 條件式存取的使用者登入頻率

通知

使用者在 PAT 存留期期間收到兩個通知 ,一個會在建立時收到,另一個會在到期前七天收到。

建立 PAT 之後,您會收到類似下列範例的通知。 此通知會確認您的 PAT 已新增至您的組織。

顯示 PAT 已建立通知的螢幕擷取畫面。

下圖顯示 PAT 到期前七天的通知範例。

顯示 PAT 接近到期通知的螢幕擷取畫面。

未預期的通知

如果您收到非預期的 PAT 通知,系統管理員或工具可能已代表您建立 PAT。 請參閱以下範例。

  • 當您透過 git.exe 連線到 Azure DevOps Git 存放庫時。 它會建立具有顯示名稱的權杖,例如 「git: https://MyOrganization.visualstudio.com/ on MyMachine」。
  • 當您或系統管理員設定Azure App 服務 Web 應用程式部署時,它會建立具有顯示名稱的權杖,例如「服務勾點::Azure App 服務::部署 Web 應用程式」。
  • 當您或系統管理員將 Web 負載測試設定為管線的一部分時,它會建立具有顯示名稱的權杖,例如 「WebAppLoadTestCDIntToken」。
  • 設定 Microsoft Teams 整合通訊延伸模組時,它會建立具有顯示名稱的權杖,例如 「Microsoft Teams 整合」。

警告

如果您認為 PAT 存在錯誤,建議您 撤銷 PAT。 然後,變更您的密碼。 身為 Azure AD 使用者,請洽詢您的系統管理員,以查看您的組織是否從未知的來源或位置使用。 另請參閱 不小心簽入 PAT 至公用 GitHub 存放庫的常見問題。

使用 PAT

您的 PAT 是您的身分識別,並在您使用時代表您,就像密碼一樣。

Git

Git 互動需要使用者名稱,這可以是空字串以外的任何專案。 若要搭配 HTTP 基本驗證使用 PAT,請使用 Base64-encode$MyPat ,其包含在下列程式碼區塊中。

在 PowerShell 中,輸入下列程式碼。

$MyPat = 'yourPAT'

$B64Pat = [Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes("`:$MyPat"))

git -c http.extraHeader="Authorization: Basic $B64Pat" clone https://dev.azure.com/yourOrgName/yourProjectName/_git/yourRepoName


若要讓您的權杖更安全,請使用認證管理員,因此您不需要每次都輸入認證。 我們建議 使用 Git 認證管理員。 需要適用于 Windows 的 Git

現有的存放庫

針對現有的存放庫,如果您已使用使用者名稱新增來源,請先執行下列命令。

git remote remove origin

否則,請執行下列命令。

git remote add origin https://<PAT>@<company_machineName>.visualstudio.com:/<path-to-git-repo> path to git repo = <project name>/_git/<repo_name> git push -u origin --all

在您的程式碼中使用 PAT

您可以在程式碼中使用 PAT。

如果您想要透過 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());
   }
}

當您的程式碼運作時,最好從基本驗證切換到 OAuth

如需如何使用 PAT 的詳細資訊和範例,請參閱下列文章:

如果您啟用 TFS 的 IIS 基本驗證,則 PAT 無效。 如需詳細資訊,請參閱 在內部部署中使用 IIS 基本驗證與 TFS

修改 PAT

您可以重新產生或擴充 PAT,並修改其 範圍。 重新產生之後,先前的 PAT 已不再獲得授權。

  1. 從首頁開啟您的使用者設定,然後選取 [ 設定檔]。

    顯示要選取以修改 PAT 之按鈕順序的螢幕擷取畫面。

  2. 在 [安全性] 底下,選取 [個人存取權杖]。 選取您想要修改的權杖,然後 選取 [編輯]。

    顯示醒目提示 [編輯] 按鈕以修改 PAT 的螢幕擷取畫面。

  3. 編輯權杖名稱、套用至的組織、權杖到期或與權杖相關聯的存取範圍,然後選取 [ 儲存]。

    顯示已儲存 PAT 的螢幕擷取畫面。

撤銷 PAT

您可以隨時撤銷 PAT,因為各種原因。

  1. 從首頁開啟您的使用者設定,然後選取 [ 設定檔]。

    此螢幕擷取畫面顯示要選取的按鈕順序、Team Services、預覽頁面,以及撤銷 PAT。

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

    顯示撤銷單一權杖或所有權杖之選取範圍的螢幕擷取畫面。

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

    顯示撤銷 PAT 確認畫面的螢幕擷取畫面。

常見問題集

問:如果使用者帳戶已停用,PAT 會發生什麼事?

答:使用者從 Azure DevOps 移除之後,PAT 會在 1 小時內失效。 如果您的組織已連線到 Azure Active Directory (Azure AD) ,則 PAT 也會在 Azure AD 中失效,因為它屬於使用者。 我們建議使用者將其 PAT 輪替到另一個使用者或服務帳戶,讓服務保持執行。

問:是否有方法可透過 REST API 更新 PAT?

答:是,您可以使用 PAT 生命週期管理 API來更新、管理及建立 PAT。 如需詳細資訊,請參閱 使用 REST API 管理 PAT我們的常見問題

問:我是否可以搭配所有 Azure DevOps REST API 使用基本驗證?

答:否。 您可以搭配大部分的 Azure DevOps REST API 使用基本驗證,但 組織和設定檔 僅支援 OAuth。 如需詳細資訊,請參閱 使用 REST API 管理 PAT

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

答:Azure DevOps 會掃描已簽入 GitHub 上的公用存放庫的 PAT。 當我們找到外泄的權杖時,我們會立即傳送詳細的電子郵件通知給權杖擁有者,並將事件記錄至 Azure DevOps 組織的 稽核記錄。 我們鼓勵受影響的使用者藉由 輪替或撤銷外泄的 PAT立即減輕。

有一個管理外泄 PAT 的原則! 如需詳細資訊,請參閱 自動撤銷外泄的 PAT

問:是否可以使用個人存取權杖作為 ApiKey,使用 dotnet/nuget.exe 命令列將 NuGet 套件發佈至 Azure Artifacts 摘要?

答:否。 Azure Artifacts 不支援將個人存取權杖當作 ApiKey 傳遞。 使用本機開發環境時,建議您安裝 Azure Artifacts 認證提供者,以向 Azure Artifacts 進行驗證。 如需詳細資訊,請參閱下列範例: dotnetNuGet.exe。 如果您想要使用 Azure Pipelines 發佈套件,請使用 NuGet 驗證 工作以摘要 範例進行驗證。