教學課程：使用受控識別透過 .NET 將 Key Vault 連線至 Azure Web 應用程式

發行項
08/08/2024

Azure Key Vault 可讓您以更高的安全性儲存認證和其他秘密。不過，您的程式碼必須向 Key Vault 進行驗證，才能擷取認證。 Azure 資源受控識別可在 Microsoft Entra ID 中將受控識別自動提供給 Azure 服務，協助解決此問題。您可以使用此身分識別來完成任何支援 Microsoft Entra 驗證的服務驗證 (包括 Key Vault)，不需要在程式碼中顯示認證。

在本教學課程中，您將建立 Azure Web 應用程式，並將其部署至 Azure App Service。您將透過適用於 .NET 的 Azure Key Vault 秘密用戶端程式庫和 Azure CLI，使用受控識別向 Azure 金鑰保存庫驗證您的 Azure Web 應用程式。當您使用自選的開發語言、Azure PowerShell 和 (或) Azure 入口網站時，適用的基本原則是一樣的。

如需本教學課程中介紹的 Azure App Service Web 應用程式和部署的詳細資訊，請參閱：

必要條件

若要完成本教學課程，您需要：

Azure 訂用帳戶。免費建立一個。
.NET Core 3.1 SDK (或更新版本)。
2.28.0 版或更高版本的 Git 安裝。
Azure CLI 或 Azure PowerShell。
Azure Key Vault。您可以使用 Azure 入口網站、Azure CLI 或 Azure PowerShell 來建立金鑰保存庫。
Key Vault 秘密。您可以使用 Azure 入口網站、PowerShell 或 Azure CLI 來建立秘密。

如果您已在 Azure App Service 中部署 Web 應用程式，您可以跳至設定對金鑰保存庫的 Web 應用程式存取權和修改 Web 應用程式程式碼小節。

建立 .NET Core 應用程式

在此步驟中，您將設定本機的 .NET Core 專案。

在您電腦上的終端機視窗中，建立名為 akvwebapp 的目錄，並將其設為目前的目錄：

mkdir akvwebapp
cd akvwebapp

使用 dotnet new web 命令建立 .NET Core 應用程式：

dotnet new web

在本機執行應用程式，以便得知其部署至 Azure 時的樣貌：

dotnet run

在網頁瀏覽器中，移至 http://localhost:5000 上的應用程式。

您會看到來自範例應用程式的 "Hello World!" 訊息顯示在頁面上。

若要進一步了解如何建立適用於 Azure 的 Web 應用程式，請參閱在 Azure App Service 中建立 ASP.NET Core Web 應用程式

將應用程式部署至 Azure

在此步驟中，您會使用本機 Git 將 .NET Core 應用程式部署至 Azure App Service。如需如何建立和部署應用程式的詳細資訊，請參閱在 Azure 中建立 ASP.NET Core Web 應用程式。

設定本機 Git 部署

在終端機視窗中，選取 Ctrl+C 以關閉網頁伺服器。初始化 .NET Core 專案的 Git 存放庫：

git init --initial-branch=main
git add .
git commit -m "first commit"

您可以使用 FTP 和本機 Git，透過「部署使用者」來部署 Azure Web 應用程式。部署使用者只需設定一次，就能供所有 Azure 部署使用。使用者名稱和密碼屬於帳戶等級部署，因此與 Azure 訂用帳戶認證不同。

若要設定部署使用者，請執行 az webapp deployment user set 命令。選擇符合下列指導方針的使用者名稱和密碼：

使用者名稱必須是 Azure 中唯一的。若為本機 Git 推送，其中不可包含 @ 符號。
密碼長度必須至少為 8 個字元，且包含下列三個元素的其中兩個：字母、數字及符號。

az webapp deployment user set --user-name "<username>" --password "<password>"

JSON 輸出會將密碼顯示為 null。如果您收到 'Conflict'. Details: 409 錯誤，請變更使用者名稱。如果您收到 'Bad Request'. Details: 400 錯誤，請使用更強的密碼。

將使用者名稱和密碼記錄下來，以便在部署 Web 應用程式時使用。

建立資源群組

資源群組是一種邏輯容器，您可在其中部署和管理 Azure 資源。使用 az group create 命令建立資源群組，將您的金鑰保存庫和 Web 應用程式包含於其中：

az group create --name "myResourceGroup" -l "EastUS"

建立 App Service 方案

使用 Azure CLI 的 az appservice plan create 命令，建立 App Service 方案。下列範例會在 myAppServicePlan 定價層中建立名為 FREE 的 App Service 方案：

az appservice plan create --name myAppServicePlan --resource-group myResourceGroup --sku FREE

建立 App Service 方案後，Azure CLI 會顯示如下所示的資訊：

{ 
  "adminSiteName": null,
  "appServicePlanName": "myAppServicePlan",
  "geoRegion": "West Europe",
  "hostingEnvironmentProfile": null,
  "id": "/subscriptions/0000-0000/resourceGroups/myResourceGroup/providers/Microsoft.Web/serverfarms/myAppServicePlan",
  "kind": "app",
  "location": "West Europe",
  "maximumNumberOfWorkers": 1,
  "name": "myAppServicePlan",
  < JSON data removed for brevity. >
  "targetWorkerSizeId": 0,
  "type": "Microsoft.Web/serverfarms",
  "workerTierName": null
}

如需詳細資訊，請參閱管理 Azure 中的 App Service 方案。

建立 Web 應用程式

在 myAppServicePlan App Service 方案中建立 Azure Web 應用程式。

重要

如同金鑰保存庫，Azure Web 應用程式必須有唯一名稱。在下列範例中，請將 <your-webapp-name> 取代為您的 Web 應用程式名稱。

az webapp create --resource-group "myResourceGroup" --plan "myAppServicePlan" --name "<your-webapp-name>" --deployment-local-git

Web 應用程式建立後，Azure CLI 會顯示如下所示的輸出：

Local git is configured with url of 'https://<username>@<your-webapp-name>.scm.azurewebsites.net/<ayour-webapp-name>.git'
{
  "availabilityState": "Normal",
  "clientAffinityEnabled": true,
  "clientCertEnabled": false,
  "clientCertExclusionPaths": null,
  "cloningInfo": null,
  "containerSize": 0,
  "dailyMemoryTimeQuota": 0,
  "defaultHostName": "<your-webapp-name>.azurewebsites.net",
  "deploymentLocalGitUrl": "https://<username>@<your-webapp-name>.scm.azurewebsites.net/<your-webapp-name>.git",
  "enabled": true,
  < JSON data removed for brevity. >
}

Git 遠端的 URL 會顯示在 deploymentLocalGitUrl 屬性中，其格式為 https://<username>@<your-webapp-name>.scm.azurewebsites.net/<your-webapp-name>.git。要儲存此 URL。稍後您將需要此資訊。

現在設定您的 Web 應用程式，以從 main 分支進行部署：

 az webapp config appsettings set -g MyResourceGroup --name "<your-webapp-name>" --settings deployment_branch=main

使用下列命令移至您的新應用程式。請將 <your-webapp-name> 取代為您的應用程式名稱。

https://<your-webapp-name>.azurewebsites.net

您會看到新 Azure Web 應用程式的預設網頁。

部署您的本機應用程式

回到本機終端視窗，將 Azure 遠端新增至本機 Git 存放庫。在下列命令中，請將 <deploymentLocalGitUrl-from-create-step> 取代為您在建立 Web 應用程式一節中儲存的 Git 遠端 URL。

git remote add azure <deploymentLocalGitUrl-from-create-step>

使用下列命令推送到 Azure 遠端，以部署您的應用程式。當 Git 認證管理員提示您輸入認證時，請使用您在設定本機 Git 部署一節中建立的認證。

git push azure main

執行此命令可能需要幾分鐘的時間。命令執行時，會顯示如下所示的資訊：

Enumerating objects: 5, done.
Counting objects: 100% (5/5), done.
Compressing objects: 100% (3/3), done.
Writing objects: 100% (3/3), 285 bytes | 95.00 KiB/s, done.
Total 3 (delta 2), reused 0 (delta 0), pack-reused 0
remote: Deploy Async
remote: Updating branch 'main'.
remote: Updating submodules.
remote: Preparing deployment for commit id 'd6b54472f7'.
remote: Repository path is /home/site/repository
remote: Running oryx build...
remote: Build orchestrated by Microsoft Oryx, https://github.com/Microsoft/Oryx
remote: You can report issues at https://github.com/Microsoft/Oryx/issues
remote:
remote: Oryx Version      : 0.2.20200114.13, Commit: 204922f30f8e8d41f5241b8c218425ef89106d1d, ReleaseTagName: 20200114.13
remote: Build Operation ID: |imoMY2y77/s=.40ca2a87_
remote: Repository Commit : d6b54472f7e8e9fd885ffafaa64522e74cf370e1
.
.
.
remote: Deployment successful.
remote: Deployment Logs : 'https://<your-webapp-name>.scm.azurewebsites.net/newui/jsonviewer?view_url=/api/deployments/d6b54472f7e8e9fd885ffafaa64522e74cf370e1/log'
To https://<your-webapp-name>.scm.azurewebsites.net:443/<your-webapp-name>.git
   d87e6ca..d6b5447  main -> main

使用網頁瀏覽器移至 (或重新整理) 已部署的應用程式：

http://<your-webapp-name>.azurewebsites.net

您會看到您稍早造訪 http://localhost:5000 時看到的 "Hello World!" 訊息。

如需使用 Git 部署 Web 應用程式的詳細資訊，請參閱本機 Git 部署至 Azure App Service

設定 Web 應用程式以連線至 Key Vault

在本節中，您將設定對 Key Vault 的 Web 存取，並更新應用程式程式碼以從 Key Vault 擷取秘密。

建立並指派受控識別的存取權

在本教學課程中，我們將使用受控識別向 Key Vault 進行驗證。受控識別會自動管理應用程式認證。

為了建立應用程式的身分識別，請在 Azure CLI 中執行 az webapp-identity assign 命令：

az webapp identity assign --name "<your-webapp-name>" --resource-group "myResourceGroup"

命令會傳回此 JSON 程式碼片段：

{
  "principalId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "tenantId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "type": "SystemAssigned"
}

Azure CLI
Azure PowerShell

若要透過角色型存取控制 (RBAC) 將應用程式權限授與金鑰保存庫，請使用 Azure CLI 命令 az role assignment create 來指派角色。

az role assignment create --role "Key Vault Secrets User" --assignee "<app-id>" --scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.KeyVault/vaults/<your-unique-keyvault-name>"

若要透過角色型存取控制 (RBAC) 將應用程式權限授與金鑰保存庫，請使用 Azure PowerShell Cmdlet New-AzRoleAssignment 指派角色。

New-AzRoleAssignment -ObjectId "<app-id>" -RoleDefinitionName "Key Vault Secrets User" -Scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.KeyVault/vaults/<your-unique-keyvault-name>"

使用實際值取代 <app-id>、<subscription-id>、<resource-group-name> 和 <your-unique-keyvault-name>。 <app-id> 是您在 Microsoft Entra 中註冊之應用程式的應用程式 (用戶端) 識別碼。

修改應用程式以存取您的金鑰保存庫

在本教學課程中，您將使用 Azure Key Vault 秘密用戶端程式庫進行示範。您也可以使用 Azure Key Vault 憑證用戶端程式庫或 Azure Key Vault 金鑰用戶端程式庫。

安裝套件

在終端機視窗中，安裝適用於 .NET 的 Azure Key Vault 秘密用戶端程式庫，以及 Azure 身分識別用戶端程式庫套件：

dotnet add package Azure.Identity
dotnet add package Azure.Security.KeyVault.Secrets

更新程式碼

尋找並開啟 .NET 5.0 或更早版本的 Startup.cs 檔案，或 akvwebapp 專案中 .NET 6.0 的 Program.cs 檔案。

將以下幾行新增至標頭：

using Azure.Identity;
using Azure.Security.KeyVault.Secrets;
using Azure.Core;

在 app.UseEndpoints 呼叫 (.NET 5.0 或更早版本) 或 app.MapGet 呼叫 (.NET 6.0) 之前新增下列幾行，更新 URI 以反映金鑰保存庫的 vaultUri。此程式碼會使用 DefaultAzureCredential() 向 Key Vault 進行驗證，這會使用來自受控識別的權杖進行驗證。如需對 Key Vault 進行驗證的詳細資訊，請參閱開發人員指南。如果 Key Vault 正在進行節流處理，程式碼也會使用指數輪詢進行重試。如需 Key Vault 交易限制的詳細資訊，請參閱 Azure Key Vault 節流指引。

SecretClientOptions options = new SecretClientOptions()
    {
        Retry =
        {
            Delay= TimeSpan.FromSeconds(2),
            MaxDelay = TimeSpan.FromSeconds(16),
            MaxRetries = 5,
            Mode = RetryMode.Exponential
         }
    };
var client = new SecretClient(new Uri("https://<your-unique-key-vault-name>.vault.azure.net/"), new DefaultAzureCredential(),options);

KeyVaultSecret secret = client.GetSecret("<mySecret>");

string secretValue = secret.Value;

.NET 5.0 或更早版本

更新 await context.Response.WriteAsync("Hello World!"); 這一行，使其如以下這一行所示：

await context.Response.WriteAsync(secretValue);

.NET 6.0

更新 app.MapGet("/", () => "Hello World!"); 這一行，使其如以下這一行所示：

app.MapGet("/", () => secretValue);

請務必先儲存變更，再繼續進行下一個步驟。

重新部署 Web 應用程式

現在您已更新程式碼，接下來可以使用下列 Git 命令將其重新部署至 Azure：

git add .
git commit -m "Updated web app to access my key vault"
git push azure main

移至您已完成的 Web 應用程式

http://<your-webapp-name>.azurewebsites.net

在您先前看到 "Hello World!" 之處，現在應該會顯示秘密值。

共用方式為