使用 REST API 管理个人访问令牌 (PAT)

项目
10/25/2024

Azure DevOps Services

处理自己拥有的大量个人访问令牌（PAT）时，仅使用 UI 管理这些令牌的维护可能会变得复杂。

借助 PAT 生命周期管理 API，你可以通过自动化流程轻松管理与组织关联的 PAT。通过此丰富的 API 集，可以管理 PAT，从而创建新的 PAT 并续订或过期现有 PAT。

在这篇文章中，我们介绍如何将应用程序配置为使用 Microsoft Entra 令牌进行身份验证并使用 PAT 生命周期 API 进行调用。如果只想查看可用终结点的完整列表，请在此处查看 API 参考。

先决条件

权限： 根据租户的安全策略，应用程序可能需要访问组织中的资源的权限。目前，在此租户中继续使用此应用的唯一方法是要求管理员授予对应用的权限，然后才能使用它。

身份验证:
- 若要使用 API，请通过 Microsoft Entra ID OAuth 通过 Microsoft Entra 令牌进行身份验证。有关详细信息，请参阅身份验证部分。
- 拥有具有活动 Azure 订阅的 Microsoft Entra 租户。

注意

不能使用服务主体或托管标识来创建或撤销 PAT。

使用 Microsoft Entra 令牌进行身份验证

与其他 Azure DevOps Services API 不同，用户必须提供 Microsoft Entra 访问令牌才能使用此 API 而不是 PAT。 Microsoft Entra 令牌是比使用 PAT 更安全的身份验证机制。鉴于此 API 能够创建和撤销 PAT，我们希望确保仅向允许的用户提供如此强大的功能。

若要获取和刷新Microsoft Entra 访问令牌，请执行以下操作：

重要

“代表应用程序”解决方案（如“客户端凭据”流）和未颁发Microsoft Entra 访问令牌的任何身份验证流都不适用于此 API。如果在 Microsoft Entra 租户中启用了多重身份验证，则必须使用 “授权代码”流。

有了一个具有处理 Microsoft Entra 令牌的工作身份验证流的应用程序后，可以使用这些令牌调用 PAT 生命周期管理 API。

若要直接调用 API，请在请求标头中Authorization提供一个Microsoft Entra 访问令牌作为Bearer令牌。有关详细信息和可用请求的完整列表，请参阅 PAT API 参考。

在以下部分中，我们将演示如何创建使用 Microsoft Entra 访问令牌对用户进行身份验证的应用。该应用使用Microsoft身份验证库（MSAL）库并调用 PAT 生命周期管理 API。

MSAL 包括多个合规的身份验证流，可在应用中用于获取和刷新 Microsoft Entra 令牌。可以在Microsoft身份验证库身份验证流文档下找到 MSAL 流的完整列表。可以在为 Azure DevOps 选择正确的身份验证方法下找到为应用程序选择正确的身份验证方法的指南。

若要开始，请参阅以下示例之一：

克隆示例 Python Flask 应用，并将其配置为租户和 ADO 组织
在Azure 门户中为所选语言生成示例应用程序，并将其配置为 PAT 生命周期管理 API

克隆 Python Flask Web 应用

我们提供了此 API 的示例 Python Flask Web 应用程序，可在 GitHub 上下载，并配置为与 Microsoft Entra 租户和 Azure DevOps 组织一起使用。示例应用程序使用 MSAL 身份验证代码流来获取Microsoft Entra 访问令牌。

重要

建议在 GitHub 上开始使用示例 Python Flask Web 应用程序，但如果想要使用其他语言或应用程序类型，请使用快速入门选项重新创建等效的测试应用程序。

克隆示例应用后，请按照存储库自述文件中的说明进行操作。 README 介绍如何在 Microsoft Entra 租户中注册应用程序、配置示例以使用 Microsoft Entra 租户并运行克隆的应用。

生成快速入门Azure 门户应用程序

相反，可以使用Azure 门户应用程序页面上的“快速入门”选项生成包含生成的 MSAL 代码的示例应用。快速入门测试应用程序遵循授权代码流，但使用Microsoft图形 API 终结点执行此操作。用户需要更新应用程序的配置，以指向 PAT 生命周期管理 API 的终结点。

若要遵循此方法，请按照 Microsoft Entra ID 开发文档主页上所选应用程序类型的快速入门说明进行操作。我们使用 Python Flask 快速入门应用演练以下示例。

示例：Python Flask 快速入门应用程序入门

