使用 Insomnia 调用 ASP.NET Core Web API

项目
2024/06/17

本文介绍如何使用 Insomnia 调用受保护的 ASP.NET 核心 Web API。 Insomnia 是一个应用程序，可让你将 HTTP 请求发送到 Web API 以测试其授权和访问控制（身份验证）策略。在本文中，你将在租户中注册 Web 应用和 Web API。 Web 应用用于获取 Microsoft 标识平台生成的访问令牌。接下来，使用令牌通过 Insomnia 对 Web API 进行授权调用。

本文介绍如何使用 Insomnia 调用受保护的 ASP.NET 核心 Web API。 Insomnia 是一个应用程序，可让你将 HTTP 请求发送到 Web API 以测试其授权和访问控制（身份验证）策略。按照教程：在 API 中实现受保护的终结点（在该教程中创建了受保护的 API）中的操作，需要向 Microsoft 标识平台注册 Web 应用程序来生成访问令牌。接下来，使用令牌通过 Insomnia 对 API 进行授权调用。

先决条件

具有活动订阅的 Azure 帐户。创建帐户。
Azure 帐户必须拥有管理应用程序的权限。以下任何 Microsoft Entra 角色都包括所需的权限：
- 应用程序管理员
- 应用程序开发人员
- 云应用程序管理员
下载并安装 Insomnia。使用 Insomnia 获取 API 请求的访问令牌。
最低要求 .NET 8.0 SDK。

一个 Azure 帐户和一个有效的订阅。创建帐户。
Azure 帐户必须拥有管理应用程序的权限。以下任何 Microsoft Entra 角色都包括所需的权限：
- 应用程序管理员
- 应用程序开发人员
- 云应用程序管理员
完成系列教程：
下载并安装 Insomnia。

注册应用程序

Microsoft 标识平台要求应用程序在注册后才能使用标识和访问管理服务。通过应用程序注册，可以指定应用程序的名称和类型以及登录受众。登录受众指定允许哪些类型的用户帐户登录给定应用程序。

注册 Web API

提示

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

请按照以下步骤创建 Web API 注册：

至少以应用程序开发人员的身份登录到 Microsoft Entra 管理中心。
如果你有权访问多个租户，请使用顶部菜单中的“设置”图标，通过“目录 + 订阅”菜单切换到你希望在其中注册应用程序的租户。
浏览到“标识”>“应用程序”>“应用注册”。
选择“新注册”。
为应用程序输入名称，例如 NewWebAPI1。
对于“支持的帐户类型”设置，请选择“仅限此组织目录中的帐户”。要了解不同帐户类型的信息，选择“帮我选择”选项。
选择“注册”。
注册完成后，可以看到应用程序的“概述”窗格。记录要用于后续步骤的目录（租户）ID 和应用程序（客户端）ID。

备注

可以通过参照修改应用程序支持的帐户来更改支持的帐户类型。

公开 API

