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

以下快速入门使用一个代码示例,该示例演示如何通过仅限授权帐户访问 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 的值替换为在 ClientIDAudience 参数中的“应用注册”门户中注册的应用程序中的客户端 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 来了解详细信息: