共用方式為

教學課程：建置會使用 Microsoft 身分識別平台的多租用戶精靈

  • 發行項

在本教學課程中，您會下載並執行 ASP.NET 精靈 Web 應用程式，以示範如何使用 OAuth 2.0 用戶端認證授與，取得用來呼叫 Microsoft Graph API 的存取權杖。

在本教學課程中：

  • 整合精靈應用程式與 Microsoft 身分識別平台
  • 由系統管理員將應用程式權限直接授予應用程式
  • 取得存取權杖以呼叫 Microsoft Graph API
  • 呼叫 Microsoft Graph API。

如果您沒有 Azure 訂用帳戶，請在開始前建立免費帳戶。

必要條件

  • Visual Studio 2017 或 2019。
  • Microsoft Entra 租用戶。 如需詳細資訊，請參閱如何取得 Microsoft Entra 租用戶。
  • 租用戶中的一或多個使用者帳戶。 此範例不適用於 Microsoft 帳戶。 若使用 Microsoft 帳戶登入，且您從未在目錄中建立使用者帳戶，請於此時建立。

案例

此應用程式會建置為 ASP.NET MVC 應用程式。 其使用 OWIN OpenID Connect 中介軟體來讓使用者登入。

此範例中的「精靈」元件是一個 API 控制器 (SyncController.cs)。 控制器收到呼叫時會從 Microsoft Graph 提取客戶的 Microsoft Entra 租用戶使用者清單。 SyncController.cs 會由 Web 應用程式中的 AJAX 呼叫加以觸發。 其會使用適用於 .NET 的 Microsoft 驗證程式庫 (MSAL) 來取得 Microsoft Graph 的存取權杖。

由於此應用程式是供 Microsoft 企業客戶使用的多租用戶應用程式，因此必須提供方法讓客戶可以「註冊」應用程式或將應用程式「連線」至其公司資料。 在連線過程中，應用程式開發人員會先將 應用程式權限 直接授予應用程式，讓其能夠在沒有登入使用者的情況下，能夠以非互動方式存取公司資料。 此範例中的邏輯主要將說明如何使用身分識別平台的管理員同意端點來完成此連線流程。

圖表顯示 UserSync 應用程式與三個連線至 Azure 的本機項目，開始點驗證是以互動方式取得權杖以連線至 Microsoft Entra ID，AccountController 取得管理員同意以連線至 Microsoft Entra ID，SyncController 讀取使用者以連線至 Microsoft Graph。

若要進一步了解此範例中使用的概念，請閱讀適用於身分識別平台的用戶端認證通訊協定文件。

複製或下載此存放庫

從殼層或命令列輸入下列命令：

git clone https://github.com/Azure-Samples/active-directory-dotnet-daemon-v2.git

或者，下載 ZIP 檔案中的範例。

註冊您的應用程式

此範例有一個專案。 若要向 Microsoft Entra 租用戶註冊應用程式，您可以採取以下操作：

  • 請遵循選擇租用戶和設定範例以使用您的租用戶中的步驟。
  • 使用 PowerShell 指令碼來：
    • 「自動」為您建立 Microsoft Entra 應用程式和相關物件 (密碼、權限、相依性)。
    • 修改 Visual Studio 專案的組態檔。

如果您想要使用自動化功能：

  1. 在 Windows 上，執行 PowerShell 並移至所複製目錄的根目錄。

  2. 執行此命令：

    Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope Process -Force

  3. 執行建立 Microsoft Entra 應用程式的指令碼，並據以設定範例應用程式的程式碼：

    .\AppCreationScripts\Configure.ps1

    應用程式建立指令碼中會有其他指令碼執行方式的說明。

  4. 開啟 Visual Studio 解決方案，然後選取 [啟動] 以執行程式碼。

如果您不想要使用自動化功能，則請使用下列各節中的步驟。

選擇租用戶

提示

