Руководство. Использование ссылок Key Vault в приложении ASP.NET Core

  • Статья

В этом учебнике вы узнаете, как использовать службу "Конфигурация приложений Azure" с Azure Key Vault. Конфигурация приложений Azure и Key Vault — это дополняющие службы, которые используются параллельно в большинстве развертываний приложений.

Служба "Конфигурация приложений Azure" упрощает их использование, позволяя создавать ключи, ссылающиеся на значения, хранящиеся в Key Vault. Когда служба "Конфигурация приложений Azure" создает такие ключи, она сохраняет URI значений Key Vault, а не сами значения.

С помощью поставщика клиента "Конфигурация приложений Azure" ваше приложение получает ссылки на Key Vault так же, как и любые другие ключи, хранящиеся в службе "Конфигурация приложений Azure". В этом случае значения, хранящиеся в службе "Конфигурация приложений Azure", являются URI, которые ссылаются на значения в Key Vault. Это не значения или учетные данные Key Vault. Так как поставщик клиента распознает ключи как ссылки на Key Vault, для получения их значений он использует Key Vault.

Приложение отвечает за правильную проверку подлинности как в службе "Конфигурация приложений", так и в Key Vault. Две службы не обмениваются данными напрямую.

В этом учебнике показано, как можно реализовать ссылки на Key Vault в коде. При этом в качестве основы используется код веб-приложения, представленный в кратких руководствах. Прежде чем продолжить, ознакомьтесь со статьей Краткое руководство. Создание приложения ASP.NET Core с помощью службы "Конфигурация приложений Azure".

Вы можете выполнять шаги в этом учебнике с помощью любого редактора кода. Например, Visual Studio Code — это кроссплатформенный редактор кода, доступный для операционных систем Windows, macOS и Linux.

В этом руководстве описано следующее:

  • создание ключа службы "Конфигурация приложений Azure", который ссылается на значение, хранящееся в Key Vault;
  • доступ к значению этого ключа из веб-приложения ASP.NET Core.

Необходимые компоненты

Перед началом работы с этим руководством установите пакет SDK для .NET 6.0 или более поздней версии.

Если у вас еще нет подписки Azure, создайте бесплатную учетную запись Azure, прежде чем начинать работу.

Создание хранилища

  1. Выберите параметр Создать ресурс в верхнем левом углу окна портала Azure.

    Снимок экрана: вариант

  2. В поле поиска введите Key Vault и выберите Key Vault из раскрывающегося списка.

  3. В списке результатов выберите Key Vault слева.

  4. В разделе Хранилища ключей выберите Добавить.

  5. Справа в разделе Создать Key Vault введите приведенные ниже сведения.

    • Выберите Подписка, чтобы выбрать подписку.
    • В поле Группа ресурсов введите имя существующей группы ресурсов или щелкните Создать и введите имя группы ресурсов.
    • В поле Имя Key Vault укажите уникальное имя.
    • В раскрывающемся списке Регион выберите расположение.

  6. Для других свойств раздела создания Key Vault оставьте значения по умолчанию.

  7. Щелкните Просмотр и создание.

  8. Система проверит и отобразит введенные данные. Нажмите кнопку Создать.

На этом этапе доступ к этому новому хранилищу может получать только учетная запись Azure.

Добавление секрета в Key Vault

Чтобы добавить секрет в хранилище, вам просто нужно выполнить несколько дополнительных шагов. В этом случае мы добавим сообщение, которое можно использовать для проверки возвращения Key Vault. Сообщение называется Message, и в нем сохраняется значение "Hello from Key Vault".

  1. На странице свойств Key Vault выберите Секреты.
  2. Выберите Создать/импортировать.
  3. В области "Создание секрета" введите следующие значения:
    • Параметры отправки: введите вручную.
    • Имя: введите сообщение.
    • Значение. Введите Hello из Key Vault.
  4. Для других свойств раздела Создание секрета оставьте значения по умолчанию.
  5. Нажмите кнопку создания.

Добавление ссылки на Key Vault в службу "Конфигурация приложений Azure"

  1. Войдите на портал Azure. Щелкните Все ресурсы и выберите экземпляр хранилища "Конфигурация приложений Azure", который вы создали по инструкциям из краткого руководства.

  2. Выберите Обозреватель конфигураций.

  3. Выберите + Создать>Ссылка на хранилище ключей и укажите следующие значения:

    • Ключ. Выберите TestApp:Параметры:KeyVaultMessage.
    • Метка: оставьте это значение пустым.
    • Подписка, группа ресурсов и хранилище ключей. Введите значения, соответствующие значениям в хранилище ключей, созданном в предыдущем разделе.
    • Секрет. Выберите секрет с именем Message , созданное в предыдущем разделе.

Снимок экрана формы создания ссылки Key Vault

