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

Azure DevOps Services

当你处理大量个人访问令牌 (你拥有) 时,单独使用 UI 管理这些令牌的维护可能会变得复杂。

借助 PAT 生命周期管理 API,可以使用自动化流程轻松管理与组织关联的 PAT。 这组丰富的 API 使你能够管理你拥有的 PAT,使你能够创建新的个人访问令牌以及续订或过期现有的个人访问令牌。

本文将展示如何配置一个应用程序,该应用程序使用 Azure Active Directory (Azure AD) 令牌进行身份验证,以及如何使用 PAT 生命周期 API 进行调用。 如果只想查看可用终结点的完整列表,请 在此处查看 API 参考

先决条件

若要使用 API,必须使用令牌Azure AD身份验证。 在下面的身份验证部分中详细了解如何 这样做

为此,必须满足几个先决条件:

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

使用令牌Azure Active Directory (Azure AD) 身份验证

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

若要获取和刷新Azure AD令牌,必须:

重要

"代表应用程序"解决方案 (例如客户端凭据流) ,以及未颁发 Azure AD 访问令牌的任何身份验证流都不适用于 “” 此 API。 如果在租户中启用了多重Azure AD,则必须明确使用"授权代码 流"。

注意

具有Azure AD Azure 订阅的租户是使用此 API 的先决条件。

拥有具有用于处理令牌的工作身份验证流的应用程序Azure AD,可以使用这些令牌调用 PAT 生命周期管理 API。

若要直接调用 API,需要提供一个Azure AD令牌作为请求 BearerAuthorization 标头中的令牌。 若要查看示例和可用请求的完整列表,请参阅 PAT API 参考

在下面的部分中,我们将展示如何创建一个应用,该应用使用 MSAL 库通过 Azure AD 访问令牌对用户进行身份验证,并调用 PAT 生命周期管理 API。

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

按照以下两个示例之一开始:

克隆 Python Flask Web 应用

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

重要

我们建议在 GitHub 上开始使用示例 Python Flask Web 应用程序,但如果希望使用不同的语言或应用程序类型,请使用"快速入门"选项重新创建等效的测试应用程序。

克隆示例应用后,请按照存储库 ’ README 中的说明进行操作。 README 说明如何在 Azure AD 租户中注册应用程序、将示例配置为使用 Azure AD 租户,以及运行克隆的应用。

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

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

若要遵循此方法,请按照"开发文档"主页上的"快速入门"说明Azure AD选择的应用程序类型。 我们将演练为 Python Flask 快速入门应用完成此操作的示例。

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

  1. 在具有活动 Azure 订阅的 Azure AD 租户中注册应用程序后,导航到 Azure 门户 中的"Azure Active Directory -应用注册 "下的已注册Azure 门户。

    Open

  2. 选择应用程序并导航到"API 权限"。

    Select your application and navigate to

  3. 选择"添加权限",然后选择Azure DevOps - 选中user_impersonation - 选择"添加权限"。

    Add the

  4. 左侧导航面板 中选择"快速入门"。

  5. 选择应用程序类型:对于"Python Flask",请选择"Web 应用程序"。

  6. 选择应用程序平台。 对于本教程,请选择"Python"。

  7. 请确保已满足必要的先决条件,然后允许Azure 门户进行必要的更改来配置应用程序。 回复 URL 将是创建应用程序时设置的重定向 URL + /getAToken ” 。

    Allow the Azure portal to make the necessary changes to configure your application

  8. 下载快速入门应用程序并提取文件。

    Download the Quickstart application and extract the files

  9. 安装应用程序要求并运行应用程序,以确保具有所有必要的依赖项。 应用程序最初配置为命中 Microsoft Graph API 中的终结点。 按照以下部分中的配置说明管理 API将此终结点更改为 PAT 生命周期和基本终结点。

    Install the application requirements and run the application to ensure you have all necessary dependencies

配置快速入门应用程序

用户下载并安装快速入门应用程序后,该应用程序将配置为使用 Microsoft Graph。 我们需要修改生成的配置文件,使该文件改为调用 PAT 生命周期管理 API。

提示

在这些文档内,我们可互换使用集合和组织。如果配置变量需要集合名称,请将其替换为组织名称。

