使用 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 角色都包含必要的權限:
- 應用程式系統管理員
- 應用程式開發人員
- 雲端應用程式系統管理員
完成教學課程系列：
- 教學課程：向 Microsoft 身分識別平台註冊 Web API。
- 教學課程：建立及設定 ASP.NET Core 專案以進行驗證。
- 教學課程：對 API 實作受保護的端點。
在您的工作站電腦上下載並安裝 cURL 。

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

Microsoft 身分識別平台需要先註冊您的應用程式，才能提供身分識別和存取管理服務。應用程式註冊可讓您指定應用程式的名稱和類型，以及登入物件。登入對象會指定允許登入指定的應用程式的使用者帳戶類型。

註冊 Web API

提示

本文中的步驟可能會根據您從開始的入口網站稍有不同。

請遵循下列步驟來建立 Web API 註冊：

以至少應用程式開發人員身分登入 Microsoft Entra 系統管理中心。
如果您有多個租使用者的存取權，請使用頂端功能表中的 [設定] 圖示，切換至您要從 [目錄 + 訂用帳戶] 功能表註冊應用程式的租使用者。
流覽至 [身分>識別應用程式> 應用程式註冊]。
選取新增註冊。
輸入應用程式的 [名稱]，例如 NewWebAPI1。
在 [支援的帳戶類型] 區段中，選取 [僅限此組織目錄中的帳戶]。如需不同帳戶類型的資訊，請選取 [ 協助我選擇] 選項。
選取註冊。
註冊完成時，會顯示應用程式的 [ 概觀 ] 窗格。 記錄要用於應用程式原始碼的目錄（租使用者）標識碼和應用程式（用戶端）標識碼。

注意

藉由參考修改應用程式支援的帳戶，即可變更支援的帳戶類型。

公開 API

註冊 API 之後，您可以定義 API 公開給用戶端應用程式的範圍來設定其許可權。用戶端應用程式會藉由將存取令牌及其要求傳遞至受保護的 Web API，來要求執行作業的許可權。然後，只有當收到的存取令牌有效時，Web API 才會執行要求的作業。

在 [管理] 底下，選取 [公開 API > 新增範圍]。 選取 [儲存並繼續]，以接受建議的應用程式標識碼 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 。
選取註冊。

註冊完成時，應用程式註冊會顯示在 [ 概觀 ] 窗格中。 記錄要用於後續步驟的目錄（租使用者）標識碼和應用程式（用戶端）標識碼。

新增用戶端密碼

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

請遵循下列步驟來設定客戶端密碼：

從 [概觀] 窗格的 [管理] 底下，選取 [憑證與秘密>客戶端密碼] [客戶端密碼>][新增客戶端密碼]。
新增客戶端密碼的描述，例如 我的客戶端密碼。
選取祕密的到期日，或指定自訂存留期。
- 客戶端密碼的存留期限制為兩年（24 個月）或更少。您無法指定超過 24 個月的自訂存留期。
- Microsoft 建議您將到期值設定為少於 12 個月。
選取 [新增]。
請務必記錄客戶端密碼的值。離開此頁面後，就「不會再次顯示」此祕密值。

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

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

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

從 Web 應用程式的 [概觀] 窗格（web-app-that-calls-web-api），在 [管理] 底下，選取 [API 許可權>] [新增許可權>我的 API]。
選取 [ 新增][WebAPI1 ] 或您想要新增許可權的 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 應用程式（用戶端）識別碼。
- {DIRECTORY_TENANT_ID}是應用程式 [概觀] 窗格 應用程式註冊 上的 Web API 目錄（租使用者）識別碼。
執行下列命令以啟動應用程式：
- .NET 6.0
- .NET 7.0
```
dotnet run
```
```
dotnet run --launch-profile https
```

隨即會出現類似下列的輸出。在 URL 中 https://localhost:{port} 記錄埠號碼。

... 
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
```

隨即會出現類似下列的輸出。在 URL 中 https://localhost:{port} 記錄埠號碼。

... 
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 應用程式 目錄（租使用者）識別碼。
- {web-app-calls-web-api_application_client_id}是 Web 應用程式 [web-app-calls-web-api] [概觀] 窗格上的 [應用程式][用戶端] 識別符。
- {web_API_application_client_id}是 Web API [新增][WebAPI1] [概觀] 窗格上的 [應用程式][用戶端] 識別符。
以 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 應用程式 目錄（租使用者）識別碼。
- 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 [新增][WebAPI1] [概觀] 窗格上的 [應用程式][用戶端] 識別符。
- 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 授權碼流程和應用程式類型的詳細資訊，請參閱：

Share via

使用 cURL 呼叫 ASP.NET Core Web API

必要條件

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

註冊 Web API

公開 API

註冊 Web 應用程式

新增用戶端密碼

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

測試 Web API

測試 Web API

要求授權碼

使用授權碼和 cURL 來取得存取令牌

使用存取令牌呼叫 Web API

下一步

更多資源