Обновление кода для использования ссылки Key Vault

  1. Добавьте ссылку на необходимые пакеты NuGet, выполнив следующую команду.

    dotnet add package Azure.Identity

  2. Откройте файл Program.cs и добавьте ссылки на приведенные ниже необходимые пакеты.

    using Azure.Identity;

  3. Используйте Конфигурация приложений путем AddAzureAppConfiguration вызова метода. Добавьте параметр ConfigureKeyVault и передайте правильные учетные данные в Key Vault с помощью метода SetCredential.

    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());
    });
});

    Совет

    Если у вас несколько хранилищ ключей, для всех них будут использоваться одни и те же учетные данные. Если для ваших хранилищ ключей требуются разные учетные данные, их можно задать с помощью методов Register или SetSecretResolver из класса AzureAppConfigurationKeyVaultOptions.

  4. При инициализации подключения к службе "Конфигурация приложений" устанавливается подключение к Key Vault путем вызова метода ConfigureKeyVault. После инициализации можно получить доступ к значениям ссылок на Key Vault так же, как и к значениям обычных ключей "Конфигурация приложений Azure".

    Чтобы увидеть этот процесс в действии, откройте файл 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>

    Вы получаете доступ к значению ссылки на Key Vault TestApp:Settings:KeyVaultMessage так же, как и к значению конфигурации TestApp:Settings:Message.

Предоставление приложению доступа к Key Vault

Конфигурация приложения Azure не будет обращаться к вашему хранилищу ключей. Ваше приложение будет читать из Key Vault напрямую, поэтому необходимо предоставить приложению доступ к секретам в хранилище ключей. Таким образом секрет всегда будет доступен в вашем приложении. Доступ можно предоставить с помощью политики доступа Key Vault или управления доступом на основе ролей Azure.

Вы используете DefaultAzureCredential в коде выше. Это объединенный маркер учетных данных, который автоматически пытается предоставить ряд типов учетных данных, например EnvironmentCredential, ManagedIdentityCredential, SharedTokenCacheCredential и VisualStudioCredential. Дополнительные сведения см. в разделе Класс DefaultAzureCredential. Можно явным образом заменить DefaultAzureCredential любым типом учетных данных. Однако DefaultAzureCredential позволяет использовать единый код, который выполняется как в локальной среде, так и в среде Azure. Например, вы предоставляете собственные учетные данные для доступа к хранилищу ключей. DefaultAzureCredential автоматически возвращается к использованию SharedTokenCacheCredential или VisualStudioCredential при локальной разработке в Visual Studio.

Кроме того, можно задать переменные среды AZURE_TENANT_ID, AZURE_CLIENT_ID и AZURE_CLIENT_SECRET, и DefaultAzureCredential будет использовать ваш секрет клиента посредством EnvironmentCredential для проверки подлинности в хранилище ключей. После развертывания приложения в службе Azure с управляемым удостоверением, например в Службе приложений Azure, Службе Azure Kubernetes или экземпляре контейнера Azure, вы предоставляете управляемому удостоверению службы Azure разрешение на доступ к своему хранилищу ключей. DefaultAzureCredential автоматически использует ManagedIdentityCredential, когда приложение выполняется в Azure. Вы можете использовать одно и то же управляемое удостоверение для проверки подлинности как в Конфигурации приложений, так и в Key Vault. Дополнительные сведения см. в статье Использование управляемых удостоверений для получения доступа к службе "Конфигурация приложений".

Создание и запуск приложения локально

  1. Чтобы создать приложение с помощью интерфейса командной строки .NET, выполните следующую команду в командной оболочке:

    dotnet build

  2. Когда создание завершится, запустите веб-приложение локально с помощью следующей команды:

    dotnet run

  3. Откройте окно браузера и перейдите по адресу http://localhost:5000, который является URL-адресом по умолчанию для веб-приложения, размещенного локально.

    Краткое руководство по запуску приложения, размещенного локально

Очистка ресурсов

Если вы не планируете в дальнейшем использовать ресурсы, созданные при работе с этой статьей, удалите созданную группу ресурсов, чтобы избежать расходов.

Внимание

Удаление группы ресурсов — процесс необратимый. Группа ресурсов и все содержащиеся в ней ресурсы удаляются без возможности восстановления. Будьте внимательны, чтобы случайно не удалить не те ресурсы или группу ресурсов. Если ресурсы для работы с этой статьей созданы в группе ресурсов, которая содержит другие нужные ресурсы, удалите каждый ресурс отдельно в соответствующей области ресурса, чтобы не удалять группу ресурсов.

  1. Войдите на портал Azure и выберитеГруппы ресурсов.
  2. Введите имя группы ресурсов в поле Фильтровать по имени.
  3. В списке результатов выберите имя группы ресурсов, чтобы просмотреть общие сведения.
  4. Выберите команду Удалить группу ресурсов.
  5. Подтвердите операцию удаления группы ресурсов. Введите имя группы ресурсов, которую необходимо удалить, и нажмите Удалить.

Через некоторое время группа ресурсов и все ее ресурсы будут удалены.

Следующие шаги

В этом руководстве вы создали ключ в Конфигурации приложений, который ссылается на секрет, хранящийся в Key Vault. Чтобы узнать, как автоматически перезагружать секреты и сертификаты из Key Vault, перейдите к следующему руководству:

Автоматическая перезагрузка секретов и сертификатов из Key Vault

Чтобы узнать, как использовать управляемое удостоверение для упрощения доступа к Конфигурации приложений и Key Vault, обратитесь к следующему руководству:

Руководство по интеграции с управляемыми удостоверениями Azure