快速入門：呼叫受Microsoft身分識別平台保護的Web API

適用於: 工作群組租戶 外部租戶 （深入瞭解）

在本快速入門中，您會使用範例 Web 應用程式來示範如何使用 Microsoft 身分識別平台來保護 ASP.NET Web API。 此範例會使用 Microsoft 驗證連結庫 （MSAL） 來處理驗證和授權。

先決條件

• 具有有效訂閱的 Azure 帳戶。 免費建立帳戶。
• 在 Microsoft Entra 系統管理中心 註冊新的應用程式， 並從應用程式 [ 概觀] 頁面記錄其標識符。 如需詳細資訊，請參閱 註冊應用程式。
  • 名稱： NewWebAPI1
  • 支援的帳戶類型： 僅限此組織目錄中的帳戶（單一租使用者）

ASP.NET

• Visual Studio 2022。 免費下載Visual Studio。

ASP.NET Core

• Visual Studio 代碼

公開 API

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

ASP.NET

1. 在 [管理] 底下，選取 [公開 API]>[新增範圍]。 選取 api://{clientId}]，然後輸入下列資訊，以接受建議的應用程式識別碼 URI （） ：

   1. 針對 [範圍名稱]，輸入 access_as_user。
   2. 針對 [誰可以同意]，請確定已選取 [ 系統管理員和使用者 ] 選項。
   3. 在 [管理員同意顯示名稱] 方塊中輸入 Access TodoListService as a user。
   4. 在 [管理員同意描述] 方塊中輸入 Accesses the TodoListService web API as a user。
   5. 在 [使用者同意顯示名稱] 方塊中輸入 Access TodoListService as a user。
   6. 在 [使用者同意描述] 方塊中輸入 Accesses the TodoListService web API as a user。
   7. 對於 [狀態]，保持 [已啟用]。

2. 選取 [新增範圍]。

ASP.NET Core

新增委派的權限 （範圍）

API 必須發佈至少一個範圍，也稱為 「委派許可權」，用戶端應用程式才能成功取得使用者的存取令牌。 若要發佈範圍，請遵循下列步驟：

1. 從 [ 應用程式註冊 ] 頁面中，選取您建立的 API 應用程式 （ciam-ToDoList-api） 以開啟其 [ 概觀 ] 頁面。

2. 在 [管理] 底下，選取 [ 公開 API]。

3. 在頁面頂端的 [ 應用程式識別碼 URI] 旁，選取 [新增 ] 鏈接以產生此應用程式唯一的 URI。

4. 接受建議的應用程式識別碼 URI，例如 api://{clientId}，然後選取 [ 儲存]。 當您的 Web 應用程式要求 Web API 的存取令牌時，它會新增 URI 作為您為 API 定義之每個範圍的前置詞。

5. 在 此 API 定義的範圍 下，選取 新增範圍。

6. 輸入下列定義 API 讀取權限的值，然後選取 [新增範圍 ] 以儲存變更：

   財產	價值
   範圍名稱	ToDoList.Read
   誰可以同意	僅限系統管理員
   管理員同意顯示名稱	使用 'TodoListApi' 讀取使用者ToDo清單
   管理員同意描述	允許應用程式使用 『TodoListApi』 讀取使用者的 ToDo 清單。
   國家	啟用

7. 再次選取 [新增範圍 ]，然後輸入下列值來定義 API 的讀取和寫入存取範圍。 選取 [新增範圍 ] 以儲存變更：

   財產	價值
   範圍名稱	ToDoList.ReadWrite
   誰可以同意	僅限系統管理員
   管理員同意顯示名稱	使用 'ToDoListApi' 讀取和寫入使用者的待辦清單
   管理員同意描述	允許應用程式使用 『ToDoListApi』 讀取和寫入使用者的 ToDo 清單
   國家	啟用

深入了解在設定 Web API 許可權時的最低許可原則。

新增應用程式權限 （應用程式角色）

