使用 REST API 管理个人访问令牌（PAT）

项目
10/23/2023

Azure DevOps Services

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

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

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

先决条件

若要使用 API，必须使用 Microsoft Entra 令牌进行身份验证，该令牌可以通过 Microsoft Entra ID OAuth 完成。若要详细了解如何执行此操作，请参阅以下身份验证部分。

为此，必须满足一些先决条件：

必须具有具有活动 Azure 订阅的 Microsoft Entra 租户。
根据租户的安全策略，可能需要向应用程序授予访问组织中的资源的权限。目前，在此租户中继续使用此应用的唯一方法是要求管理员授予对应用的权限，然后才能使用它。

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

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

若要获取和刷新 Microsoft Entra 访问令牌，必须：

重要

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

注意

拥有具有活动 Azure 订阅的 Microsoft Entra 租户是使用此 API 的先决条件。

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

若要直接调用 API，需要提供 Microsoft Entra 访问令牌作为 Bearer 请求标头中的 Authorization 令牌。若要查看示例和可用请求的完整列表，请参阅 PAT API 参考

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

Microsoft 身份验证库（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 应用程序，但如果想要使用其他语言或应用程序类型，请使用快速入门选项重新创建等效的测试应用程序。

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

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

相反，可以使用Azure 门户应用程序页面上的“快速入门”选项生成包含生成的 MSAL 代码的示例应用。快速入门测试应用程序遵循授权代码流，但使用 Microsoft Graph 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 Graph 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_标准版CRET 移到环境变量、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 参考文档。

常见问题解答

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

答：使用此 PAT 生命周期管理 API，我们打开了创建新的 PAT 和撤销现有 PAT 的功能。在错误手中，恶意参与者可以使用此 API 来创建组织的 ADO 资源的多个入口点。通过强制实施 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 副本 (replica)。

若要旋转 PAT，需要：

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

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

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

后续步骤

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

使用 REST API 管理个人访问令牌（PAT）

先决条件

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

克隆 Python Flask Web 应用

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

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

配置快速入门应用程序

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

自动刷新 Microsoft Entra 访问令牌

探索 PAT 生命周期管理 API

常见问题解答

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

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

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

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

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

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

后续步骤

反馈

反馈

其他资源

使用 REST API 管理个人访问令牌（PAT）

先决条件

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

克隆 Python Flask Web 应用

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

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

配置快速入门应用程序

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

自动刷新 Microsoft Entra 访问令牌

探索 PAT 生命周期管理 API

常见问题解答

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

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

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

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

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

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

后续步骤

反馈

反馈

其他资源

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

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

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