使用个人访问令牌

项目
06/14/2024

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

个人访问令牌（PAT）可用作对 Azure DevOps 进行身份验证的替代密码。本文指导你完成为 Azure DevOps 创建、利用、修改和撤销 PAT 的过程。

关于 PAT

个人访问令牌（PAT）充当 Azure DevOps 的安全凭据。此 PAT 不仅标识你，而且还确定可访问性和访问范围。因此，PAT 与密码一样重要，应谨慎处理。

如果使用Microsoft工具，则Microsoft帐户（MSA）或Microsoft Entra ID 是可识别和支持的方法。但是，如果你使用的是不支持Microsoft或Microsoft Entra 帐户的第三方工具，或者如果你不愿意与这些工具共享主要凭据，则 PAT 是更安全的替代方法。

通过以下两种方式创建和管理 PAT：

用户界面（UI）： 通过用户设置，如本文所述
PAT 生命周期管理 API

若要为非Microsoft工具建立 PAT，可以使用 Git 凭据管理器或手动生成它们。建议查看身份验证指南，以帮助你选择适当的身份验证机制。 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 ID 提供支持的组织，必须在 90 天内使用新 PAT 登录;未能使 PAT 处于非活动状态。有关详细信息，请参阅条件访问的用户登录频率。

通知

在 PAT 的生命周期内，用户会收到两条通知-创建时第一个通知，第二个通知在过期前七天收到。

创建 PAT 后，会收到类似于以下示例的通知。此通知用于确认 PAT 已成功添加到组织。

显示 PAT 创建的通知的屏幕截图。

下图显示了 PAT 过期前的七天通知示例。

显示 PAT 即将过期通知的屏幕截图。

有关详细信息，请参阅配置 SMTP 服务器并为警报和反馈请求自定义电子邮件。

意外通知

如果收到意外的 PAT 通知，则可能意味着管理员或工具为你创建了 PAT。下面是一些示例。

通过 git.exe 连接到 Azure DevOps Git 存储库时，将创建名为“git： https://MyOrganization.visualstudio.com/ on MyMachine”的令牌。
由你或管理员设置Azure App 服务 Web 应用部署时，将创建名为“服务挂钩：：Azure App 服务：：部署 Web 应用”的令牌。
当你或管理员将 Web 负载测试设置为管道的一部分时，将创建名为“WebAppLoadTestCDIntToken”的令牌。
设置 Microsoft Teams Integration Messaging 扩展时，将创建名为“Microsoft Teams 集成”的令牌。

警告

如果怀疑 PAT 存在错误，请考虑撤销 PAT 并更改密码。作为Microsoft Entra 用户，请与管理员联系，查看组织是否由未知源或位置使用。此外，请参阅有关意外的 PAT 签入到公共 GitHub 存储库的常见问题解答。

使用 PAT

PAT 充当数字标识，表示使用时，就像密码一样。

Git

Git 交互需要用户名，该用户名可以是空字符串以外的任何内容。若要将 PAT 与 HTTP 基本身份验证配合使用，请使用Base64-encode$MyPat以下代码块中包含的 PAT。

Windows
Linux/macOS

在 PowerShell 中，输入以下代码。

$MyPat = 'yourPat'
$headerValue = "Authorization: Basic " + [Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes(":" + $MyPat))
$env:GIT_AUTH_HEADER = $headerValue

git --config-env=http.extraheader=GIT_AUTH_HEADER clone https://dev.azure.com/yourOrgName/yourProjectName/_git/yourRepoName

若要使令牌更安全，请使用凭据管理器，这样就不必每次都输入凭据。建议使用 Git 凭据管理器。需要适用于 Windows 的 Git。

在 Bash 中，输入以下代码。

MY_PAT=yourPAT # replace "yourPAT" with "PatStringFromWebUI"
HEADER_VALUE=$(printf "Authorization: Basic :%s" "$MY_PAT" | base64)

git --config-env=http.extraheader=HEADER_VALUE clone https://dev.azure.com/yourOrgName/yourProjectName/_git/yourRepoName

若要使令牌更安全，请使用凭据管理器，这样就不必每次都输入凭据。建议使用 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。

Windows
Linux/macOS

若要通过 HTTP 标头提供 PAT，请先将其转换为 Base64 字符串。以下示例演示如何转换为 Base64 使用 C# 。


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

代码正常工作时，最好从基本身份验证切换到 OAuth。

有关如何使用 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 轮换到另一个用户或服务帐户，以使服务保持运行。

问：是否有办法通过 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。

问：是否可以使用个人访问令牌作为 ApiKey，使用 dotnet/nuget.exe 命令行将 NuGet 包发布到 Azure Artifacts 源？

答：否。 Azure Artifacts 不支持将个人访问令牌作为 ApiKey 传递。在使用本地开发环境时，建议安装 Azure Artifacts 凭据提供程序，以对 Azure Artifacts 进行身份验证。有关详细信息，请参阅以下示例：dotnet 和 NuGet.exe。如果要使用 Azure Pipelines 发布包，请使用 NuGet 身份验证任务通过源示例进行身份验证。

问：为什么我的 PAT 停止工作？

答：PAT 身份验证要求你定期使用完整的身份验证流登录到 Azure DevOps。每 30 天一次就足以满足许多人的需求，但根据Microsoft Entra 配置，可能需要更频繁地登录。如果 PAT 停止工作，请先尝试登录到组织，确保完成完整的身份验证提示。如果 PAT 在那之后仍然不起作用，请检查 PAT 是否已过期。

通过