为此,我们需要执行一些操作:

  1. PAT 生命周期管理 API 的 ENDPOINT 配置变量更新为
  2. SCOPE配置变量更新为"499b84ac-1321-427f-aa17-267ca6975798/.default",以引用 Azure DevOps 资源及其所有作用域。

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

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

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

注意

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

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

  1. 下载快速入门应用程序、安装其依赖项并测试其在你的环境中运行后,在选择的编辑器中 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
    
  2. 使用应用注册的客户端 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.
    
  3. 将 变量 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'
    
  4. 更改 变量以引用 Azure DevOps API 资源;字符串是 Azure DevOps API 的资源 ID,.default 范围引用该资源 SCOPE“ ID ” 的所有作用域。

    SCOPE = ["499b84ac-1321-427f-aa17-267ca6975798/.default"]
    
  5. 如果应用程序配置为特定租户 (而不是多租户配置) ,请使用 变量的备用值,在 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"
    
  6. 验证最终文件 app_config.py 是否与以下内容匹配,以及CLIENT_ID、租户 ID 和集合 URL。 出于安全原因,请确保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
    
  7. 重新运行应用程序以测试能否获取请求用户的所有 PAT 令牌。 验证你拥有的内容后,可以随意修改 和 目录的内容,以支持将请求发送到 PAT 生命周期管理 'app.py''ms-identity-python-webapp-master\templates' API 终结点的其余部分。 有关已修改以支持所有 PAT 生命周期管理 API 终结点请求的 Python Flask 快速入门应用程序的示例,请参阅 GitHub 上的示例存储库

自动刷新Azure AD令牌

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

探索 PAT 生命周期管理 ’ API

在上述 GitHub 示例应用程序和快速入门应用程序中,应用程序已预先配置为请求提供 Azure AD 令牌。 若要详细了解终结点、它们接受的参数以及响应中返回的内容,请参阅 API 参考文档

常见问题解答

问:为什么需要使用 Azure AD 令牌进行身份验证? 为什么 PAT 不够?

答: 通过这种 PAT 生命周期管理 API,我们已打开了创建新 Pat 并撤消现有 Pat 的功能。 攻击者可能会使用此 API 来创建多个进入组织 ADO 资源的入口点 ’ 。 通过强制实施 Azure AD 身份验证,我们希望使用此功能强大的 API 来应对此未经授权的使用。

问:我是否需要有一个具有有效 Azure 订阅的 Azure AD 租户才能使用此 API?

答:遗憾的是,此 API 仅适用于属于包含有效 Azure 订阅的 Azure AD 租户的用户。

问:我是否可以获得此示例应用程序的示例,以使用其他语言/框架/应用程序类型?

答: 我们想要使用所选语言的 API! 如果你有一个示例请求,请转到我们的开发 Community查看其他人是否有共享的示例。 如果你有一个示例应用程序,该应用程序想要 ’ 分享到更大的 Azure DevOps 受众,请’,我们可以更广泛地了解这些文档的循环使用!

问:此令牌 API 与令牌管理 API 之间有何区别?

答: 与此类似,此 令牌 api令牌管理 api提供不同的用例和受众:

  • 此令牌 API 主要适用于想要管理其在自动管道中拥有的 Pat 的用户。 此 API 允许。 它使你能够创建新令牌并更新现有令牌。
  • 令牌管理员 API 适用于组织管理员。 管理员可以使用此 API 来检索和撤销 OAuth 授权,包括 () Pat 的个人访问令牌,并为其组织中的用户自描述会话令牌。

问:如何通过 API 重新生成/轮换 Pat? 我在 UI 中看到了此选项,但 ’ 在 API 中看不到类似的方法。

答: 很好的问题! “UI 中的 "重新生成" ” 功能实际上可以完成一些操作,这些操作可通过 API 完全复制。

要旋转 PAT,需要:

  1. 使用 GET 调用了解 PAT 的元数据,
  2. 使用 POST 调用创建一个新的 PAT,其中包含旧的 PAT ’ s 元数据’
  3. 使用 DELETE 调用撤销旧 PAT

问:我在尝试使用此应用时看到 "需要管理员批准" 弹出窗口。 如何在没有管理员批准的情况下使用此应用?

答: 你的租户似乎已设置安全策略,这些策略要求你的应用程序被授予访问组织中资源的权限。 目前,在此租户中使用此应用程序的唯一方法是要求管理员向应用程序授予权限,然后才能使用该应用程序。

后续步骤