本文介绍如何使用客户端 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 Core 6.0 SDK
。
Microsoft 标识平台要求应用程序在注册后才能使用标识和访问管理服务。 通过应用程序注册，可以指定应用程序的名称和类型以及登录受众。 登录受众指定允许哪些类型的用户帐户登录给定应用程序。
注册 Web API
本文中的步骤可能因开始使用的门户而略有不同。
请按照以下步骤创建 Web API 注册：
-
至少以
应用程序开发人员
的身份登录到
Microsoft Entra 管理中心
。
-
如果你有权访问多个租户，请使用顶部菜单中的“设置”图标
，通过“目录 + 订阅”菜单切换到你希望在其中注册应用程序的租户。
-
浏览到“标识”>“应用程序”>“应用注册”。
-
选择“新注册”。
-
为应用程序输入
名称
，例如
NewWebAPI1
。
-
对于“支持的帐户类型”设置，请选择“仅限此组织目录中的帐户”。 要了解不同帐户类型的信息，选择“
帮我选择
”选项。
-
选择“注册”。
-
注册完成后，将显示应用程序的“概述”窗格。 记录要在应用程序源代码中使用的目录（租户）ID 和应用程序（客户端）ID。
公开 API
注册 API 后，可以通过定义 API 向客户端应用程序公开的范围来配置其权限。 客户端应用程序通过将访问令牌及其请求传递到受保护的 Web API 来请求执行操作的权限。 然后，仅当接收的访问令牌有效时，Web API 才会执行请求的操作。
-
在“
管理
”下，选择“
公开 API”>“添加范围
”。 选择“
保存并继续
”，以接受建议的
应用程序 ID URI
(api://{clientId})
。
{clientId}
是从“
概述
”页面记录的值。 然后输入以下信息：
-
对于“范围名称”，输入
Forecast.Read
。
-
对于“谁能同意?”，请确保选择了“管理员和用户”选项 。
-
在“管理员同意显示名称”框中，输入
Read forecast data
。
-
在“管理员同意说明”框中，输入
Allows the application to read weather forecast data
。
-
在“用户同意显示名称”框中，输入
Read forecast data
。
-
在“用户同意说明”框中，输入
Allows the application to read weather forecast data
。
-
确保将“
状态
”设置为“
已启用
”。
-
选择“添加作用域”。 如果已正确输入范围，则会在“
公开 API
”窗格中列出该范围。
-
选择“新注册”。
-
输入应用程序的
名称
，例如
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
将显示类似于以下的输出。 记录 https://localhost:{port} URL 中的端口号。
info: Microsoft.Hosting.Lifetime[14]
Now listening on: https://localhost:{port}
将显示类似于以下的输出。 记录 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 命令。 将括号中的值替换为终端的以下参数。 请务必移除括号：
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 授权代码流和应用程序类型的详细信息，请参阅：
- Microsoft 标识平台和 OAuth 2.0 授权代码流
- Microsoft 标识平台的应用程序类型
