教學課程：在 ASP.NET Core 應用程式中使用金鑰保存庫參考

  • 發行項

在此教學課程中，您將了解如何搭配 Azure Key Vault 一起使用 Azure 應用程式組態服務。 應用程式組態與 Key Vault 是互補服務，將在大部分的應用程式部署中並行使用。

應用程式組態可協助您一起使用這些服務，方法是建立參考 Key Vault 中所儲存之值的金鑰。 當應用程式組態建立此類金鑰時，它會儲存 Key Vault 值的 URI，而不是值本身。

您的應用程式會使用應用程式組態用戶端提供者擷取 Key Vault 參考，就像是儲存在應用程式組態中的其他任何金鑰一樣。 在此案例中，儲存在應用程式組態中的值是參考 Key Vault 中之值的 URI。 它們不是 Key Vault 值或認證。 用戶端提供者會將金鑰視為 Key Vault 參考，因此它會使用 Key Vault 擷取其值。

您的應用程式會負責適當地驗證應用程式組態和 Key Vault。 這兩個服務不會直接通訊。

此教學課程說明如何在程式碼中實作 Key Vault 參考。 本文會以快速入門中介紹的 Web 應用程式作為基礎。 繼續進行之前，請先完成使用應用程式設定建立 ASP.NET Core 應用程式。

您可以使用任何程式碼編輯器來進行本教學課程中的步驟。 例如，Visual Studio Code 是適用於 Windows、macOS 與 Linux 作業系統的跨平台程式碼編輯器。

在本教學課程中，您會了解如何：

  • 建立可參考 Key Vault 中儲存之值的應用程式組態金鑰。
  • 從 ASP.NET Core Web 應用程式存取此金鑰的值。

必要條件

開始本教學課程之前，請先安裝 .NET SDK 6.0 或更新版本。

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

建立保存庫

  1. 選取 Azure 入口網站左上角的 [建立資源] 選項：

    此螢幕快照顯示 Azure 入口網站 中的 [建立資源] 選項。

  2. 在搜尋方塊中，輸入 Key Vault，然後從下拉式清單中選取 [Key Vault]。

  3. 從結果清單，選取左側的 [金鑰保存庫]。

  4. 在 [金鑰保存庫] 中，選取 [新增]。

  5. 在 [建立金鑰保存庫] 的右側，提供下列資訊：

    • 選取 [訂用帳戶] 以選擇訂用帳戶。
    • 在 [資源群組] 下，輸入現有資源群組名稱，或選取 [建立新的名稱]，並輸入資源群組名稱。
    • 在 [金鑰保存庫名稱] 中，需要唯一的名稱。
    • 在 [區域] 下拉式清單中，選擇一個位置。

  6. 將其他 [建立金鑰保存庫] 選項維持為預設值。

  7. 按一下 [檢閱 + 建立]。

  8. 系統會驗證並顯示您輸入的資料。 按一下 [建立]。

此時，您的 Azure 帳戶是唯一獲得授權可存取此新保存庫的帳戶。

將祕密新增至 Key Vault

若要將祕密新增至保存庫，您只需要採取一些額外步驟。 在此案例中，請新增一則您可以用來測試 Key Vault 擷取的訊息。 此訊息稱為 Message，而您要將 "Hello from Key Vault" 的值儲存於其中。

  1. 從 Key Vault 屬性頁面，選取 [祕密]。
  2. 選取產生/匯入。
  3. 在 [建立祕密] 窗格中，輸入下列值：
    • 上傳選項：輸入 [手動]。
    • 名稱：輸入 [訊息]。
    • 值：輸入 Hello from Key Vault。
  4. 保留其他 [建立祕密] 屬性的預設值。
  5. 選取 建立。

將 Key Vault 參考新增至應用程式組態

  1. 登入 Azure 入口網站。 選取 [所有資源]，然後選取您在快速入門中建立的應用程式組態存放區執行個體。

  2. 選取 [組態總管]。

  3. 選取 [+ 建立]>[金鑰保存庫參考]，然後指定下列值：

    • 索引碼：選取 TestApp:Settings:KeyVaultMessage。
    • 標籤：將此值保留空白。
    • 訂用帳戶、資源群組與金鑰保存庫：輸入與您在上一節中建立的金鑰保存庫對應的值。
    • 祕密：選取您在上一節中所建立、名為 Message 的祕密。

建立新 金鑰保存庫 參考表單的螢幕快照

更新您的程式碼以使用 Key Vault 參考

  1. 執行下列命令，以新增對必要 NuGet 套件的參考：

    dotnet add package Azure.Identity

  2. 開啟 Program.cs，並加入對下列必要套件的參考：

    using Azure.Identity;

  3. 藉由呼叫 AddAzureAppConfiguration 方法，使用 應用程式組態。 請加入 ConfigureKeyVault 選項，並使用 SetCredential 方法將正確的認證傳遞給您的 Key Vault。

    var builder = WebApplication.CreateBuilder(args);

// Retrieve the connection string
string connectionString = builder.Configuration.GetConnectionString("AppConfig");