根據您開始使用的入口網站，本文中的步驟可能略有不同。

  1. 至少以應用程式開發人員的身分登入 Microsoft Entra 系統管理中心。

  2. 如果您有權存取多個租用戶，請使用頂端功能表中的 [設定] 圖示 ，從 [目錄 + 訂用帳戶] 功能表中切換為要在其中註冊應用程式的租用戶。

  3. 瀏覽至 [身分識別] > [應用程式] > [應用程式註冊]。

  4. 選取新增註冊。

  5. 輸入應用程式的名稱，例如 dotnet-web-daemon-v2。 您的應用程式使用者可能會看到此名稱，而且您稍後可以加以變更。

  6. 在 [支援的帳戶類型] 區段中，選取 [任何組織目錄中的帳戶]。

  7. 在 [重新導向 URI (選用)] 區段中，選取下拉式方塊中的 [Web]，然後輸入 https://localhost:44316/ 和 https://localhost:44316/Account/GrantPermissions 作為重新導向 URI。

    如果有超過兩個的重新導向 URI，您稍後必須在應用程式建立成功之後，從 [驗證] 索引標籤新增這些 URI。

  8. 選取 [暫存器] 以建立應用程式。

  9. 在應用程式的 [概觀] 頁面上，尋找 [應用程式 (用戶端) 識別碼] 值並記下供稍後使用。 您必須用此識別碼來設定此專案的 Visual Studio 組態檔。

  10. 在 [管理] 底下，選取 [驗證]。

  11. 將 [前端通道登出 URL] 設定為 https://localhost:44316/Account/EndSession。

  12. 在 [隱含授與和混合式流程] 區段中，選取 [存取權杖]，然後選取 [識別碼權杖]。 此範例需要啟用隱含授與流程才能讓使用者登入並呼叫 API。

  13. 選取 [儲存]。

  14. 在 [管理] 下，選取 [憑證和密碼]。

  15. 在用戶端密碼區段底下，選取新增用戶端密碼。

  16. 輸入金鑰描述 (例如，應用程式祕密)。

  17. 選取金鑰持續時間，此值可為 [1 年]、[2 年] 或 [永不過期]。

  18. 選取 [新增]。 記錄金鑰值並儲存到安全的位置。 稍後您將需要用此金鑰在 Visual Studio 中設定專案。

  19. 在 [管理] 底下，選取 [API 權限]>[新增權限]。

  20. 在 [常用的 Microsoft API] 區段中，選取 [Microsoft Graph]。

  21. 在 [應用程式權限] 區段中，確定已選取正確的權限：User.Read.All。

  22. 選取新增權限。

設定範例以使用您的租用戶

在下列步驟中，ClientID 與「應用程式識別碼」或 AppId 相同。

在 Visual Studio 中開啟解決方案以設定專案。

設定用戶端專案

如果您使用安裝指令碼，系統會為您套用下列變更。

  1. 開啟 UserSync\Web.Config 檔案。
  2. 尋找應用程式金鑰 ida:ClientId。 將現有值取代為先前記錄的 dotnet-web-daemon-v2 應用程式識別碼。
  3. 尋找應用程式金鑰 ida:ClientSecret。 將現有值取代為您建立 dotnet-web-daemon-v2 應用程式時所儲存的金鑰。

執行範例

清除解決方案、重建解決方案、執行 UserSync 應用程式，然後在 Microsoft Entra 租用戶中以管理員身分登入。 若沒有 Microsoft Entra 租用戶可用於測試，您可以依照這些指示取得一個。

當您登入時，應用程式會先要求您提供權限，以便讓您登入並讀取您的使用者設定檔。 此同意可讓應用程式確保您是企業使用者。

使用者同意

應用程式接著會嘗試透過 Microsoft Graph，從您的 Microsoft Entra 租用戶同步處理使用者清單。 如果無法這麼做，便會要求您 (租用戶管理員) 將租用戶連線至應用程式。

然後，應用程式會要求您提供權限，以便讀取租用戶中的使用者清單。

管理員同意

授與權限之後，您就會從應用程式登出。 讓您登出可確保 Microsoft Graph 的任何現有存取權杖都會從權杖快取中移除。 當您再次登入時，所取得的全新權杖就會有可對 MS Graph 發出呼叫的必要權限。

