教學課程：代表登入的使用者將 App Service 應用程式連線到 SQL Database

本教學課程說明如何使用 Microsoft Entra 驗證提供者在 App Service 應用程式中啟用內建驗證，然後藉由模擬登入使用者 (也稱為代理者流程) 將其連線到後端 Azure SQL Database 來加以擴充。 這是教學課程：使用受控識別存取資料的更進階連線方法，並在企業案例中具有下列優點：

• 消除後端服務的連線秘密，如同受控識別方法一樣。
• 讓後端資料庫 (或任何其他 Azure 服務) 更能控制授與其資料和功能存取權的人員或方式。
• 可讓應用程式針對已登入的使用者量身打造其資料簡報。

在本教學課程中，您要將 Microsoft Entra 驗證新增至您在下列其中一個教學課程所部署的 Web 應用程式範例：

• 教學課程：在 Azure 中搭配 Azure SQL Database 來建置 ASP.NET 應用程式
• 教學課程：在 Azure App Service 中建置 ASP.NET Core 和 Azure SQL Database 應用程式

當您完成時，範例應用程式會代表登入的使用者驗證使用者是否安全地連線到 SQL Database。

注意

本教學課程所涵蓋的步驟支援下列版本：

• .NET Framework 4.8 和更新版本
• .NET 6.0 和更新版本

您將了解：

• 啟用 Azure SQL Database 的內建驗證
• 停用 Azure SQL Database 中的其他驗證選項
• 啟用 App Service 驗證
• 使用 Microsoft Entra ID 做為識別提供者
• 代表登入的 Microsoft Entra 使用者存取 Azure SQL Database

注意

Microsoft Entra 驗證與內部部署 Active Directory (AD DS) 中的整合式 Windows 驗證不同。 AD DS 和 Microsoft Entra ID 使用完全不同的驗證通訊協定。 如需詳細資訊，請參閱 Microsoft Entra Domain Services 文件。

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

必要條件

本文會從您在以下教學課程之一中中斷處繼續：

• 教學課程：在 Azure 中搭配 SQL Database 來建置 ASP.NET 應用程式
• 教學課程：在 Azure App Service 中組建 ASP.NET Core 和 SQL Database 應用程式。

如果您尚未進行，請先依照這兩個教學課程的其中一個來進行。 或者，您可以使用 SQL Database 針對自己的 .NET 應用程式調整步驟。

備妥環境以使用 Azure CLI。

Azure Cloud Shell 是裝載於 Azure 中的互動式殼層環境，可在瀏覽器中使用。 您可以使用 Bash 或 PowerShell 搭配 Cloud Shell，與 Azure 服務共同使用。 您可以使用 Cloud Shell 預先安裝的命令，執行本文提到的程式碼，而不必在本機環境上安裝任何工具。

要啟動 Azure Cloud Shell：

選項	範例/連結
選取程式碼或命令區塊右上角的 [試試看]。 選取 [試試看] 並不會自動將程式碼或命令複製到 Cloud Shell 中。
請前往 https://shell.azure.com，或選取 [啟動 Cloud Shell] 按鈕，在瀏覽器中開啟 Cloud Shell。
選取 Azure 入口網站右上方功能表列上的 [Cloud Shell] 按鈕。

若要使用 Azure Cloud Shell：

1. 啟動 Cloud Shell。

2. 選取程式碼區塊 (或命令區塊) 上的 [複製] 按鈕以複製程式碼或命令。

3. 透過在 Windows 和 Linux 上選取 Ctrl+Shift+V；或在 macOS 上選取 Cmd+Shift+V，將程式碼或命令貼到 Cloud Shell 工作階段中。

4. 選取 Enter 鍵執行程式碼或命令。

1.使用 Microsoft Entra 驗證設定資料庫伺服器

首先，將 Microsoft Entra 使用者指派為伺服器管理員，啟用對 SQL 資料庫的 Microsoft Entra 驗證。 此使用者與您用來註冊 Azure 訂用帳戶的 Microsoft 帳戶不同。 這必須是您已在 Microsoft Entra ID 中建立、匯入、同步處理或受邀加入的使用者。 若要進一步了解允許的 Microsoft Entra 使用者，請參閱 SQL Database 中的 Microsoft Entra 功能和限制。

1. 如果您的 Microsoft Entra 租用戶還沒有使用者，請依照使用 Microsoft Entra ID 新增或刪除使用者中的步驟建立一個。

2. 使用 az ad user list 尋找 Microsoft Entra 使用者的物件識別碼，並取代 <user-principal-name>。 結果會儲存到變數中。

   azureaduser=$(az ad user list --filter "userPrincipalName eq '<user-principal-name>'" --query [].id --output tsv)
   

   提示

   若要在 Microsoft Entra 中查看所有使用者主體名稱的清單，請執行 az ad user list --query [].userPrincipalName。

3. 在 Cloud Shell 中使用 az sql server ad-admin create 命令，將此 Microsoft Entra 使用者新增為 Active Directory 管理員。 在下列命令中，將 <server-name> 取代為 伺服器名稱 (不含 .database.windows.net 尾碼)。

   az sql server ad-admin create --resource-group <group-name> --server-name <server-name> --display-name ADMIN --object-id $azureaduser
   

4. 將資料庫伺服器驗證限制為 Active Directory 驗證。 此步驟實際上會停用 SQL 驗證。

   az sql server ad-only-auth enable --resource-group <group-name> --name <server-name>
   

如需關於新增 Active Directory 管理員的詳細資訊，請參閱佈建 Microsoft Entra 管理員 (SQL Database)。

2.為您的應用程式啟用使用者驗證

您可以使用 Microsoft Entra ID 做為識別提供者來啟用驗證。 如需詳細資訊，請參閱為 App Service 應用程式設定 Microsoft Entra 驗證。

1. 在 Azure 入口網站功能表中，選取 [資源群組]，或從任何頁面搜尋並選取 [資源群組]。

2. 在 [資源群組] 中，尋找並選取資源群組，然後選取您的應用程式。

3. 在應用程式的左側功能表中，選取 [驗證]，然後選取 [新增識別提供者]。

4. 在 [新增識別提供者] 頁面中，選取 [Microsoft] 做為 [識別提供者]，以登入 Microsoft 和 Microsoft Entra 識別。

5. 接受預設設定，然後選取 [新增]。

   

提示

如果發生錯誤，且您重新設定應用程式的驗證設定，權杖存放區中的權杖可能不會從新的設定重新產生。 為了確保您的權杖會重新產生，您必須先登出應用程式，然後再重新登入。 您可以透過簡單的方式完成此動作，即以私用模式使用瀏覽器，並在變更應用程式中的設定後關閉，再以私用模式重新開啟瀏覽器。

3.對 SQL Database 設定使用者模擬

目前，您的 Azure 應用程式會連線至使用受控 SQL 驗證 (使用者名稱和密碼) 做為應用程式設定的 SQL Database。 在此步驟中，您會提供應用程式權限，代表登入的 Microsoft Entra 使用者存取 SQL Database。

1. 在應用程式的 [驗證] 頁面中，在 [識別提供者] 底下選取您的應用程式名稱。 此應用程式註冊會自動為您產生。 在左側功能表中選取 [API 權限]。

2. 選取 [新增權限]，然後選取 [我的組織使用的 API]。

3. 在搜尋方塊中輸入 Azure SQL Database，然後選取結果。

4. 在 Azure SQL Database 的 [要求 API 權限] 頁面中，選取 [委派的權限]和 [user_impersonation]，然後選取 [新增權限]。

   

4.設定 App Service，以傳回可使用的存取權杖

Microsoft Entra ID 中的應用程式註冊現在具有必要權限，可模擬登入的使用者連線到 SQL Database。 接下來，您會將 App Service 應用程式設定為提供可使用的存取權杖。

在 Cloud Shell 中，在應用程式上執行下列命令，將 scope 參數新增至驗證設定 identityProviders.azureActiveDirectory.login.loginParameters。 該設定會使用 [jq] 進行 JSON 處理，此功能已安裝在 Cloud Shell 中。

authSettings=$(az webapp auth show --resource-group <group-name> --name <app-name>)
authSettings=$(echo "$authSettings" | jq '.properties' | jq '.identityProviders.azureActiveDirectory.login += {"loginParameters":["scope=openid profile email offline_access https://database.windows.net/user_impersonation"]}')
az webapp auth set --resource-group <group-name> --name <app-name> --body "$authSettings"

命令可有效地新增具有額外自訂範圍的 loginParameters 屬性。 以下是要求範圍的說明：

• 預設情況下，App Service 會要求 openid、profile 和 email。 如需詳細資訊，請參閱 OpenID Connect 範圍。
• https://database.windows.net/user_impersonation 是指 Azure SQL Database。 這是提供您 JWT 權杖的範圍，其中包含 SQL Database 做為權杖物件。
• 為了方便起見，此處包含了 offline_access (以防您要重新整理權杖)。

提示

若要改用 Web 介面來設定必要的範圍，請參閱 重新整理驗證權杖中的 Microsoft 步驟。

您的應用程式已完成設定。 應用程式現在可以產生 SQL Database 接受的權杖。

5.在應用程式程式碼中使用存取權杖

您針對專案遵循的步驟取決於您使用的是 Entity Framework (ASP.NET 預設)，還是 Entity Framework Core (ASP.NET Core 預設)。

Entity Framework

1. 在 Visual Studio 中，開啟套件管理員主控台，並更新 Entity Framework：

   Update-Package EntityFramework
   

2. 在 Models/MyDbCoNtext.cs 中的 DbCoNtext 物件裡，將下列程式碼新增至預設建構函式。

   var conn = (System.Data.SqlClient.SqlConnection)Database.Connection;
   conn.AccessToken = System.Web.HttpContext.Current.Request.Headers["X-MS-TOKEN-AAD-ACCESS-TOKEN"];
   

Entity Framework Core

在您的 DbContext 物件中 (在 Models/MyDbContext.cs 中)，將預設建構函式變更為下列項目。

public MyDatabaseContext (DbContextOptions<MyDatabaseContext> options, IHttpContextAccessor accessor)
    : base(options)
{
    var conn = Database.GetDbConnection() as SqlConnection;
    conn.AccessToken = accessor.HttpContext.Request.Headers["X-MS-TOKEN-AAD-ACCESS-TOKEN"];
}

注意

程式碼會將 App Service 驗證所提供的存取權杖新增至連線物件。

此程式碼變更無法在本機運作。 如需詳細資訊，請參閱如何在使用 App Service 驗證時，在本機進行偵錯？。

6.發佈您的變更

ASP.NET

1. 如果您來自教學課程：使用 SQL Database，在 Azure 中建置 ASP.NET 應用程式，請使用 SQL 驗證並搭配使用者名稱和密碼，在 App Service 中設定連接字串。 使用下列命令來移除連線秘密，但請將 <group-name>、<app-name>、<db-server-name> 和 <db-name> 取代為您的資訊。

   az webapp config connection-string set --resource-group <group-name> --name <app-name> --connection-string-type SQLAzure --settings MyDbConnection="server=tcp:<db-server-name>.database.windows.net;database=<db-name>;"
   

2. 在 Visual Studio 中發佈您的變更。 在 [方案總管] 中，以滑鼠右鍵按一下 [DotNetAppSqlDb] 專案，然後選取 [發佈]。

   

3. 在發佈頁面中，選取 [發佈]。

ASP.NET Core

1. 如果您來自教學課程：在 Azure App Service 中建置 ASP.NET Core 和 SQL Database 應用程式，則您在 App Service 中會有一個使用 SQL 驗證並搭配使用者名稱和密碼、名為 defaultConnection 的連接字串。 使用下列命令來移除連線秘密，但請將 <group-name>、<app-name>、<db-server-name> 和 <db-name> 取代為您的資訊。

   az webapp config connection-string set --resource-group <group-name> --name <app-name> --connection-string-type SQLAzure --settings defaultConnection="server=tcp:<db-server-name>.database.windows.net;database=<db-name>;"
   

2. 您已在 GitHub 分支中變更程式碼，並在瀏覽器中使用 Visual Studio Code。 從左側功能表中，選取 [原始檔控制]。

3. 輸入認可訊息，例如 OBO connect，然後選取 [認可]。

   認可會對 App Service 觸發 GitHub Actions 部署。 請等候幾分鐘的時間讓部署完成。

當新的網頁顯示待辦事項清單時，表示應用程式正代表登入的 Microsoft Entra 使用者連線到資料庫。

您現在應該能夠如以往一樣編輯待辦事項清單。

7.清除資源

在上述步驟中，您已建立資源群組中的 Azure 資源。 如果您在未來不需要這些資源，請在 Cloud Shell 中執行下列命令，刪除資源群組：

az group delete --name <group-name>

此命令可能會花一分鐘執行。

常見問題集

• 為什麼我會收到 Login failed for user '<token-identified principal>'. 錯誤？
• 如何在 Azure SQL Database 中新增其他 Microsoft Entra 使用者或群組？
• 如何在使用 App Service 驗證時，在本機進行偵錯？
• 存取權杖到期時會發生什麼事？

為什麼我會收到 Login failed for user '<token-identified principal>'. 錯誤？

導致這個錯誤最常見的原因包括：

• 您是在本機執行程式碼，且 X-MS-TOKEN-AAD-ACCESS-TOKEN 要求標頭中沒有有效的權杖。 請參閱如何在使用 App Service 驗證時，在本機進行偵錯？。
• SQL Database 上未設定 Microsoft Entra 驗證。
• 不允許登入的使用者連線到資料庫。 請參閱如何在 Azure SQL Database 中新增其他 Microsoft Entra 使用者或群組？。

如何在 Azure SQL Database 中新增其他 Microsoft Entra 使用者或群組？

1. 連線到您的資料庫伺服器，例如使用 sqlcmd 或 SSMS。

2. 在 SQL Database 文件中建立對應至 Microsoft Entra 身分識別的自主使用者。

   下列 Transact-SQL 範例會將 Microsoft Entra 身分識別新增至 SQL Server，並為其提供一些資料庫角色：

   CREATE USER [<user-or-group-name>] FROM EXTERNAL PROVIDER;
   ALTER ROLE db_datareader ADD MEMBER [<user-or-group-name>];
   ALTER ROLE db_datawriter ADD MEMBER [<user-or-group-name>];
   ALTER ROLE db_ddladmin ADD MEMBER [<user-or-group-name>];
   GO
   

如何在使用 App Service 驗證時，在本機進行偵錯？

由於 App Service 驗證是 Azure 中的功能，因此無法讓相同的程式碼在本機環境中運作。 不同於在 Azure 中執行的應用程式，您的本機程式碼不會受益於 App Service 的驗證中介軟體。 您有幾個替代方案：

• 使用 Active Directory Interactive 從本機環境連線到 SQL Database。 驗證流程不會將使用者登入應用程式本身，但會使用登入的使用者連線到後端資料庫，並可讓您在本機測試資料庫授權。
• 手動將存取權杖從 https://<app-name>.azurewebsites.net/.auth/me 複製到您的程式碼，以取代 X-MS-TOKEN-AAD-ACCESS-TOKEN 要求標頭。
• 如果您是從 Visual Studio 部署，請使用 App Service 應用程式的遠端偵錯。

存取權杖到期時會發生什麼事？

存取權杖會在一段時間後到期。 若要了解如何重新整理存取權杖，而不需要讓使用者向應用程式重新驗證，請參閱重新整理識別提供者權杖。

下一步

您已了解如何︰

• 啟用 Azure SQL Database 的內建驗證
• 停用 Azure SQL Database 中的其他驗證選項
• 啟用 App Service 驗證
• 使用 Microsoft Entra ID 做為識別提供者
• 代表登入的 Microsoft Entra 使用者存取 Azure SQL Database

將現有的自訂 DNS 名稱對應至 Azure App Service

教學課程：從安全的 .NET 應用程式中，以應用程式身分存取 Microsoft Graph

教學課程：使用虛擬網路整合隔離後端通訊