在具有活动 Azure 订阅的 Microsoft Entra 租户中注册应用程序后，请在Azure 门户中的 Microsoft Entra ID ->App Registrations 下导航到已注册的应用程序。
选择应用程序并导航到 API 权限。
选择“ 添加权限 ”，然后选择“ Azure DevOps ” -> 选中 user_impersonation -> 选择“ 添加权限”。
选择 “快速入门”。
选择应用程序类型：对于 Python Flask，请选择 Web 应用程序。
选择应用程序平台。对于本教程，请选择“Python”。
请确保满足必要的先决条件，然后允许Azure 门户进行必要的更改来配置应用程序。回复 URL 是在创建应用程序时设置的重定向 URL + “/getAToken”。
下载快速入门应用程序并提取文件。
安装应用程序要求并运行应用程序，以确保拥有所有必要的依赖项。应用程序最初配置为在 Microsoft Graph API 中命中终结点。按照以下部分中的配置说明了解如何将此终结点更改为 PAT 生命周期管理 API 基本终结点。

配置快速入门应用程序

用户下载并安装快速入门应用程序后，它将配置为从 Microsoft Graph 使用测试 API 终结点。修改生成的配置文件，使其改为调用 PAT 生命周期管理 API。

提示

在这些文档中可互换使用集合和组织。如果配置变量需要集合名称，请将它替换为组织名称。

执行以下任务：

将 ENDPOINT 配置变量更新为 https://vssps.dev.azure.com/{YOUR_COLLECTION_NAME_HERE}/_apis/Tokens/Pats?api-version=6.1-preview PAT 生命周期管理 API
将 SCOPE 配置变量更新为 “499b84ac-1321-427f-aa17-267ca6975798/.default” ，以引用 Azure DevOps 资源及其所有范围。

以下示例演示如何为上一部分中的 Azure 门户生成的快速入门 Python Flask 应用程序执行此配置。

请确保按照说明保护客户端密码，该密码最初以纯文本形式插入应用程序配置文件。最佳做法是从配置文件中删除纯文本变量，并使用环境变量或 Azure KeyVault 来保护其应用程序的机密。

相反，可以选择使用证书而不是客户端密码。如果应用程序在生产环境中使用，则建议使用证书。有关使用证书的说明，请参阅快速入门应用程序设置的最后一步。

注意

切勿在生产应用程序代码中保留纯文本客户端密码。

示例：为 PAT 生命周期管理 API 配置 Python Flask 快速入门应用程序

下载快速入门应用程序、安装其依赖项并测试它在环境中运行后，请在 app_config.py 所选编辑器中打开该文件。该文件应类似于以下代码片段;为清楚起见，引用默认Microsoft图形 API 配置的注释已删除：

import os

CLIENT_ID = "YOUR_CLIENT_ID_HERE" 
# Application (client) ID of app registration

CLIENT_SECRET = "YOUR_CLIENT_SECRET_HERE" 
# Placeholder - for use ONLY during testing.
# In a production app, we recommend you use a more secure method of storing your secret,
# like Azure Key Vault. Or, use an environment variable as described in Flask's documentation:
# https://flask.palletsprojects.com/en/1.1.x/config/#configuring-from-environment-variables
# CLIENT_SECRET = os.getenv("CLIENT_SECRET")
# if not CLIENT_SECRET:
#     raise ValueError("Need to define CLIENT_SECRET environment variable")

AUTHORITY = "https://login.microsoftonline.com/YOUR_AAD_TENANT_ID_HERE"  # For multi-tenant app
# AUTHORITY = "https://login.microsoftonline.com/Enter_the_Tenant_Name_Here"

REDIRECT_PATH = "/getAToken"  
# Used for forming an absolute URL to your redirect URI.
# The absolute URL must match the redirect URI you set
# in the app's registration in the Azure portal.

ENDPOINT = 'https://graph.microsoft.com/v1.0/users'  

SCOPE = ["User.ReadBasic.All"]

SESSION_TYPE = "filesystem"  
# Specifies the token cache should be stored in server-side session

使用应用注册的客户端 ID 和客户端密码将客户端 ID 或客户端密码更新到应用程序。在生产环境中时，请确保使用环境变量、Azure KeyVault 或切换到证书来保护客户端密码。

CLIENT_ID = "YOUR_CLIENT_ID_HERE" 
# Application (client) ID of app registration

CLIENT_SECRET = "YOUR_CLIENT_SECRET_HERE" 
# Placeholder - for use ONLY during testing.
# In a production app, we recommend you use a more secure method of storing your secret.

将 ENDPOINT 变量更改为 Azure DevOps 集合 URL 和 API 终结点。例如，对于名为“testCollection”的集合，该值为：

# Fill in the url to the user's ADO collection + the PAT lifecycle management API endpoint here

