快速入门：调用受 Microsoft 标识平台保护的 ASP.NET Web API

以下快速入门使用一个代码示例，该示例演示如何通过仅限授权帐户访问 ASP.NET Web API 资源来保护 ASP.NET Web API。 该示例支持对个人 Microsoft 帐户和任何 Microsoft Entra 组织中的帐户进行授权。

本文还使用 Windows Presentation Foundation (WPF) 应用演示如何请求访问令牌来访问 Web API。

先决条件

• 具有活动订阅的 Azure 帐户。 免费创建帐户。
• Visual Studio 2022。 免费下载 Visual Studio。

克隆或下载示例

可以通过两种方式获取代码示例：

• 在 shell 或命令行中进行克隆：

  git clone https://github.com/AzureADQuickStarts/AppModelv2-NativeClient-DotNet.git
  

• 以 ZIP 文件下载。

提示

若要避免由于 Windows 中路径长度限制导致的错误，我们建议将存档提取或克隆到驱动器根目录附近的目录中。

注册 Web API (TodoListService)

提示

本文中的步骤可能因开始使用的门户而略有不同。

在 Azure 门户的“应用注册”中注册 Web API。

1. 至少以云应用程序管理员身份登录到 Microsoft Entra 管理中心。

2. 如果你有权访问多个租户，请使用顶部菜单中的“设置”图标 ，通过“目录 + 订阅”菜单切换到你希望在其中注册应用程序的租户。

3. 浏览至“标识”>“应用程序”>“应用注册”，选择“新建注册”。

4. 输入应用程序的名称（例如 AppModelv2-NativeClient-DotNet-TodoListService）。 应用的用户可能会看到此名称，你稍后可对其进行更改。

5. 在“支持的帐户类型”下，选择“任何组织目录中的帐户” 。

6. 选择“注册”以创建应用程序。

7. 在应用的“概述”页上，找到“应用程序(客户端) ID”值，然后记下该值以供后续使用 。 你将需要使用该值为此项目配置 Visual Studio 配置文件（即 TodoListService\appsettings.json 文件中的 ClientId）。

