快速入门:调用受 Microsoft 标识平台保护的 ASP.NET Web API
以下快速入门使用一个代码示例,该示例演示如何通过仅限授权帐户访问 ASP.NET Web API 资源来保护 ASP.NET Web API。 该示例支持对任何 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
提示
若要避免由于 Windows 中路径长度限制导致的错误,我们建议将存档提取或克隆到驱动器根目录附近的目录中。
注册 Web API (TodoListService)
提示
本文中的步骤可能因开始使用的门户而略有不同。
在 Azure 门户的“应用注册”中注册 Web API。
至少以云应用程序管理员身份登录到 Microsoft Entra 管理中心。
如果你有权访问多个租户,请使用顶部菜单中的“设置”图标 ,通过“目录 + 订阅”菜单切换到你希望在其中注册应用程序的租户。
浏览至“标识”>“应用程序”>“应用注册”,选择“新建注册”。
输入应用程序的名称(例如
AppModelv2-NativeClient-DotNet-TodoListService
)。 应用的用户可能会看到此名称,你稍后可对其进行更改。在“支持的帐户类型”下,选择“任何组织目录中的帐户” 。
选择“注册”以创建应用程序。
在应用的“概述”页上,找到“应用程序(客户端) ID”值,然后记下该值以供后续使用 。 你将需要使用该值为此项目配置 Visual Studio 配置文件(即 TodoListService\appsettings.json 文件中的
ClientId
)。在“管理”下,选择“公开 API”>“添加范围” 。 通过选择“保存并继续”来接受建议的应用程序 ID URI (
api://{clientId}
),然后输入以下信息:- 对于“范围名称”,输入
access_as_user
。 - 对于“谁能同意?”,请确保选择了“管理员和用户”选项 。
- 在“管理员同意显示名称”框中,输入
Access TodoListService as a user
。 - 在“管理员同意说明”框中,输入
Accesses the TodoListService web API as a user
。 - 在“用户同意显示名称”框中,输入
Access TodoListService as a user
。 - 在“用户同意说明”框中,输入
Accesses the TodoListService web API as a user
。 - 对于“状态”,保留“启用” 。
- 对于“范围名称”,输入
选择“添加范围”。
配置服务项目
配置服务项目以匹配注册的 Web API。
在 Visual Studio 中打开解决方案,然后在“TodoListService”项目的根目录下打开 appsettings.json 文件。
将
Enter_the_Application_Id_here
的值替换为在ClientID
和Audience
参数中的“应用注册”门户中注册的应用程序中的客户端 ID(应用程序 ID)值。
将新范围添加到 app.config 文件
若要将新范围添加到 TodoListClient 的 app.config 文件中,请执行以下步骤:
在 TodoListClient 项目根文件夹中,打开 app.config 文件。
将你为 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 应用,请执行以下步骤:
至少以云应用程序管理员身份登录到 Microsoft Entra 管理中心。
浏览至“标识”>“应用程序”>“应用注册”,选择“新建注册”。
选择“新注册”。
“注册应用程序”页出现后,请输入应用程序的注册信息:
- 在“名称”部分输入一个会显示给应用用户的有意义的应用程序名称,例如 NativeClient-DotNet-TodoListClient 。
- 在“支持的帐户类型”下,选择“任何组织目录中的帐户” 。
- 选择“注册”以创建应用程序。
注意
在 TodoListClient 项目的 app.config 文件中,将
ida:Tenant
的默认值设置为common
。 可能的值为:organizations
:可使用工作或学校帐户登录。
在应用“概述”页面上,选择“身份验证”,然后完成以下步骤以添加平台 :
- 在“平台配置”下,选择“添加平台”按钮 。
- 对于“移动和桌面应用程序”,选择“移动和桌面应用程序” 。
- 对于“重定向 URI”,请选择
https://login.partner.microsoftonline.cn/common/oauth2/nativeclient
复选框。 - 选择“配置” 。
选择“API 权限”,然后完成以下步骤以添加权限:
- 选择“添加权限”按钮。
- 选择“我的 API”选项卡。
- 在 API 列表中,选择 AppModelv2-NativeClient-DotNet-TodoListService API 或选择为 Web API 输入的名称。
- 如果“access_as_user”权限复选框未处于选中状态,请将其选中。 如有必要,请使用搜索框。
- 选择“添加权限”按钮。
配置项目
通过将应用程序 ID 添加到 app.config 文件来配置 TodoListClient 项目。
在“应用注册门户”的“概述”页中,复制“应用程序(客户端) ID”的值 。
打开位于“TodoListClient”项目根文件夹中的 app.config 文件,然后将应用程序 ID 值粘贴到
ida:ClientId
参数中。
运行项目
启动这两个项目。 对于 Visual Studio 用户:
右键单击 Visual Studio 解决方案,然后选择“属性”
在“常用属性”中选择“启动项目”,然后选择“多个启动项目”。
对于这两个项目,请选择“启动”作为操作
请使用向上箭头将 TodoListService 服务移动到列表中的第一个位置,以确保先启动该服务。
登录以运行 TodoListClient 项目。
按 F5 启动项目。 此时会打开服务页以及桌面应用程序。
在 TodoListClient 中,选择右上角的“登录”,然后使用注册应用程序时所用的同一凭据登录,或以同一目录中的用户身份登录。
如果你是首次登录,系统可能会提示你同意 TodoListService Web API。
登录时还需要请求 access_as_user 范围的访问令牌,用于访问 TodoListService Web API 并处理“待办事项”列表 。
为客户端应用程序预先授权
可以允许其他目录中的用户访问 Web API,方法是预先授权客户端应用程序访问 Web API。 为此,可将客户端应用中的应用程序 ID 添加到 Web API 的预授权应用程序列表中。 添加预授权客户端,即表示你允许用户访问你的 Web API,而不必再征求你的同意。
- 在“应用注册”门户中,打开 TodoListService 应用的属性。
- 在“公开 API”部分,选择“授权的客户端应用程序”部分下的“添加客户端应用程序” 。
- 在“客户端 ID”框中,粘贴 TodoListClient 应用的应用程序 ID。
- 在“授权范围”部分中,为此
api://<Application ID>/access_as_user
Web API 选择范围。 - 选择“添加应用程序”。
运行项目
- 按 F5 运行项目。 随即会打开 TodoListClient 应用。
- 在右上方选择“登录”,然后使用工作或学校帐户登录。
可选:限制对特定用户的登录访问
默认情况下,任何集成了 Microsoft Entra ID 的组织的工作或学校帐户都可以请求令牌并访问你的 Web API。
若要指定谁可以登录你的应用,请更改 appsettings.json 文件中的 TenantId
属性。
帮助和支持
如果需要帮助、需要报告问题,或者需要详细了解支持选项,请参阅面向开发人员的帮助和支持。
后续步骤
在以下教程系列中通过构建受保护的 ASP.NET Core Web API 来了解详细信息: