使用 Insomnia 呼叫 ASP.NET Core Web API

發行項
11/23/2024

本文說明如何使用 Insomnia 呼叫受保護的 ASP.NET Core Web API。 Insomnia 是一種應用程式，可讓您將 HTTP 要求傳送至 Web API，以測試其授權和存取控制 (驗證) 原則。在本文中，您會在租用戶中註冊一個 Web 應用程式和一個 Web API。 Web 應用程式用來取得 Microsoft 身分識別平台所產生的存取權杖。接下來，您會使用該權杖透過 Insomnia 對 Web API 進行授權呼叫。

本文說明如何使用 Insomnia 呼叫受保護的 ASP.NET Core Web API。 Insomnia 是一種應用程式，可讓您將 HTTP 要求傳送至 Web API，以測試其授權和存取控制 (驗證) 原則。繼教學課程：將受保護的端點實作至 API (您在其中建立了受保護的 API) 之後，您必須向 Microsoft 身分識別平台註冊 Web 應用程式以產生存取權杖。接下來，您會使用該權杖透過 Insomnia 對 API 進行授權呼叫。

必要條件

具有有效訂用帳戶的 Azure 帳戶。免費建立帳戶。
此 Azure 帳戶必須具有管理應用程式的權限。下列任何 Microsoft Entra 角色都包含必要的權限:
- 應用程式系統管理員
- 應用程式開發人員
- 雲端應用程式系統管理員
下載並安裝 Insomnia。您會使用 Insomnia 來取得 API 要求的存取權杖。
.NET 8.0 SDK 的最低需求。

具有有效訂用帳戶的 Azure 帳戶。免費建立帳戶。
此 Azure 帳戶必須具有管理應用程式的權限。下列任何 Microsoft Entra 角色都包含必要的權限:
- 應用程式系統管理員
- 應用程式開發人員
- 雲端應用程式系統管理員
完成教學課程系列：
下載並安裝 Insomnia。

註冊應用程式

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 個月。
選取 [新增]。
請務必記錄用戶端密碼的 [值]。離開此頁面後，就「不會再次顯示」此祕密值。

如需如何安全儲存用戶端密碼的詳細資訊，請參閱 Key Vault 中中密碼管理的最佳做法。

新增用來存取 Web API 的權限

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

請依照下列步驟來設定用戶端對 Web API 的權限：

在應用程式的 [概觀] 窗格的 [管理] 底下，選取 [API 權限]>[新增權限]>[我的組織使用的 API]。
選取 [NewWebAPI1] 或您想要新增權限的 API。
在 [選取權限] 底下，勾選 [Forecast.Read] 旁的方塊。您需要展開 [權限] 清單。這會選取用戶端應用程式應該代表登入使用者擁有的權限。
選取 [新增權限] 來完成程序。

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

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

測試 Web API

若要確保您的 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 [目錄 (租用戶) 識別碼]。
執行下列命令以啟動應用程式：
```
dotnet run
```

您會看到如下的輸出。記錄 https://localhost:{port} URL 中的連接埠號碼。

...
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: https://localhost:{port}
...

測試 Web API

若要確保您的 API 正常運作並準備好處理要求，請依照下列步驟進行：

瀏覽至在教學課程：建立 ASP.NET Core 專案並設定 API 中建立的 Web API (例如 NewWebAPILocal)，然後開啟資料夾。
開啟新的終端機視窗並瀏覽至 Web API 專案所在的資料夾。
- .NET 6.0
- .NET 7.0
1. 執行下列命令以啟動應用程式：
```
dotnet run
```
1. 開啟新的終端機，然後執行下列命令以在 https 設定檔上啟動應用程式：
```
dotnet run -launch-profile https`
```

您會看到如下的輸出。記錄 https://localhost:{port} URL 中的連接埠號碼。

...
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: https://localhost:{port}
...

在 Insomnia 中設定對 Web API 的授權要求

若要取得 API 要求的存取權杖，請依照下列步驟進行：

啟動 Insomnia 應用程式。
選取 [新增 HTTP 要求]，或者您可以使用 [Ctrl + N] 來建立新的 HTTP 要求。
在 [新增要求模式] 中，從下拉式清單中選取 [GET] 方法。
對於要求 URL，輸入 Web API 所公開端點的 URL，https://localhost:{port}/weatherforecast。
從 [驗證] 下拉式功能表中，選取 [OAuth 2.0]。這會顯示 [OAuth 2.0] 表單。

在 [OAuth 2.0] 表單中輸入下列值：

設定	值
GRANT TYPE	選取 [授權碼]
AUTHORIZATION URL	`https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/authorize` 將 `{tenantId}` 取代為 [目錄 (租用戶) 識別碼]
ACCESS TOKEN URL	`https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token` 將 `{tenantId}` 取代為 [目錄 (租用戶) 識別碼]
CLIENT ID	Web 應用程式註冊的 [應用程式 (用戶端) 識別碼] 值
CLIENT SECRET	Web 應用程式註冊的用戶端密碼 [值]
REDIRECT URL	輸入 `http://localhost`，會將 REDIRECT URL 設定為使用 Microsoft Entra ID 註冊的重新導向 URI。
進階選項>SCOPE	`api://{application_client_id}/Forecast.Read` 瀏覽至 Web 應用程式註冊，在 [管理] 底下，選取 [API 權限]，然後再選取 [Forecast.Read] 複製文字方塊中的值，其中包含 [範圍] 值

取得存取權杖，並將要求傳送至 Web API

輸入這些值後，請選取表單結尾的 [擷取權杖]。這會啟動 Insomnia 瀏覽器視窗，您可以在其中使用使用者認證進行驗證。請務必允許瀏覽器中的 Insomnia 應用程式產生快顯視窗。
驗證之後，請選取 [傳送]，將要求傳送至受保護的 Web API 端點。

如果要求中包含有效的存取權杖，則預期回應為 200 OK，其輸出類似下列內容：

[
  {
    "date": "YYYY-MM-DDTHH:MM:SS",
    "temperatureC": -16,
    "summary": "Scorching",
    "temperatureF": 4
  },
  {
    "date": "YYYY-MM-DDTHH:MM:SS",
    "temperatureC": 1,
    "summary": "Sweltering",
    "temperatureF": 33
  },
  {
    "date": "YYYY-MM-DDTHH:MM:SS",
    "temperatureC": 26,
    "summary": "Freezing",
    "temperatureF": 78
  },
  {
    "date": "YYYY-MM-DDTHH:MM:SS",
    "temperatureC": 54,
    "summary": "Mild",
    "temperatureF": 129
  },
  {
    "date": "YYYY-MM-DDTHH:MM:SS",
    "temperatureC": 11,
    "summary": "Bracing",
    "temperatureF": 51
  }
]

如需 OAuth 2.0 授權碼流程和應用程式類型的詳細資訊，請參閱：

共用方式為

使用 Insomnia 呼叫 ASP.NET Core Web API

必要條件

註冊應用程式

註冊 Web API

公開 API

註冊 Web 應用程式

新增用戶端密碼

新增用來存取 Web API 的權限

測試 Web API

測試 Web API

在 Insomnia 中設定對 Web API 的授權要求

取得存取權杖，並將要求傳送至 Web API

意見反應

其他資源

共用方式為

使用 Insomnia 呼叫 ASP.NET Core Web API

必要條件

註冊應用程式

註冊 Web API

公開 API

註冊 Web 應用程式

新增用戶端密碼

新增用來存取 Web API 的權限

測試 Web API

測試 Web API

在 Insomnia 中設定對 Web API 的授權要求

取得存取權杖，並將要求傳送至 Web API

相關內容

意見反應

其他資源