Compartir a través de

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

  • Artículo

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

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

先决条件

克隆或下载示例

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

  • 在 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”中注册的同一应用程序。

注册应用

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

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

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

  3. 选择“新注册”。

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

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

    注意

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

    • organizations：可使用工作或学校帐户登录。

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

    1. 在“平台配置”下，选择“添加平台”按钮 。
    2. 对于“移动和桌面应用程序”，选择“移动和桌面应用程序” 。
    3. 对于“重定向 URI”，请选择 https://login.partner.microsoftonline.cn/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 Entra ID 的组织的工作或学校帐户都可以请求令牌并访问你的 Web API。

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

帮助和支持

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

后续步骤

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

受保护的 Web API 教程