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

2025/05/07

在本快速入门中，你将使用示例 Web 应用来演示如何使用Microsoft标识平台保护 ASP.NET Web API。此示例使用 Microsoft身份验证库（MSAL）来处理身份验证和授权。

先决条件

拥有有效订阅的 Azure 帐户。创建账户。
在 Microsoft Entra 管理中心注册新应用，并从“应用概述 ”页记录其标识符。要了解更多信息，请参见注册应用程序。
- 名称： NewWebAPI1
- 支持的帐户类型： 仅限于此组织目录中的帐户（单一租户）

ASP.NET
ASP.NET Core

Visual Studio Code

公开 API

注册 API 后，可以通过定义 API 向客户端应用程序公开的范围来配置其权限。客户端应用程序通过将访问令牌及其请求传递到受保护的 Web API 来请求执行操作的权限。然后，仅当 Web API 接收的访问令牌包含所需范围时，Web API 才会执行请求的操作。

ASP.NET
ASP.NET Core

在管理下，选择公开 API>添加范围。通过选择“保存并继续”来接受建议的应用程序 ID URI (api://{clientId})，然后输入以下信息：
1. 对于范围名称，请输入access_as_user。
2. 对于“谁能同意?”，请确保选择了“管理员和用户”选项。
3. 在“管理员同意显示名称”框中，输入 Access TodoListService as a user。
4. 在“管理员同意说明”框中，输入。
5. 在“用户同意显示名称”框中，输入 Access TodoListService as a user。
6. 在“用户同意说明”框中，输入 Accesses the TodoListService web API as a user。
7. 对于“状态”，保留“启用”。
选择添加作用域。

添加委托的权限（范围）

API 需要发布至少一个范围（也称为委派权限），客户端应用才能成功获取用户的访问令牌。若要发布范围，请执行以下步骤：

从“应用注册”页中，选择创建的 API 应用程序 (ciam-ToDoList-api) 以打开其“概述”页。
在“管理”下，选择“公开 API” 。
在页面顶部的“应用程序 ID URI”旁边，选择“添加”链接以生成对此应用来说独一无二的 URI。
接受建议的应用程序 ID URI，例如 api://{clientId}，然后选择“保存”。当您的 Web 应用在请求 Web API 的访问令牌时，会将该 URI 添加为 API 每个定义范围的前缀。
在“此 API 定义的范围”下选择“添加范围”。

输入以下值，用于定义对 API 的读取访问权限，然后选择添加范围以保存更改：

资产	价值
范围名称	ToDoList.Read
谁可以许可	仅管理员
管理员同意显示名称	使用“ToDoListApi”读取用户待办事项列表
管理员同意说明	允许应用使用“TodoListApi”读取用户的待办事项列表。
国家	已启用

再次选择添加范围，然后输入定义对 API 的读取和写入访问权限范围的以下值。选择 “添加范围 ”以保存更改：

资产	价值
范围名称	ToDoList.ReadWrite
谁可以许可	仅管理员
管理员同意显示名称	使用“ToDoListApi”读取和写入用户 ToDo 列表
管理员同意说明	允许应用使用“ToDoListApi”读取和写入用户的 ToDo 列表
国家	已启用

详细了解 Web API 的发布权限时的最小特权原则。

添加应用程序权限（应用角色）

API 需要为应用程序发布至少一个应用角色（也称为应用程序权限），客户端应用才能自行获取访问令牌。应用程序权限是 API 想要使客户端应用程序能够成功地以自己的身份进行身份验证（无需让用户登录）时应发布的权限类型。若要发布应用程序权限，请执行下列步骤：

从“应用注册”页中，选择创建的应用程序（例如 ciam-ToDoList-api）以打开其“概述”页。
在“管理”下，选择“应用角色”。

选择“创建应用角色”，输入以下值，然后选择“应用”以保存更改：

资产	价值
显示名称	ToDoList.Read.All
允许的成员类型	应用程序
价值	ToDoList.Read.All
DESCRIPTION	允许应用使用“TodoListApi”读写每个用户的待办事项列表
要启用此应用角色吗？	保持选中状态

再次选择“创建应用角色”，为第二个应用角色输入以下值，然后选择“应用”以保存更改：

资产	价值
显示名称	ToDoList.ReadWrite.All
允许的成员类型	应用程序
价值	ToDoList.ReadWrite.All
DESCRIPTION	允许应用使用“ToDoListApi”读写每个用户的 ToDo 列表
要启用此应用角色吗？	保持选中状态

克隆或下载示例应用程序

若要获取示例应用程序，可以从 GitHub 克隆它或将其下载为 .zip 文件。

ASP.NET
ASP.NET Core

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

以 ZIP 文件下载。

提示

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

git clone https://github.com/Azure-Samples/ms-identity-ciam-dotnet-tutorial.git

下载 .zip 文件。将其解压缩到名称长度少于 260 个字符的文件路径。

配置示例应用程序

配置代码示例以匹配已注册的 Web API。

ASP.NET
ASP.NET Core

在 Visual Studio 中打开解决方案，然后在 TodoListService 项目的根目录下打开 appsettings.json 文件。
将 Enter_the_Application_Id_here 的值替换为在“应用注册”门户中的和 ClientID 参数中注册的应用程序中的客户端 ID（应用程序 ID）值Audience。

将新范围添加到 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）

在 Microsoft Entra 管理中心 的应用注册 中注册 TodoListClient 应用，然后在 TodoListClient 项目中配置代码。如果客户端和服务器被视为同一应用程序，则可以重复使用在步骤 2 中注册的应用程序。

注册应用

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

至少以云应用程序管理员身份登录到 Microsoft Entra 管理中心。
浏览至“标识”>“应用程序”>“应用注册”，选择“新建注册”。
选择“新注册”。
“注册应用程序”页出现后，请输入应用程序的注册信息：
1. 在名称部分中，输入一个有意义的应用程序名称，该名称将显示给应用的用户（例如，NativeClient-DotNet-TodoListClient）。
2. 在“支持的帐户类型”下，选择“任何组织目录中的帐户” 。
3. 选择“注册”以创建应用程序。
备注

在 TodoListClient 项目 app.config 文件中，ida:Tenant 的默认值设置为 common。可能的值为：
- common：可使用工作或学校帐户登录。
- organizations：可使用工作或学校帐户登录。
在应用概述页上，选择 身份验证，然后完成以下步骤以添加平台：
1. 在“平台配置”下，选择“添加平台”按钮。
2. 对于 移动和桌面应用程序，请选择 移动和桌面应用程序。
3. 对于“重定向 URI”，请选择复选框https://login.partner.microsoftonline.cn/common/oauth2/nativeclient。
4. 选择配置。
选择“API 权限”，然后完成以下步骤以添加权限：
1. 选择“添加权限”按钮。
2. 选择“我的 API”选项卡。
3. 在 API 列表中，选择 AppModelv2-NativeClient-DotNet-TodoListService API 或选择您为 Web API 输入的名称。
4. 如果“access_as_user”权限复选框未选中，请选中它。如有必要，请使用“搜索”框。
5. 选择“添加权限”按钮。

配置你的项目

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

在“应用注册门户”的“概述”页中，复制“应用程序(客户端) ID”的值。
从 TodoListClient 项目根文件夹打开 app.config 文件，然后将应用程序 ID 值粘贴到 ida:ClientId 参数中。

在 IDE 中，打开包含示例的项目文件夹 ms-identity-ciam-dotnet-tutorial/2-Authorization/3-call-own-api-dotnet-core-daemon/ToDoListAPI。
打开 appsettings.json 文件，其中包含以下代码片段：
```
{
  "AzureAd": {
    "Instance": "Enter_the_Authority_URL_Here", 
    "TenantId": "Enter_the_Tenant_Id_Here",
    "ClientId": "Enter_the_Application_Id_Here",
    "Scopes": {
      "Read": ["ToDoList.Read", "ToDoList.ReadWrite"],
      "Write": ["ToDoList.ReadWrite"]
    },
    "AppPermissions": {
      "Read": ["ToDoList.Read.All", "ToDoList.ReadWrite.All"],
      "Write": ["ToDoList.ReadWrite.All"]
    }
  },
  "Logging": {...},
  "AllowedHosts": "*"
}
```
查找以下值：
- ClientId - 应用程序的标识符，也称为客户端。将引号中的 value 文本替换为先前从注册应用程序的“概述”页中记录的应用程序（客户端）ID。
- TenantId - 应用程序注册所在租户的标识符。将引号中的 value 文本替换为注册应用程序“概述页”中先前记录的 目录（租户）ID 值。
- Instance - 它指定Microsoft身份验证库（MSAL）可从中请求令牌的目录。根据您的情况，将 Enter_the_Authority_URL_Here 替换为以下任一值：
  - 对于员工租户，请使用 https://login.partner.microsoftonline.cn/ 作为实例。

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

右键单击 Visual Studio 解决方案，然后选择“属性”
在 “通用属性”中，选择“ 启动项目 ”，然后选择 “多个启动项目”。
对于这两个项目，请选择“启动”作为操作
请使用向上箭头将 TodoListService 服务移动到列表中的第一个位置，以确保先启动该服务。

登录以运行 TodoListClient 项目。

按 F5 启动项目。服务页面和桌面应用程序同时打开。
在 TodoListClient 中，选择右上角的“登录”，然后使用注册应用程序时所用的同一凭据登录，或以同一目录中的用户身份登录。

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

为了帮助你访问 TodoListService Web API 并操作 待办事项 列表，登录还请求访问 access_as_user 作用域的访问令牌。

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

可以允许其他目录中的用户访问 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。

若要通过更改 TenantId 文件中属性来指定谁可以登录到应用程序。

从 Web API 项目目录的根目录运行以下命令以启动应用：
```
dotnet run
```

如果一切正常，终端将显示如下所示的输出：

 Building...
     info: Microsoft.Hosting.Lifetime[14]
           Now listening on: https://localhost:{port}
     info: Microsoft.Hosting.Lifetime[0]
           Application started. Press Ctrl+C to shut down.
     info: Microsoft.Hosting.Lifetime[0]
           Hosting environment: Development
...

记录 https://localhost:{port} URL 中的端口号。

若要验证终结点是否受保护，请更新下面的 cURL 命令中的基 URL 以匹配在上一步中收到的终结点，然后运行该命令：
```
curl -k -X GET https://localhost:<your-api-port>/api/todolist -w "%{http_code}\n"
```
预期响应为 401 未授权。

后续步骤

了解如何使用Microsoft标识平台保护 ASP.NET Core Web API。

教程：使用 Microsoft 标识平台生成和保护 ASP.NET Core Web API

通过