ENDPOINT = 'https://vssps.dev.azure.com/{YOUR_COLLECTION_NAME_HERE}/_apis/Tokens/Pats?api-version=6.1-preview'

对于名为“testCollection”的集合，此终结点为：

ENDPOINT = 'https://vssps.dev.azure.com/testCollection/_apis/Tokens/Pats?api-version=6.1-preview'

更改 SCOPE 变量以引用 Azure DevOps API 资源;字符串是 Azure DevOps API 的资源 ID，范围 .default 引用该资源 ID 的所有范围。
```
SCOPE = ["499b84ac-1321-427f-aa17-267ca6975798/.default"]
```

如果为特定租户（而不是多租户配置）配置应用程序，请使用变量的 AUTHORITY 备用值，在“Enter_the_Tenant_Name_Here”中添加特定租户名称。

# For single-tenant app:
AUTHORITY = "https://login.microsoftonline.com/YOUR_AAD_TENANT_ID_HERE"

# For multi-tenant app:
AUTHORITY = "https://login.microsoftonline.com/Enter_the_Tenant_Name_Here"

使用CLIENT_ID、租户 ID 和集合 URL 验证最终 app_config.py 文件是否与以下内容匹配。出于安全原因，请确保CLIENT_SECRET已移到环境变量、Azure KeyVault 或已交换到已注册应用程序的证书：

import os

CLIENT_ID = "YOUR_CLIENT_ID_HERE" 
# Application (client) ID of app registration

# Note that the CLIENT_SECRET has been removed and moved to an environment variable or Azure KeyVault

AUTHORITY = "https://login.microsoftonline.com/YOUR_AAD_TENANT_ID_HERE"  # For multi-tenant app
# AUTHORITY = "https://login.microsoftonline.com/Enter_the_Tenant_Name_Here"

REDIRECT_PATH = "/getAToken"  
# Used for forming an absolute URL to your redirect URI.
# The absolute URL must match the redirect URI you set in the app's registration in the Azure portal.

ENDPOINT = 'https://vssps.dev.azure.com/testCollection/_apis/Tokens/Pats?api-version=6.1-preview' 
# Used to configure user's collection URL and the desired API endpoint

SCOPE = ["499b84ac-1321-427f-aa17-267ca6975798/.default"]
# Means "All scopes for the Azure DevOps API resource"

SESSION_TYPE = "filesystem"  
# Specifies the token cache should be stored in server-side session

重新运行应用程序以测试是否可以获取请求用户的所有 PAT 令牌。验证后，可以修改目录的内容 'app.py' ， 'ms-identity-python-webapp-master\templates' 以支持将请求发送到 PAT 生命周期管理 API 终结点的其余部分。有关已修改为支持所有 PAT 生命周期管理 API 终结点请求的 Python Flask 快速入门应用程序的示例，请参阅 GitHub 上的此示例存储库。

自动刷新Microsoft Entra 访问令牌

正确配置应用程序并用户获取访问令牌后，该令牌最多可以使用一小时。前面两个示例中提供的 MSAL 代码会在令牌过期后自动刷新。刷新令牌可防止用户再次登录并获取新的授权代码。但是，用户刷新令牌过期后可能需要在 90 天后再次登录。

探索 PAT 生命周期管理 API

在以前的 GitHub 示例应用程序和快速入门应用程序中，该应用程序已预先配置，以使用获取的 Microsoft Entra 令牌发出请求。有关详细信息，请参阅 API 参考文档。

常见问题 (FAQ)

问：为何需要使用 Microsoft Entra 令牌进行身份验证？为什么 PAT 不够？

答：使用此 PAT 生命周期管理 API，我们打开了创建新的 PAT 并撤销现有 PAT 的功能。在错误手中，恶意参与者可以使用此 API 创建组织的 Azure DevOps 资源的多个入口点。通过强制实施 Microsoft Entra 身份验证，我们希望能够更安全地使用此功能强大的 API，防止这种未经授权的使用。

问：是否需要具有具有活动 Azure 订阅的 Microsoft Entra 租户才能使用此 API？

答：遗憾的是，此 API 仅适用于具有活动 Azure 订阅的Microsoft Entra 租户的一部分。

问：是否可以获取另一种语言/框架/应用程序类型的此示例应用程序的示例？

答：我们非常希望以所选语言使用 API！如果有示例请求，请转到我们的开发社区，看看其他人是否有要共享的示例。如果你有一个想要向更大的 Azure DevOps 受众共享的示例应用程序，请告诉我们，我们可以更广泛地研究在这些文档中分发它！

问：此令牌 API 与令牌管理 API 有何区别？

