使用 Azure DevOps OAuth 2.0

Azure DevOps Services

本文介绍 Azure DevOps OAuth 2.0 如何适用于现有应用程序，并提供维护和迁移应用的指南。

概述

Azure DevOps OAuth 2.0 允许应用程序代表用户访问 Azure DevOps 资源。 虽然此服务已弃用，但现有应用程序将继续运行到 2026 年。

迁移建议：开始规划迁移到 Microsoft Entra ID OAuth ，以确保持续服务和访问增强的安全功能。

先决条件

在使用 Azure DevOps OAuth 应用程序之前：

使用现有的 Azure DevOps OAuth 应用

1.管理现有应用注册

对于现有应用程序，可以查看和管理应用设置：

1. 转到 Visual Studio 个人资料 以访问应用程序注册。

2. 查看 配置的作用域 并确保它们符合应用程序的需求。

3. 验证您的回调URL配置，并在必要时进行更新。

   

4. 请规划您的迁移时间线，以在 2026 年弃用截止日期之前，迁移到 Microsoft Entra ID OAuth。

2.授权您的应用

对于现有的 Azure DevOps OAuth 应用，授权流保持不变：

1. 使用应用参数将用户定向到授权 URL：

   https://app.vssps.visualstudio.com/oauth2/authorize
           ?client_id={app ID}
           &response_type=Assertion
           &state={state}
           &scope={scope}
           &redirect_uri={callback URL}
   

   参数	类型	DESCRIPTION
   client_id	GUID	注册应用时分配给应用的 ID
   response_type	字符串	必须是 Assertion
   state	字符串	生成的字符串值，用于将回叫与其授权请求相关联
   scope	字符串	应用注册的以空格分隔的权限范围 查看 可用范围
   redirect_uri	URL	应用的回叫 URL 地址。 必须与注册到应用的 URL 完全匹配

   示例授权 URL：

   https://app.vssps.visualstudio.com/oauth2/authorize
           ?client_id=00001111-aaaa-2222-bbbb-3333cccc4444
           &response_type=Assertion
           &state=User1
           &scope=vso.work%20vso.code_write
           &redirect_uri=https://fabrikam.azurewebsites.net/myapp/oauth-callback
   

   用户授权后，Azure DevOps 会使用授权代码重定向到回调 URL：

   https://fabrikam.azurewebsites.net/myapp/oauth-callback
           ?code={authorization code}
           &state=User1
   

3. 访问令牌的 Exchange 授权代码

使用授权代码请求访问令牌和刷新令牌：

请求详细信息

网址

POST https://app.vssps.visualstudio.com/oauth2/token

标题

Content-Type: application/x-www-form-urlencoded

请求正文

client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&client_assertion={0}&grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion={1}&redirect_uri={2}

参数替换：

• {0}：应用注册中 URL 编码的客户端密钥
• {1}：来自回调的经过URL编码的授权代码
• {2}：应用注册的回叫 URL

C# 实现示例

public string GenerateRequestPostData(string appSecret, string authCode, string callbackUrl)
{
   return String.Format("client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&client_assertion={0}&grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion={1}&redirect_uri={2}",
               HttpUtility.UrlEncode(appSecret),
               HttpUtility.UrlEncode(authCode),
               callbackUrl
        );
}

响应

{
    "access_token": "{ access token for the user }",
    "token_type": "{ type of token }",
    "expires_in": "{ time in seconds that the token remains valid }",
    "refresh_token": "{ refresh token to use to acquire a new access token }"
}

4.使用访问令牌

将访问令牌作为持有者令牌包含在 API 请求中：

授权标头格式：

Authorization: Bearer {access_token}

示例 API 请求：

GET https://dev.azure.com/myaccount/myproject/_apis/build-release/builds?api-version=3.0
Authorization: Bearer {access_token}

5.刷新过期的访问令牌

访问令牌过期时，使用刷新令牌获取新的访问令牌：

请求：

POST https://app.vssps.visualstudio.com/oauth2/token
Content-Type: application/x-www-form-urlencoded
Content-Length: 1654

client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&client_assertion={0}&grant_type=refresh_token&assertion={1}&redirect_uri={2}

参数替换：

• {0}：URL 编码的客户端密码
• {1}：URL 编码的刷新令牌
• {2}：应用注册的回叫 URL

响应：

{
    "access_token": "{ new access token }",
    "token_type": "{ type of token }",
    "expires_in": "{ time in seconds that the token remains valid }",
    "refresh_token": "{ new refresh token }"
}