API 必須針對應用程式發佈至少一個應用程式角色，也稱為 應用程式許可權，用戶端應用程式才能自行取得存取令牌。 應用程式許可權是 API 想要讓用戶端應用程式以自己身分成功驗證，而不需要登入使用者時，應該發佈的許可權類型。 若要發佈應用程式許可權，請遵循下列步驟：

1. 從 [ 應用程式註冊 ] 頁面中，選取您建立的應用程式（例如 ciam-ToDoList-api），以開啟其 [ 概觀 ] 頁面。

2. 在 [管理] 下方，選取 [應用程式角色]。

3. 選取 [建立應用程式角色]，並輸入下列值，然後選取 [套用] 以儲存您的變更：

   財產	價值
   顯示名稱	ToDoList.Read.All
   允許的成員類型	應用
   價值	ToDoList.Read.All
   說明	允許應用程式使用 'TodoListApi' 讀取每位使用者的待辦事項清單
   您要啟用此應用程式角色嗎？	保持檢查

4. 再次選取 [建立應用程式角色]，並為第二個應用程式角色輸入下列值，然後選取 [套用] 以儲存您的變更：

   財產	價值
   顯示名稱	ToDoList.ReadWrite.All
   允許的成員類型	應用
   價值	ToDoList.ReadWrite.All
   說明	允許應用程式使用 'ToDoListApi' 讀取和寫入每位使用者的待辦事項清單
   您要啟用此應用程式角色嗎？	保持檢查

複製或下載範例應用程式

若要取得範例應用程式，您可以從 GitHub 複製它，或將它下載為 .zip 檔案。

ASP.NET

git clone https://github.com/AzureADQuickStarts/AppModelv2-NativeClient-DotNet.git

• 將它下載為 ZIP 檔案。

小提示

為了避免 Windows 中路徑長度限制所造成的錯誤，建議您將封存解壓縮或將存放庫複製到磁碟機根目錄附近的目錄中。

ASP.NET Core

git clone https://github.com/Azure-Samples/ms-identity-ciam-dotnet-tutorial.git

• 下載 .zip 檔案。 將它解壓縮到名稱長度少於 260 個字元的檔案路徑。

設定範例應用程式

設定程式代碼範例以符合已註冊的 Web API。

ASP.NET

1. 在 Visual Studio 中開啟方案，然後在 TodoListService 專案的根目錄下開啟 appsettings.json 檔案。

2. 在 Enter_the_Application_Id_here 和 屬性中，用您在 ClientID 入口網站中註冊的應用程式的用戶端識別碼（應用程式識別元）值來取代 Audience 的值。

將新範圍新增至 app.config 檔案

若要將新範圍新增至 TodoListClient app.config 檔案，請遵循下列步驟：

1. 在 TodoListClient 專案根資料夾中，開啟 app.config 檔案。

2. 在 TodoListServiceScope 參數中，貼上您為 TodoListService 專案註冊的應用程式識別符，並取代 {Enter the Application ID of your TodoListService from the app registration portal} 字串。

備註

請確定應用程式識別碼使用下列格式：api://{TodoListService-Application-ID}/access_as_user（其中 {TodoListService-Application-ID} 是代表TodoListService 應用程式的應用程式識別碼的 GUID）。

註冊 Web 應用程式 （TodoListClient）

在 Microsoft Entra 系統管理中心的應用程式註冊中 註冊 TodoListClient 應用程式，然後在 TodoListClient 專案中設定程式代碼。 如果客戶端和伺服器視為相同的應用程式，您可以重複使用在步驟 2 中註冊的應用程式。 如果您想要讓使用者使用個人Microsoft帳戶登入，請使用相同的應用程式。

註冊應用程式

若要註冊 TodoListClient 應用程式，請遵循下列步驟：

1. 以至少雲端應用程式管理員身分登入 Microsoft Entra 系統管理中心。

2. 流覽至 Entra ID>應用程式註冊，然後選取 新增註冊。

3. 選取 [新增註冊]。

4. 當 [註冊應用程式] 頁面開啟時，輸入您應用程式的註冊資訊：

   1. 在 [ 名稱 ] 區段中，輸入將向用戶顯示有意義的應用程式名稱（例如 NativeClient-DotNet-TodoListClient）。
   2. 針對 [支援的帳戶類型]，選取 [任何組織目錄中的帳戶]。
   3. 選取 [註冊 ] 以建立應用程式。

   備註

   在 TodoListClient 項目 app.config 檔案中，預設值 ida:Tenant 設定為 common。 可能的值為：

   • common：您可以使用公司或學校帳戶或個人 Microsoft 帳戶登入 (因為您在先前步驟中選取了 [任何組織目錄中的帳戶])。
   • organizations：您可以使用公司或學校帳戶登入。
   • consumers：您只能使用Microsoft個人帳戶登入。

5. 在應用程式的 [概觀] 頁面上，選取 [驗證]，然後完成下列步驟以新增平台：

   1. 在 [平台設定] 下，選取 [新增平台] 按鈕。
   2. 針對 [ 行動和傳統型應用程式]，選取 [ 行動裝置和傳統型應用程式]。
   3. 針對 [重新導向 URI]，選取 https://login.microsoftonline.com/common/oauth2/nativeclient 複選框。
   4. 選取設定。

6. 選取 [API 權限]，然後完成下列步驟來新增權限：

   1. 選取 [ 新增許可權] 按鈕。
   2. 請選取「我的 API」 索引標籤。
   3. 在 API 清單中，選取 [AppModelv2-NativeClient-DotNet-TodoListService API ] 或您為 Web API 輸入的名稱。
   4. 如果尚未選取，請選取 access_as_user 的 [許可權] 複選框。 如有必要，請使用 [搜尋] 方塊。
   5. 選取 [新增權限] 按鈕。

設定您的專案

將應用程式識別碼新增至 app.config 檔案，以設定 TodoListClient 專案。

1. 在 應用程式註冊入口網站的 [ 概觀 ] 頁面上，複製 應用程式 （用戶端） 識別碼的值。

2. 從 TodoListClient 專案根資料夾，開啟 app.config 檔案，然後將 [應用程式識別符] 值貼到 參數中 ida:ClientId 。

ASP.NET Core

1. 在您的 IDE 中，開啟包含範例的專案資料夾 ms-identity-ciam-dotnet-tutorial/2-Authorization/3-call-own-api-dotnet-core-daemon/ToDoListAPI。

2. 開啟 appsettings.json 檔案，其中包含下列代碼段：

   {
     "AzureAd": {
       "Instance": "Enter_the_Authority_URL_Here", //For external tenants, use instance in the form of "https://Enter_the_Tenant_Subdomain_Here.ciamlogin.com/"
       "TenantId": "Enter_the_Tenant_Id_Here",
       "ClientId": "Enter_the_Application_Id_Here",
       "Scopes": {
         "Read": ["ToDoList.Read", "ToDoList.ReadWrite"],
         "Write": ["ToDoList.ReadWrite"]
       },
       "AppPermissions": {
         "Read": ["ToDoList.Read.All", "ToDoList.ReadWrite.All"],
         "Write": ["ToDoList.ReadWrite.All"]
       }
     },
     "Logging": {...},
     "AllowedHosts": "*"
   }
   

   尋找下列值：

   • ClientId - 應用程式的識別碼，也稱為用戶端。 將value引號中的文字取代為先前從已註冊應用程式 [概觀] 頁面記錄的應用程式 （client） 識別碼。
   • TenantId - 註冊應用程式之租戶的識別碼。 將「value」替換為目錄（租戶）識別碼，該值是從先前已註冊應用程式的「概觀」頁面記錄下來的。
   • Instance - 它會指定Microsoft驗證連結庫 （MSAL） 可從中要求令牌的目錄。 根據您的案例，將 Enter_the_Authority_URL_Here 取代為下列其中一個值：
     • 針對工作場所租戶，請使用 https://login.microsoftonline.com/ 作為實例。
     • 針對外部租戶，請以 https://<Enter_the_Tenant_Subdomain_Here>.ciamlogin.com/ 的形式新增授權單位 URL