在“管理”下，选择“公开 API”>“添加范围”。通过选择“保存并继续”来接受建议的应用程序 ID URI (api://{clientId})。 {clientId} 是从“概述”页面记录的值。然后输入以下信息：
1. 对于“范围名称”，输入 Forecast.Read。
2. 对于“谁能同意?”，请确保选择了“管理员和用户”选项。
3. 在“管理员同意显示名称”框中，输入 Read forecast data。
4. 在“管理员同意说明”框中，输入 Allows the application to read weather forecast data。
5. 在“用户同意显示名称”框中，输入 Read forecast data。
6. 在“用户同意说明”框中，输入 Allows the application to read weather forecast data。
7. 确保将“状态”设置为“已启用”。
选择“添加作用域”。如果作用域已正确输入，则会显示在“公开 API”窗格中。

注册 Web 应用

拥有 Web API 是不够的，还需要一个 Web 应用来获取访问令牌来访问 Web API。

请按照以下步骤创建 Web 应用注册：

选择“主页”以返回到主页。浏览到“标识”>“应用程序”>“应用注册”。
选择“新注册”。
输入应用程序的名称，例如 web-app-calls-web-api。
对于“支持的帐户类型”设置，请选择“仅限此组织目录中的帐户”。要了解不同帐户类型的信息，选择“帮我选择”选项。
在“重定向 URI（可选）”下选择“Web”，然后在“URL”文本框中输入 http://localhost。
选择“注册”。

至少以应用程序开发人员的身份登录到 Microsoft Entra 管理中心。
如果你有权访问多个租户，请使用顶部菜单中的“设置”图标，通过“目录 + 订阅”菜单切换到你希望在其中注册应用程序的租户。
浏览到“标识”>“应用程序”>“应用注册”。
选择“新注册”。
输入应用程序的名称，例如 web-app-calls-web-api。
对于“支持的帐户类型”设置，请选择“仅限此组织目录中的帐户”。要了解不同帐户类型的信息，选择“帮我选择”选项。
在“重定向 URI（可选）”下选择“Web”，然后在“URL”文本框中输入 http://localhost。
选择注册。

注册完成后，可以看到应用程序的“概述”窗格。记录要用于后续步骤的目录（租户）ID 和应用程序（客户端）ID。

添加客户端密码

客户端密码是一个字符串值，应用可以使用该值来标识自身，客户端密码有时也称为应用程序密码。 Web 应用在请求令牌时会使用客户端密码来证明其身份。

按照以下步骤配置客户端密码：

在“概述”窗格的“管理”下，选择“证书和机密”>“客户端机密”>“新建客户端机密”。
为客户端密码添加说明，例如“我的客户端密码”。
选择机密的过期时间，或指定自定义的生存期。
- 客户端密码的生存期限制为两年（24 个月）或更短。不能指定超过 24 个月的自定义生存期。
- Microsoft 建议将过期时间值设置为小于 12 个月。
选择添加。
请务必记录客户端密码的值。退出此页面后，此机密值永不再显示。

有关如何安全地存储客户端机密的详细信息，请参阅 Key Vault 中机密管理的最佳做法。

添加用于访问 Web API 的权限

通过指定 Web API 的范围，Web 应用可获得由 Microsoft 标识平台提供的包含这些范围的访问令牌。然后在代码中，Web API 可基于访问令牌中找到的范围提供对其资源的基于权限的访问。

按照以下步骤配置客户端对 Web API 的权限：

在应用程序的“概述”窗格中，在“管理”下，选择“API 权限”>“添加权限”>“我的组织使用的 API”。
选择“NewWebAPI1”或要向其添加权限的 API。
在“选择权限”下，选中“Forecast.Read”旁边的框。可能需要展开“权限”列表。这会代表已登录用户选择客户端应用应具有的权限。
选择“添加权限”以完成此过程。

将这些权限添加到 API 后，应会在“配置的权限”下看到所选权限。

你可能还会注意到 Microsoft Graph API 的 User.Read 权限。注册应用时，会自动添加此权限。

测试 Web API

若要确保 API 正常运行并准备好处理请求，请执行以下步骤：

克隆 ms-identity-docs-code-dotnet 存储库。

git clone https://github.com/Azure-Samples/ms-identity-docs-code-dotnet.git

导航到 ms-identity-docs-code-dotnet/web-api 并打开 appsettings.json，将 {APPLICATION_CLIENT_ID} 和 {DIRECTORY_TENANT_ID} 替换为以下值：
- {APPLICATION_CLIENT_ID} 是应用的“概述”窗格中的 Web API“应用程序(客户端) ID”。
- {DIRECTORY_TENANT_ID} 是应用“概述”窗格上的 Web API“目录(租户) ID”。
执行以下命令以启动应用：
```
dotnet run
```

将显示类似于以下的输出。记录 https://localhost:{port} URL 中的端口号。

...
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: https://localhost:{port}
...

测试 Web API

若要确保 API 正常运行并准备好处理请求，请执行以下步骤：

导航到在教程：创建 ASP.NET Core 项目并配置 API 中创建的 Web API（例如 NewWebAPILocal），然后打开文件夹。
打开新的终端窗口，并导航到 Web API 项目所在的文件夹。
- .NET 6.0
- .NET 7.0
1. 执行以下命令以启动应用：
```
dotnet run
```
1. 打开新终端并执行以下命令，在 https 配置文件上启动应用：
```
dotnet run -launch-profile https`
```

将显示类似于以下的输出。记录 https://localhost:{port} URL 中的端口号。

...
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: https://localhost:{port}
...

在 Insomnia 中配置 Web API 的授权请求

若要获取 API 请求的访问令牌，请执行以下步骤：

启动 Insomnia 应用程序。
选择“新的 HTTP 请求”，也可以使用 ctrl + N 创建新的 HTTP 请求。
在“新建请求模式”中，从下拉列表中选择“GET”方法。
对于请求 URL，输入 Web API 公开的终结点的 URL https://localhost:{port}/weatherforecast。
从“身份验证”下拉菜单中选择“OAuth 2.0”。这将显示 OAuth 2.0 窗体。

在 OAuth 2.0 窗体中输入以下值：

设置	“值”
授权类型	选择“授权代码”
授权 URL	`https://login.partner.microsoftonline.cn/{tenantId}/oauth2/v2.0/authorize` 将 `{tenantId}` 替换为目录（租户）ID
访问令牌 URL	`https://login.partner.microsoftonline.cn/{tenantId}/oauth2/v2.0/token` 将 `{tenantId}` 替换为目录（租户）ID
客户端 ID	Web 应用注册的应用程序（客户端）ID 值
客户端密码	Web 应用注册的客户端密码值
重定向 URL	输入 `http://localhost`，它将重定向 URL 设置为注册到 Microsoft Entra ID 的重定向 URI。
高级选项>范围	`api://{application_client_id}/Forecast.Read` 导航到 Web 应用注册，在“管理”下，选择“API 权限”，然后选择“Forecast.Read” 复制文本框中的值，其中包含“范围”值

获取访问令牌并将请求发送到 Web API

输入这些值后，选择窗体末尾的“提取令牌”。这会启动一个 Insomnia 浏览器窗口，可在其中使用用户凭据进行身份验证。请务必在浏览器中允许来自 Insomnia 应用程序的弹出窗口。
进行身份验证后，选择“发送”以将请求发送到受保护的 Web API 终结点。

如果请求中包含有效的访问令牌，预期的响应将为 200 正常，输出类似于：

[
  {
    "date": "YYYY-MM-DDTHH:MM:SS",
    "temperatureC": -16,
    "summary": "Scorching",
    "temperatureF": 4
  },
  {
    "date": "YYYY-MM-DDTHH:MM:SS",
    "temperatureC": 1,
    "summary": "Sweltering",
    "temperatureF": 33
  },
  {
    "date": "YYYY-MM-DDTHH:MM:SS",
    "temperatureC": 26,
    "summary": "Freezing",
    "temperatureF": 78
  },
  {
    "date": "YYYY-MM-DDTHH:MM:SS",
    "temperatureC": 54,
    "summary": "Mild",
    "temperatureF": 129
  },
  {
    "date": "YYYY-MM-DDTHH:MM:SS",
    "temperatureC": 11,
    "summary": "Bracing",
    "temperatureF": 51
  }
]

有关 OAuth 2.0 授权代码流和应用程序类型的详细信息，请参阅：

通过

使用 Insomnia 调用 ASP.NET Core Web API

先决条件

注册应用程序

注册 Web API

公开 API

注册 Web 应用

添加客户端密码

添加用于访问 Web API 的权限

测试 Web API

测试 Web API

在 Insomnia 中配置 Web API 的授权请求

获取访问令牌并将请求发送到 Web API

相关内容

其他资源