使用 cURL 呼叫 ASP.NET Core Web API

必要條件

使用 Microsoft 身分識別平台來註冊應用程式

Microsoft 身分識別平台要求您的應用程式在提供身分識別和存取權管理服務之前先進行註冊。 應用程式註冊可讓您指定應用程式的名稱、類型以及登入對象。 登入對象會指定允許登入指定的應用程式的使用者帳戶類型。

註冊 Web 應用程式

不過，擁有 Web API 是不夠的，因為還需要 Web 應用程式也取得存取權杖，才能存取您所建立的 Web API。

請依照下列步驟來建立 Web 應用程式註冊：

註冊完成後，應用程式註冊會顯示在 [概觀] 窗格中。 記錄 [目錄 (租用戶) 識別碼] 和 [應用程式 (用戶端) 識別碼]，以供後續步驟使用。

新增用戶端密碼

用戶端密碼是應用程式用來識別本身的字串值，有時稱為 [應用程式密碼]。 Web 應用程式在要求權杖時，會使用用戶端密碼來證明其身分識別。

請依照下列步驟來設定客戶端密碼：

1. 在 [概觀] 窗格的 [管理] 底下，選取 [憑證及秘密] > [用戶端密碼] > [新增用戶端密碼]。

2. 新增用戶端密碼的說明，例如 [我的用戶端密碼]。

3. 選取祕密的到期日，或指定自訂存留期。

   • 用戶端祕密存留期限制為等於或小於兩年 (24 個月)。 您無法指定超過 24 個月的自訂存留期。
   • Microsoft 建議您將到期值設定為少於 12 個月。

4. 選取 [新增]。

5. 請務必記錄用戶端密碼的 [值]。 離開此頁面後，就「不會再次顯示」此祕密值。

新增應用程式權限以允許存取 Web API

藉由在 Web 應用程式註冊中指定 Web API 的範圍，Web 應用程式可以取得包含 Microsoft 身分識別平台所提供範圍的存取權杖。 接著 Web API 可以在程式碼中根據存取權杖中找到的範圍，提供其資源的權限存取權。

請依照下列步驟來設定 Web API 的 Web 應用程式權限：

1. 在 Web 應用程式 (web-app-that-c​​alls-web-api) 的 [概觀] 窗格中，在 [管理] 底下，選取 [API 權限]>[新增權限]>[我的組織使用的 API]。
2. 選取 [NewWebAPI1] 或您想要新增權限的 API。
3. 在 [選取權限] 底下，勾選 [Forecast.Read] 旁的方塊。 您需要展開 [權限] 清單。 這會選取用戶端應用程式應該代表登入使用者擁有的權限。
4. 選取 [新增權限] 來完成程序。

將這些權限新增至 API 後，您應該會在 [設定的權限] 底下看到所選取的權限。

您可能也會注意到 Microsoft Graph API 的 [User.Read] 權限。 註冊應用程式時，系統會自動新增此權限。

要求授權碼

授權碼流程始於用戶端將使用者導向 /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

1. 複製 URL，取代下列參數並將其貼到瀏覽器中：

   • {tenant_id} 是 Web 應用程式 [目錄 (租用戶) 識別碼]。
   • {web-app-calls-web-api_application_client_id} 是 Web 應用程式 (web-app-calls-web-api) [概觀] 窗格中的 [應用程式 (用戶端) 識別碼]。
   • {web_API_application_client_id} 是 Web API (NewWebAPI1) [概覽] 窗格中的 [應用程式 (用戶端) 識別碼]。

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.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 應用程式 [目錄 (租用戶) 識別碼]。
   • 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) [概觀] 窗格中的 [應用程式 (用戶端) 識別碼]。
   • api://{web_API_application_client_id}/Forecast.Read 是 Web API (NewWebAPI1) [概覽] 窗格中的 [應用程式 (用戶端) 識別碼]。
   • 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 身分識別平台的應用程式類型