使用 cURL 调用 ASP.NET Core Web API

项目
04/24/2024

本文介绍如何使用客户端 URL (cURL) 调用受保护的 ASP.NET Core Web API。 cURL 是开发人员用来向服务器和从服务器传输数据的命令行工具。在本文中，你将在租户中注册 Web 应用和 Web API。 Web 应用用于获取 Microsoft 标识平台生成的访问令牌。接下来，你将使用该令牌通过 cURL 对 Web API 进行授权调用。

本文介绍如何使用客户端 URL (cURL) 调用受保护的 ASP.NET Core Web API。 cURL 是开发人员用来向服务器和从服务器传输数据的命令行工具。按照教程：在 API 中实现受保护的终结点（在该教程中创建了受保护的 API）中的操作，需要向 Microsoft 标识平台注册 Web 应用程序来生成访问令牌。接下来，你将使用该令牌通过 cURL 对 API 进行授权调用。

先决条件

具有活动订阅的 Azure 帐户。免费创建帐户。
Azure 帐户必须拥有管理应用程序的权限。以下任何 Microsoft Entra 角色都包括所需的权限：
- 应用程序管理员
- 应用程序开发人员
- 云应用程序管理员
在工作站计算机上下载并安装 cURL。
最低要求 .NET 8.0 SDK。

具有活动订阅的 Azure 帐户。免费创建帐户。
Azure 帐户必须拥有管理应用程序的权限。以下任何 Microsoft Entra 角色都包括所需的权限：
- 应用程序管理员
- 应用程序开发人员
- 云应用程序管理员
完成系列教程：
在工作站计算机上下载并安装 cURL。

将应用程序注册到 Microsoft 标识平台

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 个月。
选择“添加”。
请务必记录客户端密码的值。退出此页面后，此机密值永不再显示。

添加应用程序权限以允许访问 Web API

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

按照以下步骤配置 Web 应用对 Web API 的权限：

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

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

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

测试 Web 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”。
执行以下命令以启动应用：
- .NET 6.0
- .NET 7.0
```
dotnet run
```
```
dotnet run --launch-profile https
```

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

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

测试 Web API

导航到在教程：创建 ASP.NET Core 项目并配置 API 中创建的 Web API（例如 NewWebAPILocal），然后打开文件夹。
打开新的终端窗口，并导航到 Web API 项目所在的文件夹。

.NET 6.0
.NET 7.0

执行以下命令以启动应用：
```
dotnet run
```

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

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

请求授权代码

授权代码流始于客户端将用户定向到 /authorize 终结点。在此请求中，客户端会向用户请求 Forecast.Read 权限。

https://login.microsoftonline.com/{tenant_id}/oauth2/v2.0/authorize?client_id={web-app-calls-web-api_application_client_id}&response_type=code&redirect_uri=http://localhost&response_mode=query&scope=api://{web_API_application_client_id}/Forecast.Read

复制 URL，替换以下参数并将其粘贴到浏览器中：
- {tenant_id} 是 Web 应用目录（租户）ID。
- {web-app-calls-web-api_application_client_id} 是 Web 应用 (web-app-calls-web-api)“概述”窗格上的“应用程序（客户端）ID”。
- {web_API_application_client_id} 是 Web API (NewWebAPI1)“概述”窗格上的“应用程序（客户端）ID”。
以注册应用的 Microsoft Entra 租户中的用户身份登录。如有必要，可同意任何访问请求。
浏览器将会重定向到 http://localhost/。请参阅浏览器的导航栏，并复制 {authorization_code} 以在以下步骤中使用。 URL 采用以下代码片段的形式：
```
http://localhost/?code={authorization_code}
```

使用授权代码和 cURL 获取访问令牌

现在，cURL 可用于从 Microsoft 标识平台请求访问令牌。

复制以下代码片段中的 cURL 命令。将括号中的值替换为终端的以下参数。请务必移除括号：

Bash
Windows 命令提示符

curl -X POST https://login.microsoftonline.com/{tenant_id}/oauth2/v2.0/token \
-d 'client_id={web-app-calls-web-api_application_client_id}' \
-d 'api://{web_API_application_client_id}/Forecast.Read' \
-d 'code={authorization_code}&session_state={web-app-calls-web-api_application_client_id}' \
-d 'redirect_uri=http://localhost' \
-d 'grant_type=authorization_code' \
-d 'client_secret={client_secret}'

curl -X POST https://login.microsoftonline.com/{tenant_id}/oauth2/v2.0/token ^
 -d "client_id={web-app-calls-web-api_application_client_id}" ^
 -d "api://{web_API_application_client_id}/Forecast.Read" ^
 -d "code={authorization_code}&session_state={web-app-calls-web-api_application_client_id}" ^
 -d "redirect_uri=http://localhost" ^
 -d "grant_type=authorization_code" ^
 -d "client_secret={client_secret}"

{tenant_id} 是 Web 应用目录（租户）ID。
client_id={web-app-calls-web-api_application_client_id} 和 session_state={web-app-calls-web-api_application_client_id} 是 Web 应用程序 (web-app-calls-web-api)“概述”窗格上的“应用程序（客户端）ID”。
api://{web_API_application_client_id}/Forecast.Read 是 Web API (NewWebAPI1)“概述”窗格上的“应用程序（客户端）ID”。
code={authorization_code} 是已在请求授权代码中收到的授权代码。这支持 cURL 工具请求访问令牌。
client_secret={client_secret} 是在“添加客户端密码”中记录的客户端密码值。

运行 cURL 命令，如果输入正确，应会收到类似于以下输出的 JSON 响应：

{
   "token_type": "Bearer",
   "scope": "api://{web_API_application_client_id}/Forecast.Read",
   "expires_in": 3600,
   "ext_expires_in": 3600,
   "access_token": "{access_token}"
}

使用访问令牌调用 Web API

通过运行前面的 cURL 命令，Microsoft 标识平台提供了访问令牌。现在，可将获取的令牌用作 HTTP 请求中的持有者来调用 Web API。

要调用 Web API，请复制以下 cURL 命令，替换括号中的以下值并将其粘贴到终端：
```
curl -X GET https://localhost:{port}/weatherforecast -ki \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer {access_token}"
```
- {access_token} 从上一部分中的 JSON 输出记录的访问令牌值。
- {port} 在终端中运行 API 时记录的来自 Web API 的端口号。确保它是 https 端口号。

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

HTTP/2 200
content-type: application/json; charset=utf-8
date: Day, DD Month YYYY HH:MM:SS
server: Kestrel
[{"date":"YYYY-MM-DDTHH:MM:SS","temperatureC":36,"summary":"Hot","temperatureF":96},{"date":"YYYY-MM-DDTHH:MM:SS","temperatureC":43,"summary":"Warm","temperatureF":109},{"date":"YYYY-MM-DDTHH:MM:SS","temperatureC":18,"summary":"Warm","temperatureF":64},{"date":"YYYY-MM-DDTHH:MM:SS","temperatureC":50,"summary":"Chilly","temperatureF":121},{"date":"YYYY-MM-DDTHH:MM:SS","temperatureC":3,"summary":"Bracing","temperatureF":37}]

后续步骤

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

通过

使用 cURL 调用 ASP.NET Core Web API

先决条件

将应用程序注册到 Microsoft 标识平台

注册 Web API

公开 API

注册 Web 应用

添加客户端密码

添加应用程序权限以允许访问 Web API

测试 Web API

测试 Web API

请求授权代码

使用授权代码和 cURL 获取访问令牌

使用访问令牌调用 Web API

后续步骤

反馈

其他资源