使用个人访问令牌

项目
12/30/2024

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。

提示

我们建议查看我们的身份验证指南，以根据需要选择适当的身份验证机制。在我们的文档中，此页面提供了一些指导，说明在某些常见的 PAT 方案中，可能更适合使用 Microsoft Entra 令牌。

可以通过以下方法管理 PAT：

用户界面 (UI)）： 通过用户设置，如本文所述。
PAT 生命周期管理 API
用于 Git 操作的Git 凭证管理器。凭据管理器有助于进行令牌管理。如果没有凭据，用户每次都必须输入其凭据。

先决条件

权限：
- 有权访问和修改管理 PAT 的用户设置。
  - 检查权限： 若要检查权限，请在 Azure DevOps 中执行以下任一过程：
    - 转到配置文件并选择“>”。如果在此处可以看到和管理 PAT，则具有必要的权限。
    - 转到项目并选择“项目设置>权限”。 在列表中查找用户帐户，并检查分配给你的权限。查找与管理令牌或用户设置相关的权限。
- 如果组织已制定策略，Azure DevOps 管理员可能需要授予特定权限，或将你添加到允许列表来创建和管理 PAT。
- PATs 连接到生成令牌的用户帐户。根据 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 充当数字标识，就像密码一样。 PAT 可用作在本地执行一次性请求或原型应用程序的快速方法。

重要

代码正常工作时，最好从基本身份验证切换到 Microsoft Entra OAuth。在任何可以使用 PAT 的地方，都可以使用 Microsoft Entra 令牌，除非下面另有说明。

可以在代码中使用 PAT 对 REST 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

有关如何使用 PAT 的更多示例，请参阅以下文章：

修改 PAT

执行以下步骤：

重新生成 PAT 以创建新令牌，使上一个令牌失效。
延长 PAT 以增加其有效期。
更改 PAT 的范围以更改其权限。

在主页中，打开用户设置，然后选择“ 配置文件”。
在“安全性”下，选择“ 个人访问令牌”。选择要修改的令牌，然后选择 “编辑”。
编辑令牌名称、令牌过期或与令牌关联的访问范围，然后选择“ 保存”。

撤销 PAT

可以随时出于以下原因和其他原因撤销 PAT：

如果你怀疑它遭到入侵，则撤销 PAT。
不再需要 PAT 时将其撤销。
撤销 PAT 以强制实施安全策略或合规性要求。

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

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

对格式的更改

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

关键更改：

增加令牌长度： 新令牌的长度现在 为 84 个字符，52 个字符是随机数据。这种增加的长度提高了整体萎缩性，使令牌对潜在的暴力攻击更具抵抗力。
已修复签名： 我们的服务颁发的令牌包括位于 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 ID 中登录到任何组织时，可以查看所有 PAT，但只能在登录到其范围的组织时编辑组织范围的令牌。

问：如果用户帐户被禁用，PAT 会发生什么情况？

答：从 Azure DevOps 中删除用户时，PAT 在 1 小时内失效。如果组织已连接到 Microsoft Entra ID，则 PAT 也会在Microsoft Entra ID 中失效，因为它属于用户。建议将 PAT 轮换到另一个用户或服务帐户，以使服务保持运行。

问：是否有办法通过 REST API 续订 PAT？

答：是的，可以使用 PAT 生命周期管理 API 续订、管理和创建 PAT。

问：是否可以将 PAT 用于所有 Azure DevOps REST API？

答: 不是。可以将基本身份验证与大多数 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 源？

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

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

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

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

使用 Azure DevOps Server 的 IIS 基本身份验证会导致不能使用个人访问令牌 (PAT)：请参阅了解在本地环境中将 IIS 基本身份验证与 Azure DevOps 配合使用。

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

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

::: moniker-end

通过