使用 cURL 调用 ASP.NET Core Web API

先决条件

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

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

注册 Web 应用

但是，拥有 Web API 是不够的，因为还需要 Web 应用来获取访问令牌才能访问已创建的 Web API。

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

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

添加客户端密码

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

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

1. 在“概述”窗格的“管理”下，选择“证书和机密”>“客户端机密”>“新建客户端机密”。

2. 为客户端密码添加说明，例如“我的客户端密码”。

3. 选择机密的过期时间，或指定自定义的生存期。

   • 客户端密码的生存期限制为两年（24 个月）或更短。 不能指定超过 24 个月的自定义生存期。
   • Microsoft 建议将过期时间值设置为小于 12 个月。

4. 选择 添加 。

5. 请务必记录客户端密码的值。 退出此页面后，此机密值永不再显示。

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

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

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

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

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

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

请求授权代码

授权代码流始于客户端将用户定向到 /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

1. 复制 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”。

2. 以注册应用的 Microsoft Entra 租户中的用户身份登录。 如有必要，可同意任何访问请求。

3. 浏览器将会重定向到 http://localhost/。 请参阅浏览器的导航栏，并复制 {authorization_code} 以在以下步骤中使用。 URL 采用以下代码段的形式：

   http://localhost/?code={authorization_code}
   

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

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

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

   • Bash
   • Windows 命令提示符

   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} 是在“添加客户端密码”中记录的客户端密码值。

2. 运行 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。

1. 要调用 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 端口号。

2. 如果请求中包含有效的访问令牌，预期的响应将为 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 标识平台的应用程序类型