當您授與權限時，應用程式便可在任何時間點查詢使用者。 您可以選取 [同步使用者] 按鈕，然後重新整理使用者清單來確認這一點。 嘗試新增或移除使用者，並重新同步處理此清單。 (但請注意，應用程式只會同步處理第一頁的使用者)。

關於程式碼

此範例的相關程式碼位於下列檔案中：

  • App_Start\Startup.Auth.cs、Controllers\AccountController.cs：初始登入。 特別是，控制器上的動作具有授權屬性，會強制使用者登入。 應用程式會使用授權碼流程來登入使用者。
  • Controllers\SyncController.cs：將使用者清單同步至本機記憶體內部存放區。
  • Controllers\UserController.cs：顯示本機記憶體內部存放區中的使用者清單。
  • Controllers\AccountController.cs：使用管理員同意端點，取得租用戶管理員提供的權限。

重新建立應用程式範例

  1. 在 Visual Studio 中，建立新的 Visual C# ASP.NET Web 應用程式 (.NET Framework) 專案。
  2. 在下一個畫面中，選擇 MVC 專案範本。 此外，也請為 Web API 新增資料夾和核心參考，因為稍後會新增 Web API 控制器。 將專案選擇的驗證模式保留為預設值：No Authentication。
  3. 在 [方案總管] 視窗中選取專案，然後選取 F4 鍵。
  4. 在 [專案屬性] 中，將 [已啟用 SSL] 設定為 True。 請記下 SSL URL 中的資訊。 在 Azure 入口網站中設定此應用程式的註冊時，將會用到這項資料。
  5. 新增下列 ASP.NET OWIN 中介軟體 NuGet 套件：
    • Microsoft.Owin.Security.ActiveDirectory
    • Microsoft.Owin.Security.Cookies
    • Microsoft.Owin.Host.SystemWeb
    • Microsoft.IdentityModel.Protocol.Extensions
    • Microsoft.Owin.Security.OpenIdConnect
    • Microsoft.Identity.Client
  6. 在 App_Start 資料夾中：
    1. 建立名為 Startup.Auth.cs 的類別。
    2. 從命名空間名稱中移除 .App_Start。
    3. 將啟動類別的程式碼取代為應用程式範例相同檔案內的程式碼。 請務必採用整個類別定義。 定義會從公用類別啟動變更為公用部分類別啟動。
  7. 在 Startup.Auth.cs 中，藉由新增 Visual Studio IntelliSense 所建議的 using 陳述式來解析遺漏的參考。
  8. 以滑鼠右鍵按一下專案，選取 [新增]，然後選取 [類別]。
  9. 在搜尋方塊中，輸入 OWIN。 OWIN 啟動類別便會顯示為選取項目。 加以選取，並將類別命名為 Startup.cs。
  10. 在 Startup.cs 中，將啟動類別的程式碼取代為應用程式範例相同檔案內的程式碼。 同樣地，請注意定義會從公用類別啟動變更為公用部分類別啟動。
  11. 在 Models 資料夾中，新增名為 MsGraphUser.cs 的新類別。 請將實作取代為範例中同名檔案的內容。
  12. 新增名為 AccountController 的 MVC 5 控制器 - 空白執行個體。 請將實作取代為範例中同名檔案的內容。
  13. 新增名為 UserController 的 MVC 5 控制器 - 空白執行個體。 請將實作取代為範例中同名檔案的內容。
  14. 新增名為 SyncController 的 Web API 2 5 控制器 - 空白執行個體。 請將實作取代為範例中同名檔案的內容。
  15. 針對使用者介面，在 Views\Account 資料夾中，新增三個空白 (不含模型) 檢視執行個體，分別命名為 GrantPermissions、Index 和 UserMismatch。 在 Views\User 資料夾中，新增一個名為 Index 的執行個體。 請將實作取代為範例中同名檔案的內容。
  16. 更新 Shared_Layout.cshtml 和 Home\Index.cshtml，以將不同的檢視正確地連結在一起。

將範例部署至 Azure