執行範例應用程式

ASP.NET

啟動這兩個專案。 針對 Visual Studio 使用者;

1. 以滑鼠右鍵按一下 Visual Studio 解決方案，然後選取 [屬性]

2. 在 [ 一般屬性] 中，選取 [ 啟動專案 ]，然後選取 [多個啟始專案]。

3. 針對這兩個專案，選擇 [開始] 作為動作

4. 使用向上箭號，確保 TodoListService 服務會先啟動，方法是將它移至清單中的第一個位置。

登入以執行 TodoListClient 專案。

1. 按 F5 以啟動專案。 服務頁面和桌面應用程式一起開啟。

2. 在 TodoListClient 中，選取右上方的 [登入]，然後使用您用來註冊應用程式的同一認證，或以同一目錄中的使用者來登入。

   如果您第一次登入，系統可能會提示您同意 TodoListService Web API。

   為了協助您存取 TodoListService Web API 並操作 To-Do 列表，登入也會要求存取令牌至 access_as_user 範疇。

預先授權客戶端應用程式

您可以預先授權用戶端應用程式存取 Web API，以允許來自其他目錄的使用者存取您的 Web API。 若要這樣做，請從用戶端應用程式將應用程式標識元新增至 Web API 的預先授權應用程式清單。 藉由新增預先授權的用戶端，您就允許使用者存取您的 Web API，而不需要提供同意。

1. 在 應用程式註冊入口 網站中，開啟 TodoListService 應用程式的屬性。
2. 在 [公開 API] 區段中，選取 [授權的用戶端應用程式] 下的 [新增用戶端應用程式]。
3. 在 [用戶端識別碼] 方塊中，貼上 TodoListClient 應用程式的應用程式識別碼。
4. 在 [授權的範圍] 區段中，選取 api://<Application ID>/access_as_user Web API 的範圍。
5. 選取 [新增應用程式]。

執行您的專案

1. 按 F5 執行您的專案。 您的 TodoListClient 應用程式隨即開啟。
2. 在右上方，選取 [ 登入]，然後使用個人Microsoft帳戶登入，例如 live.com 或 hotmail.com 帳戶或公司或學校帳戶。

選擇性：限制特定使用者的登入存取

根據預設，任何個人帳戶，例如 outlook.com 或 live.com 帳戶，或是與 Microsoft Entra ID 整合的組織的工作或學校帳戶，都可以要求令牌並存取您的 Web API。

若要指定誰可以登入您的應用程式，請變更 TenantId 檔案中的 屬性。

ASP.NET Core

1. 從 Web API 專案目錄的根目錄執行下列命令，以啟動應用程式：

   dotnet run
   

2. 如果一切運作正常，您的終端機應會顯示類似以下的輸出：

    Building...
        info: Microsoft.Hosting.Lifetime[14]
              Now listening on: https://localhost:{port}
        info: Microsoft.Hosting.Lifetime[0]
              Application started. Press Ctrl+C to shut down.
        info: Microsoft.Hosting.Lifetime[0]
              Hosting environment: Development
   ...
   

   記錄 https://localhost:{port} URL 中的連接埠號碼。

3. 若要確認端點受到保護，請更新下列 cURL 命令中的基底 URL，以符合您在上一個步驟中收到的端點，然後執行 命令：

   curl -k -X GET https://localhost:<your-api-port>/api/todolist -w "%{http_code}\n"
   

   預期的回應為 401 未經授權。

後續步驟

瞭解如何使用 Microsoft 身分識別平台保護 ASP.NET Core Web API。

教學課程：使用 Microsoft 身分識別平臺建置及保護 ASP.NET Core Web API