// Load configuration from Azure App Configuration
builder.Configuration.AddAzureAppConfiguration(options =>
{
    options.Connect(connectionString);

    options.ConfigureKeyVault(keyVaultOptions =>
    {
        keyVaultOptions.SetCredential(new DefaultAzureCredential());
    });
});

    提示

    如果您有多個 Key Vault，則所有的金鑰保存庫都會使用相同的認證。 如果您的 Key Vault 需要不同的認證，您可以使用 AzureAppConfigurationKeyVaultOptions 類別的 Register 或 SetSecretResolver 方法來加以設定。

  4. 當您初始化與應用程式組態的連線時，您藉由呼叫 ConfigureKeyVault 方法設定了與 Key Vault 的連線。 初始化之後，您就可以存取 Key Vault 參考的值，就像存取一般應用程式組態金鑰的值一樣。

    若要查看此程序的運作情形，請在 [檢視]>[主目錄] 資料夾中開啟 Index.cshtml。 以下列程式碼取代其內容：

    @page
@using Microsoft.Extensions.Configuration
@inject IConfiguration Configuration

<style>
    body {
        background-color: @Configuration["TestApp:Settings:BackgroundColor"]
    }
    h1 {
        color: @Configuration["TestApp:Settings:FontColor"];
        font-size: @Configuration["TestApp:Settings:FontSize"]px;
    }
</style>

<h1>@Configuration["TestApp:Settings:Message"]
    and @Configuration["TestApp:Settings:KeyVaultMessage"]</h1>

    您要以與組態值 TestApp:Settings:Message 相同的方式存取 Key Vault 參考的值 TestApp:Settings:KeyVaultMessage。

將您的應用程式存取權授與 Key Vault

Azure 應用程式組態不會存取您的金鑰保存庫。 您的應用程式會直接從金鑰保存庫讀取，因此您必須將金鑰保存庫的密碼權限授與應用程式。 如此一來，密碼會一律保留在您的應用程式中。 您可以使用 Key Vault 存取原則或 Azure 角色型存取控制來授與存取權。

您會在上述程式碼中使用 DefaultAzureCredential。 這是會自動嘗試許多認證類型的彙總權杖認證，例如 EnvironmentCredential、ManagedIdentityCredential、SharedTokenCacheCredential 和 VisualStudioCredential。 如需詳細資訊，請參閱 DefaultAzureCredential 類別。 您可以明確地將 DefaultAzureCredential 取代為任何認證類型。 不過，使用 DefaultAzureCredential 可讓您擁有在本機和 Azure 環境中執行的相同程式碼。 例如，您會將自身的認證存取權授與金鑰保存庫。 當您使用 Visual Studio 進行本機開發時，DefaultAzureCredential 會自動回復為 SharedTokenCacheCredential 或 VisualStudioCredential。

或者，您可以設定 AZURE_TENANT_ID、AZURE_CLIENT_ID 和 AZURE_CLIENT_SECRET 環境變數，且 DefaultAzureCredential 會透過 EnvironmentCredential 使用您擁有的用戶端密碼，以驗證您的金鑰保存庫。 將您的應用程式部署至已啟用受控識別的 Azure 服務 (例如 Azure App Service、Azure Kubernetes Service 或 Azure 容器執行個體) 之後，您會授與 Azure 服務的受控識別權限，以提供金鑰保存庫的存取權。 當您的應用程式在 Azure 中執行時，DefaultAzureCredential 會自動使用 ManagedIdentityCredential。 您可以使用相同的受控識別，來驗證應用程式組態和 Key Vault。 如需詳細資訊，請參閱如何使用受控識別來存取應用程式組態 (機器翻譯)。

於本機建置並執行應用程式

  1. 若要使用 .NET CLI 建置應用程式，請在命令殼層中執行下列命令：

    dotnet build

  2. 建置完成後，請使用下列命令在本機執行 Web 應用程式：

    dotnet run

  3. 開啟瀏覽器視窗，並前往 http://localhost:5000 (這是本機所裝載 Web 應用程式的預設 URL)。

    快速入門本機應用程式啟動

清除資源

如果您不想繼續使用本文中建立的資源，請刪除在此處建立的資源群組，以避免產生費用。

重要

刪除資源群組是無法回復的動作。 資源群組和其中的所有資源都將被永久刪除。 請確定您不會誤刪錯誤的資源群組或資源。 如果您是在包含需保留其他資源的資源群組內部，建立本文的資源，則可以從每個資源各自的窗格中個別刪除每個資源，而不必刪除整個資源群組。

  1. 登入 Azure 入口網站，然後選取 [資源群組]。
  2. 在 [依名稱篩選] 方塊中，輸入您資源群組的名稱。
  3. 在結果清單中，選取資源群組名稱以查看概觀。
  4. 選取 [刪除資源群組]。
  5. 系統將會要求您確認是否刪除資源群組。 輸入您資源群組的名稱以進行確認，然後選取 [刪除]。

不久後，系統便會刪除該資源群組及其所有的資源。

下一步

在此教學課程中，您建立了參考 Key Vault 中所儲存密碼的應用程式組態金鑰。 若要了解如何從 Key Vault 自動重新載入密碼和憑證，請繼續進行下一個教學課程：

自動從金鑰保存庫重新載入祕密和憑證

若要了解如何使用受控服務識別來簡化對應用程式組態和 Key Vault 的存取權，請參考下一個教學課程：

受控識別整合