代码示例

可以在 Azure DevOps 身份验证示例存储库中找到工作示例。

管理应用机密

Azure DevOps OAuth 应用支持双重机密，以实现零停机轮换：

轮换机密

1. 在 Visual Studio 配置文件中或通过注册机密 API生成新机密。

   

2. 在弹出对话框中确认该操作。

   

3. 更新应用程序 以在旧机密过期之前使用新机密。

4. 在旧机密过期之前彻底测试新机密。

5. 当新机密即将过期时重复此过程。

紧急机密吊销

如果机密遭到入侵：

1. 立即重新生成 个人资料中的密钥。
2. 使用新机密更新应用程序。
3. 监视应用程序日志中未经授权的访问。

删除应用

删除 Azure DevOps OAuth 应用：

1. 转到 Visual Studio 配置文件。

2. 从下拉菜单中选择正确的租户。

3. 在 “应用程序和服务”下查找应用。

4. 在应用程序注册页上选择 “删除 ”。

   

5. 在模式对话框中确认删除操作。

删除后，应用及其所有令牌将立即停止工作。

迁移规划

迁移核对清单

• [ ] 查看 Microsoft Entra ID OAuth 文档
• [ ] 在组织中使用 Azure DevOps OAuth 标识所有应用
• [ ] 规划迁移时间线 ，允许足够的测试时间
• [ ] 更新应用程序体系结构 以支持 Microsoft Entra ID OAuth
• [ ] 在非生产环境中测试迁移
• [ ] 向用户和利益干系人传达更改
• [ ] 在 2026 年截止时间之前完成迁移

迁移优点

增强的安全功能：

• 多重身份验证支持
• 条件访问策略
• 高级威胁防护
• 企业标识集成

更好的开发人员体验：

• 新式身份验证库 （MSAL）
• 跨Microsoft服务的一致标识平台
• 更好的令牌管理和缓存

长期支持：

• 持续投资和特征开发
• 企业合规性和治理功能

常见问题

问：是否仍可创建新的 Azure DevOps OAuth 应用？

答：否。 新应用注册已于 2025 年 4 月停止。 对新应用程序使用 Microsoft Entra ID OAuth 。

问：我的现有 Azure DevOps OAuth 应用何时停止工作？

答：在 2026 年完全弃用 Azure DevOps OAuth 之前，现有应用将继续正常运行。 在此截止时间之前规划迁移。

问：是否可以将 OAuth 与移动应用程序配合使用？

答：Azure DevOps OAuth 仅支持 Web 服务器流，并且需要安全存储客户端机密，使其不适用于移动应用。 Microsoft Entra ID OAuth 提供更好的移动应用支持。

问：如果在请求令牌时收到 HTTP 400 错误，该怎么办？

答：常见原因包括：

• 标头不正确 Content-Type （应为 application/x-www-form-urlencoded）
• 格式不正确的请求正文参数
• 无效或过期的授权代码
• 回叫 URL 不匹配

问：为什么我在使用 OAuth 令牌时会收到 HTTP 401 错误，而使用 PAT 时却不会？

答：检查组织管理员是否 通过 OAuth 禁用了第三方应用程序访问 ， https://dev.azure.com/{your-org-name}/_settings/organizationPolicy

禁用后，OAuth 授权流会正常工作，但 API 调用返回 TF400813: The user "<GUID>" is not authorized to access this resource.

问：是否可以使用 localhost 进行测试？

答：是的。 Azure DevOps OAuth 支持用于本地开发和测试的 https://localhost 回调 URL。

问：如何处理授权拒绝和撤销？

A：为以下内容实现适当的错误处理：

• 授权拒绝：回调中未返回任何授权代码
• 撤销的授权：API 调用返回 401 错误;从用户重新请求授权

问：Azure DevOps OAuth 与 Microsoft Entra ID OAuth 有何区别？

A:

• Azure DevOps OAuth：已弃用、特定于 Azure DevOps 的有限安全功能
• Microsoft Entra ID OAuth：新式、企业级、增强的安全性、长期支持

后续步骤

对于现有应用程序：

对于新应用程序：

相关内容

• 选择身份验证方法
• 迁移到 Microsoft Entra ID OAuth
• 查看 Azure DevOps 的 OAuth 2.0 范围
• 管理应用授权
• 探索 Azure DevOps REST API 参考文档
• 了解 Azure DevOps 中的安全性和标识