使用 cURL 调用 ASP.NET Core Web API
本文介绍如何使用客户端 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 后,可以通过定义 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 应用
但是,拥有 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”。
执行以下命令以启动应用:
将显示类似于以下的输出。 记录
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 项目所在的文件夹。
将显示类似于以下的输出。 记录
https://localhost:{port}
URL 中的端口号。... info: Microsoft.Hosting.Lifetime[14] Now listening on: https://localhost:{port} ...
请求授权代码
授权代码流始于客户端将用户定向到 /authorize
终结点。 在此请求中,客户端会向用户请求 Forecast.Read
权限。
https://login.partner.microsoftonline.cn/{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.partner.microsoftonline.cn/{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 授权代码流和应用程序类型的详细信息,请参阅: