使用 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 註冊：
如有多個租用戶的存取權，請使用頂端功能表中的 [設定] 圖示
，從 [目錄 + 訂用帳戶] 功能表來切換至您要在其中註冊應用程式的租用戶。瀏覽至 [身分識別] > [應用程式] > [應用程式註冊]。
選取 [新增註冊]。
輸入應用程式的 [名稱]，例如 NewWebAPI1。
在 [支援的帳戶類型] 區段中，選取 [僅限此組織目錄中的帳戶]。 如需不同帳戶類型的資訊，請選取 [協助我選擇] 選項。
選取 [註冊]。
註冊完成時，將會顯示應用程式的 [概觀] 窗格。 記錄 [目錄 (租用戶) 識別碼] 和 [應用程式 (用戶端) 識別碼]，以用於您的應用程式原始程式碼。
注意
您可以參考修改應用程式所支援的帳戶，以變更 [支援的帳戶類型]。
公開 API
註冊 API 之後，您可以定義 API 向用戶端應用程式公開的範圍來設定其權限。 用戶端應用程式會要求權限以執行作業，方法是將存取權杖連同其要求傳遞至受保護的 Web API。 然後，只有在所收到的存取權杖有效時，Web API 才會執行要求的作業。
在 [管理] 底下，選取 [公開 API > 新增範圍]。 請選取 [儲存並繼續]，以接受建議的 [應用程式識別碼 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。 - 選取 [註冊]。
註冊完成後，應用程式註冊會顯示在 [概觀] 窗格中。 記錄 [目錄 (租用戶) 識別碼] 和 [應用程式 (用戶端) 識別碼]，以供後續步驟使用。
新增用戶端密碼
用戶端密碼是應用程式用來識別本身的字串值，有時稱為 [應用程式密碼]。 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]。
- 選取 [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 [應用程式 (用戶端) 識別碼]。{DIRECTORY_TENANT_ID}是應用程式的 [概觀] 窗格 [應用程式註冊] 上的 Web API [目錄 (租用戶) 識別碼]。
執行下列命令以啟動應用程式：
您會看到如下的輸出。 記錄
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.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 (NewWebAPI1) [概覽] 窗格中的 [應用程式 (用戶端) 識別碼]。
以註冊應用程式的 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 (NewWebAPI1) [概覽] 窗格中的 [應用程式 (用戶端) 識別碼]。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 授權碼流程和應用程式類型的詳細資訊，請參閱：