使用个人访问令牌

项目
10/25/2024

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

个人访问令牌（PAT）充当用于向 Azure DevOps 进行身份验证的替代密码。此 PAT 可识别你并确定可访问性和访问范围。因此，请以与密码相同的谨慎级别对待 PAT。

使用Microsoft工具时，Microsoft帐户（MSA）或Microsoft Entra ID 是可识别和支持的方法。如果使用不支持Microsoft或Microsoft Entra 帐户的非Microsoft工具，或者不想与这些工具共享主凭据，则 PAT 是一种合适的替代方法。

本文指导你创建、使用、修改和撤销 Azure DevOps 的 PAT。

可以使用以下方法管理 PAT：

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

若要为非Microsoft工具建立 PAT，可以使用 Git 凭据管理器或手动生成它们。建议查看身份验证指南，选择适当的身份验证机制。 PAT 为不需要大量解决方案的小型项目提供了简单的替代方法。如果没有凭据管理器，用户每次都输入其凭据。

先决条件

权限：
- 有权访问和修改管理 PAT 的用户设置。
  - 检查权限： 若要检查权限，请在 Azure DevOps 中执行以下任一过程：
    - 转到配置文件并选择“用户设置>个人访问令牌”。如果在此处可以看到和管理 PAT，则具有必要的权限。
    - 转到项目并选择“项目设置>权限”。 在列表中查找用户帐户，并检查分配给你的权限。查找与管理令牌或用户设置相关的权限。
- 如果组织已制定策略，Azure DevOps 管理员可能需要授予特定权限，或将你添加到允许列表来创建和管理 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 ID 支持的组织在 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 Integration Messaging 扩展时，将创建名为“Microsoft Teams 集成”的令牌。

警告

如果怀疑它存在错误，请撤销 PAT。按照步骤撤消 PAT 并更改密码。
如果你是Microsoft Entra 用户，请与管理员联系，查看组织是否被未知源或位置访问。
查看有关意外通过 PAT 签入到公共 GitHub 存储库的常见问题解答。

使用 PAT

PAT 充当数字标识，就像密码一样。

Git

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

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"
export HEADER_VALUE=$(echo -n "Authorization: Basic "$(printf ":%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
使用 PAT 进行身份验证： 如果遇到标准身份验证问题，请运行以下命令，通过命令行进行身份验证：

git remote add origin https://dev.azure.com/<PAT>@<company_machineName>:/<project-name>/_git/<repo_name>

git push -u origin --all

指 path to git repo = /_git/do 用于 Git 存储库的 Azure DevOps 中使用的 URL 路径结构。该 /_git/ 段指示你正在访问 Git 存储库，应替换为 do 存储库的实际名称。例如，如果存储库命名my-repo，则路径为“”。/_git/my-repo
克隆存储库： 如果使用 Git 并需要进行身份验证，请运行以下命令：

git clone https://{organization}@dev.azure.com/{organization}/_git/{repository}

替换为 {organization} Azure DevOps 组织名称和 {repository} 存储库的名称。

在代码中使用 PAT

可以在代码中使用 PAT 对 API 请求进行身份验证并自动执行工作流。为此，请将 PAT 包含在 HTTP 请求的授权标头中。

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。
不再需要 PAT 时将其撤销。
撤销 PAT 以强制实施安全策略或合规性要求。

在主页中，打开用户设置，然后选择“ 配置文件”。
在“安全性”下，选择“ 个人访问令牌”。选择要为其撤消访问权限的令牌，然后选择“ 撤销”。
在确认对话框中选择“ 撤销 ”。

有关详细信息，请参阅为管理员撤销用户 PAT。

对格式的更改

截至 2024 年 7 月，我们显著改变了 Azure DevOps 颁发的 PAT 格式。这些更改提供了更多安全优势，并通过合作伙伴产品/服务（例如 GitHub Advanced Security for Azure DevOps）获得改进机密检测工具。此新的 PAT 格式遵循所有Microsoft产品的建议格式。包含更多可识别位可提高这些机密检测工具的误报检测率，使我们能够更快地缓解检测到的泄漏。

关键更改：

增加令牌长度： 新令牌的长度现在 为 84 个字符，52 个字符是随机数据。这种增加的长度提高了整体萎缩性，使令牌对潜在的暴力攻击更具抵抗力。
已修复签名： 我们的服务颁发的令牌包括位于 76-80 位置的固定 AZDO 签名。

需要执行操作：

重新生成现有 PAT： 强烈建议重新生成当前用于利用这些安全增强功能的所有 PAT。
集成器支持： 集成器应更新其系统，以适应新的令牌长度和现有令牌长度。

重要

这两种格式在可预见的将来仍然有效，但我们 积极鼓励客户过渡到新的 84 个字符的格式。随着新格式的采用增加，我们考虑停用旧版 52 个字符的格式和该样式中颁发的所有令牌。

常见问题

问：为什么无法编辑或重新生成范围限定为单个组织的 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 仍然不起作用，请检查它是否已过期。

问：如何实现创建不与特定人员关联的访问密钥以进行部署？

答：在 Azure DevOps 中，可以使用服务主体或管理标识创建不绑定到特定人员的访问密钥。有关详细信息，请参阅管理服务连接，在 Azure Pipelines 中使用 Azure 密钥库机密。

通过