8. 在“管理”下，选择“公开 API”>“添加范围” 。 通过选择“保存并继续”来接受建议的应用程序 ID URI (api://{clientId})，然后输入以下信息：

   1. 对于“范围名称”，输入 access_as_user。
   2. 对于“谁能同意?”，请确保选择了“管理员和用户”选项 。
   3. 在“管理员同意显示名称”框中，输入 Access TodoListService as a user。
   4. 在“管理员同意说明”框中，输入 Accesses the TodoListService web API as a user。
   5. 在“用户同意显示名称”框中，输入 Access TodoListService as a user。
   6. 在“用户同意说明”框中，输入 Accesses the TodoListService web API as a user。
   7. 对于“状态”，保留“启用” 。

9. 选择“添加范围”。

配置服务项目

配置服务项目以匹配注册的 Web API。

1. 在 Visual Studio 中打开解决方案，然后在“TodoListService”项目的根目录下打开 appsettings.json 文件。

2. 将 Enter_the_Application_Id_here 的值替换为在 ClientID 和 Audience 参数中的“应用注册”门户中注册的应用程序中的客户端 ID（应用程序 ID）值。

将新范围添加到 app.config 文件

若要将新范围添加到 TodoListClient 的 app.config 文件中，请执行以下步骤：

1. 在 TodoListClient 项目根文件夹中，打开 app.config 文件。

2. 将你为 TodoListService 项目注册的应用程序的 ID 粘贴到 TodoListServiceScope 参数中，替换 {Enter the Application ID of your TodoListService from the app registration portal} 字符串。

注意

请确保应用程序 ID 使用以下格式：api://{TodoListService-Application-ID}/access_as_user（其中 {TodoListService-Application-ID} 是表示 TodoListService 应用的应用程序 ID 的 GUID）。

注册 Web 应用 (TodoListClient)

在 Azure 门户的“应用注册”中注册 TodoListClient 应用，然后在 TodoListClient 项目中配置代码。 如果客户端和服务器视为相同的应用程序，则可重复使用在“步骤 2”中注册的同一应用程序。 如果希望用户使用 Microsoft 个人帐户登录，则可使用相同的应用程序。

注册应用

若要注册 TodoListClient 应用，请执行以下步骤：

1. 至少以云应用程序管理员身份登录到 Microsoft Entra 管理中心。

2. 浏览至“标识”>“应用程序”>“应用注册”，选择“新建注册”。

3. 选择“新注册”。

4. “注册应用程序”页出现后，请输入应用程序的注册信息：

   1. 在“名称”部分输入一个会显示给应用用户的有意义的应用程序名称，例如 NativeClient-DotNet-TodoListClient 。
   2. 在“支持的帐户类型”下，选择“任何组织目录中的帐户” 。
   3. 选择“注册”以创建应用程序。

   注意

   在 TodoListClient 项目的 app.config 文件中，将 ida:Tenant 的默认值设置为 common。 可能的值为：

   • common：可以使用工作或学校帐户或 Microsoft 个人帐户登录（因为你在上一步中选择了“任何组织目录中的帐户”）。
   • organizations：可使用工作或学校帐户登录。
   • consumers：只能使用 Microsoft 个人帐户登录。

5. 在应用“概述”页面上，选择“身份验证”，然后完整以下步骤以添加平台 ：

   1. 在“平台配置”下，选择“添加平台”按钮 。
   2. 对于“移动和桌面应用程序”，选择“移动和桌面应用程序” 。
   3. 对于“重定向 URI”，请选择 https://login.microsoftonline.com/common/oauth2/nativeclient 复选框。
   4. 选择“配置” 。

6. 选择“API 权限”，然后完成以下步骤以添加权限：

   1. 选择“添加权限”按钮。
   2. 选择“我的 API”选项卡。
   3. 在 API 列表中，选择 AppModelv2-NativeClient-DotNet-TodoListService API 或选择为 Web API 输入的名称。
   4. 如果“access_as_user”权限复选框未处于选中状态，请将其选中。 如有必要，请使用搜索框。
   5. 选择“添加权限”按钮。

配置项目

通过将应用程序 ID 添加到 app.config 文件来配置 TodoListClient 项目。

1. 在“应用注册门户”的“概述”页中，复制“应用程序(客户端) ID”的值 。

2. 打开位于“TodoListClient”项目根文件夹中的 app.config 文件，然后将应用程序 ID 值粘贴到 ida:ClientId 参数中。

运行项目

启动这两个项目。 对于 Visual Studio 用户：

1. 右键单击 Visual Studio 解决方案，然后选择“属性”

2. 在“常用属性”中选择“启动项目”，然后选择“多个启动项目”。

3. 对于这两个项目，请选择“启动”作为操作

4. 请使用向上箭头将 TodoListService 服务移动到列表中的第一个位置，以确保先启动该服务。

登录以运行 TodoListClient 项目。

1. 按 F5 启动项目。 此时会打开服务页以及桌面应用程序。

2. 在 TodoListClient 中，选择右上角的“登录”，然后使用注册应用程序时所用的同一凭据登录，或以同一目录中的用户身份登录。

   如果你是首次登录，系统可能会提示你同意 TodoListService Web API。

   登录时还需要请求 access_as_user 范围的访问令牌，用于访问 TodoListService Web API 并处理“待办事项”列表 。

为客户端应用程序预先授权

可以允许其他目录中的用户访问 Web API，方法是预先授权客户端应用程序访问 Web API。 为此，可将客户端应用中的应用程序 ID 添加到 Web API 的预授权应用程序列表中。 添加预授权客户端，即表示你允许用户访问你的 Web API，而不必再征求你的同意。

1. 在“应用注册”门户中，打开 TodoListService 应用的属性。
2. 在“公开 API”部分，选择“授权的客户端应用程序”部分下的“添加客户端应用程序” 。
3. 在“客户端 ID”框中，粘贴 TodoListClient 应用的应用程序 ID。
4. 在“授权范围”部分中，为此 api://<Application ID>/access_as_user Web API 选择范围。
5. 选择“添加应用程序”。

运行项目

1. 按 F5 运行项目。 随即会打开 TodoListClient 应用。
2. 选择右上角的“登录”，然后使用 Microsoft 个人帐户（例如 live.com 或 hotmail.com 帐户）或工作或学校帐户登录 。

可选：限制对特定用户的登录访问

默认情况下，任何个人帐户（如 outlook.com 或 live.com 帐户），或者集成了 Microsoft Entra ID 的组织的工作或学校帐户都可以请求令牌并访问你的 Web API。

若要指定谁可以登录你的应用，请更改 appsettings.json 文件中的 TenantId 属性。

帮助和支持

如果需要帮助、需要报告问题，或者需要详细了解支持选项，请参阅面向开发人员的帮助和支持。

后续步骤

在以下教程系列中通过构建受保护的 ASP.NET Core Web API 来了解详细信息：

受保护的 Web API 教程