答：此令牌 API 和令牌管理 API（类似）提供不同的用例和受众：

此令牌 API 主要适用于想要管理他们在自动化管道中拥有的 PAT 的用户。此 API 允许。它使你能够创建新令牌并更新现有令牌。
令牌管理 API 适用于组织管理员。管理员可以使用此 API 检索和撤销组织用户的个人访问令牌（PAT）和自描述会话令牌等 OAuth 授权。

问：如何通过 API 重新生成/轮换 PAT？我在 UI 中看到了该选项，但在 API 中看不到类似的方法。

答：好问题！ UI 中提供的“重新生成”功能实际上实现了一些操作，这些操作通过 API 完全可复制。

若要旋转 PAT，请执行以下步骤：

使用 GET 调用了解 PAT 的元数据，
使用 POST 调用创建具有旧 PAT 元数据的新 PAT，
使用 DELETE 调用撤销旧的 PAT

问：尝试使用此应用时，会看到“需要管理员批准”弹出窗口。如何在未经管理员批准的情况下使用此应用？

答：租户似乎具有安全策略，这要求向应用程序授予访问组织中的资源的权限。目前，在此租户中继续使用此应用的唯一方法是要求管理员授予对应用的权限，然后才能使用它。

问：尝试使用服务主体或托管标识调用 PAT 生命周期管理 API 时，为何会看到“不允许服务主体执行此操作”之类的错误？

答：不允许使用服务主体和托管标识。鉴于此 API 能够创建和撤销 PAT，我们希望确保仅向允许的用户提供如此强大的功能。

后续步骤

了解 PAT 生命周期管理 API 终结点

通过

使用 REST API 管理个人访问令牌 (PAT)

先决条件

使用 Microsoft Entra 令牌进行身份验证

克隆 Python Flask Web 应用

生成快速入门Azure 门户应用程序

示例：Python Flask 快速入门应用程序入门

配置快速入门应用程序

示例：为 PAT 生命周期管理 API 配置 Python Flask 快速入门应用程序

自动刷新Microsoft Entra 访问令牌

探索 PAT 生命周期管理 API

常见问题 (FAQ)

问：为何需要使用 Microsoft Entra 令牌进行身份验证？为什么 PAT 不够？

问：是否需要具有具有活动 Azure 订阅的 Microsoft Entra 租户才能使用此 API？

问：是否可以获取另一种语言/框架/应用程序类型的此示例应用程序的示例？

问：此令牌 API 与令牌管理 API 有何区别？

问：如何通过 API 重新生成/轮换 PAT？我在 UI 中看到了该选项，但在 API 中看不到类似的方法。

问：尝试使用此应用时，会看到“需要管理员批准”弹出窗口。如何在未经管理员批准的情况下使用此应用？

问：尝试使用服务主体或托管标识调用 PAT 生命周期管理 API 时，为何会看到“不允许服务主体执行此操作”之类的错误？

后续步骤

反馈

其他资源

通过

使用 REST API 管理个人访问令牌 (PAT)

先决条件

使用 Microsoft Entra 令牌进行身份验证

克隆 Python Flask Web 应用

生成快速入门Azure 门户应用程序

示例：Python Flask 快速入门应用程序入门

配置快速入门应用程序

示例：为 PAT 生命周期管理 API 配置 Python Flask 快速入门应用程序

自动刷新Microsoft Entra 访问令牌

探索 PAT 生命周期管理 API

常见问题 (FAQ)

问：为何需要使用 Microsoft Entra 令牌进行身份验证？ 为什么 PAT 不够？

问：是否需要具有具有活动 Azure 订阅的 Microsoft Entra 租户才能使用此 API？

问：是否可以获取另一种语言/框架/应用程序类型的此示例应用程序的示例？

问：此令牌 API 与令牌管理 API 有何区别？

问：如何通过 API 重新生成/轮换 PAT？ 我在 UI 中看到了该选项，但在 API 中看不到类似的方法。

问：尝试使用此应用时，会看到“需要管理员批准”弹出窗口。 如何在未经管理员批准的情况下使用此应用？

问：尝试使用服务主体或托管标识调用 PAT 生命周期管理 API 时，为何会看到“不允许服务主体执行此操作”之类的错误？

后续步骤

反馈

其他资源

问：为何需要使用 Microsoft Entra 令牌进行身份验证？为什么 PAT 不够？

问：如何通过 API 重新生成/轮换 PAT？我在 UI 中看到了该选项，但在 API 中看不到类似的方法。

问：尝试使用此应用时，会看到“需要管理员批准”弹出窗口。如何在未经管理员批准的情况下使用此应用？