此專案具有 Web 應用程式和 Web API 專案。 若要將這些專案部署至 Azure 網站，請對每個專案執行下列步驟：

  1. 建立 Azure 網站。
  2. 將 Web 應用程式和 Web API 發佈至網站。
  3. 更新用戶端以呼叫網站，而非呼叫 IIS Express。

建立 dotnet-web-daemon-v2 並將其發佈至 Azure 網站

  1. 登入 Azure 入口網站。
  2. 在左上角，選取 [建立資源]。
  3. 選取 [Web]>[Web 應用程式]，然後為網站提供名稱。 例如，將網站命名為 dotnet-web-daemon-v2-contoso.azurewebsites.net。
  4. 選取 [訂用帳戶]、[資源群組] 和 [App Service 方案和位置] 的資訊。 [OS] 是 [Windows]，[發佈] 則是 [程式碼]。
  5. 選取 [建立]，並等待 App Service 建立。
  6. 當您收到部署成功通知時，請選取 [移至資源] 以移至新建立的 App Service。
  7. 網站建立好之後，請在 [儀表板] 中找到網站，然後加以選取以開啟 App Service 的 [概觀] 畫面。
  8. 從 App Service 的 [概觀] 索引標籤中，選取 [取得發行設定檔] 連結以下載發行設定檔，並加以儲存。 您可以使用其他部署機制，例如從原始檔控制進行部署。
  9. 切換至 Visual Studio，然後：
    1. 移至 dotnet-web-daemon-v2 專案。
    2. 在 [方案總管] 中以滑鼠右鍵按一下專案，然後選取 [發佈]。
    3. 選取底部列上的 [匯入設定檔]，然後匯入您先前下載的發行設定檔。
  10. 選取設定。
  11. 在 [連線] 索引標籤上，更新目的地 URL 使其使用 "https"。例如，使用 https://dotnet-web-daemon-v2-contoso.azurewebsites.net。 選取 [下一步]。
  12. 在 [設定] 索引標籤上，確定已清除 [啟用組織驗證]。
  13. 選取 [儲存]。 選取主畫面上的 [發佈]。

Visual Studio 會發佈專案，並自動開啟瀏覽器並導向至專案的 URL。 如果您看到專案的預設網頁，表示發佈成功。

更新 dotnet-web-daemon-v2 的 Microsoft Entra 租用戶應用程式註冊

  1. 返回 Microsoft Entra 系統管理中心，然後在 [應用程式註冊] 中選取 dotnet-web-daemon-v2 應用程式。
  2. 在您應用程式的 [驗證] 頁面上，以您的服務位址更新 [前端通道登出 URL] 欄位。 例如，使用 https://dotnet-web-daemon-v2-contoso.azurewebsites.net/Account/EndSession。
  3. 從 [商標] 功能表，將 [首頁 URL] 更新為您的服務位址。 例如，使用 https://dotnet-web-daemon-v2-contoso.azurewebsites.net。
  4. 儲存設定。
  5. 在 [驗證]>[重新導向 URI] 功能表的值清單中，新增相同的 URL。 如果您有多個重新導向 URL，請確定在使用應用程式服務的 URI 作為每個重新導向 URL 時，都有新的輸入項目。

清除資源

如果不再需要，請刪除您在註冊應用程式步驟中所建立的應用程式物件。 若要移除應用程式，請遵循移除您或貴組織所編寫的應用程式中的指示。

取得協助

使用 Microsoft Q&A 從社群取得支援。 請先在 Microsoft Q&A 上提出問題，並瀏覽現有問題，查看先前是否有人已提出相同問題。 請確定您的問題或意見已標記 azure-ad-adal-deprecation、azure-ad-msal 和 dotnet-standard。

如果您在範例中發現錯誤 (bug)，請在 GitHub 問題上提出問題。

如果您在 MSAL.NET 中發現錯誤 (bug)，請在 MSAL.NET GitHub 問題上提出問題。

若要提供建議，請移至 User Voice 頁面。

下一步

深入了解如何建置可使用 Microsoft 身分識別平台來存取受保護 Web API 的精靈應用程式：

案例：呼叫 Web API 的精靈應用程式