Используйте секреты клиента с Microsoft. Identity.Web

Секрет клиента — это строковое значение, которое приложение использует для аутентификации при запросе токенов из платформа удостоверений Майкрософт. Microsoft. Identity.Web поддерживает секреты клиента как один из нескольких типов учетных данных для конфиденциальных клиентских приложений.

Это важно

Секреты клиента должны использоваться только в средах разработки и тестирования. Для рабочих нагрузок используйте сертификаты или учетные данные без сертификатов , такие как управляемые удостоверения или федеративные учетные данные удостоверения. Секреты клиента проще компрометировать, чем учетные данные на основе сертификатов и не могут быть ограничены определенными операциями.

Выберите тип учетных данных

Конфиденциальные клиентские приложения нуждаются в учетных данных для проверки подлинности с помощью платформа удостоверений Майкрософт. Microsoft. Identity.Web поддерживает следующие типы учетных данных с помощью раздела конфигурации ClientCredentials:

Тип учетных данных	Рекомендуемая среда	Уровень безопасности
Секрет клиента	Разработка, тестирование	Низкий
Сертификат	Тестирование, производственное	Высокий
Управляемая идентичность	Azure размещенной рабочей среде	Самый высокий
Федеративное удостоверение	CI/CD, Kubernetes	Высокий

Секреты клиента — это простые строки, зарегистрированные в вашем приложении в Microsoft Entra ID. Хотя они самый простой тип учетных данных для настройки, они также имеют значительные ограничения безопасности:

Они могут быть случайно обнаружены в исходных кодах, журналах или файлах конфигурации.
Они имеют дату окончания срока действия и должны быть повернуты вручную.
Они не предоставляют криптографическое подтверждение личности вызывающего, кроме как через владение секретом.

Настройка секрета клиента в appsettings.json

Чтобы настроить секрет клиента, добавьте ClientCredentials массив в AzureAd раздел appsettings.json файла:

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "YOUR_TENANT_ID",
    "ClientId": "YOUR_CLIENT_ID",
    "ClientCredentials": [
      {
        "SourceType": "ClientSecret",
        "ClientSecret": "YOUR_SECRET_VALUE"
      }
    ]
  }
}

Массив ClientCredentials поддерживает несколько записей. Microsoft.Identity.Web проверяет каждую учетную запись поочерёдно до тех пор, пока одна из них не сработает, что полезно для сценариев смены секретов.

Предупреждение

Никогда не фиксируйте настоящие значения секретов в системе контроля версий. Заполнитель YOUR_SECRET_VALUE в предыдущем примере должен быть заменен ссылкой на безопасное хранилище, как описано в следующих разделах.

Хранение секретов для разработки

В этом разделе описывается, как хранить секретные значения вне исходного кода во время локальной разработки.

.NET секреты пользователей

Рекомендуемый подход для хранения секретов во время локальной разработки — это средство диспетчера секретов. Секреты пользователей хранят конфиденциальные данные за пределами дерева проекта, что предотвращает случайные фиксации в системе управления версиями.

Инициализация секретов пользователей для проекта:
```
dotnet user-secrets init
```

Задайте значение секрета клиента:

dotnet user-secrets set "AzureAd:ClientCredentials:0:ClientSecret" "your-secret-value"

Убедитесь, что секрет сохранен:
```
dotnet user-secrets list
```

Секреты пользователей Development автоматически загружаются в указанной среде при использовании WebApplication.CreateBuilder() или Host.CreateDefaultBuilder().

Структура appsettings.json должна содержаться без фактического значения секрета:

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "YOUR_TENANT_ID",
    "ClientId": "YOUR_CLIENT_ID",
    "ClientCredentials": [
      {
        "SourceType": "ClientSecret"
      }
    ]
  }
}

Переменные среды

Можно также использовать переменные среды для предоставления секрета клиента. .NET конфигурация автоматически сопоставляет переменные среды, использующие разделитель __ (двойной символ подчеркивания) в иерархию конфигурации. Задайте переменную для оболочки:

PowerShell
Bash

$env:AzureAd__ClientCredentials__0__ClientSecret = "your-secret-value"

export AzureAd__ClientCredentials__0__ClientSecret="your-secret-value"

Переменные среды имеют приоритет над значениями appsettings.json, поэтому значение секрета в файле конфигурации может быть пустым или опущено.

Хранение секретов для более высоких сред

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

Добавление Azure Key Vault в качестве источника конфигурации

Установите необходимый пакет NuGet:

dotnet add package Azure.Extensions.AspNetCore.Configuration.Secrets

Сохраните секрет клиента в Azure Key Vault с именем, которое сопоставляется с путем конфигурации. Используйте -- (двойной дефис) в качестве разделителя:
```
az keyvault secret set \
  --vault-name "your-keyvault-name" \
  --name "AzureAd--ClientCredentials--0--ClientSecret" \
  --value "your-secret-value"
```
Добавьте Key Vault в качестве источника конфигурации в Program.cs. Следующий код регистрирует Key Vault, чтобы его секреты были доступны через стандартный API конфигурации:
```
var builder = WebApplication.CreateBuilder(args);

builder.Configuration.AddAzureKeyVault(
    new Uri("https://your-keyvault-name.vault.azure.net/"),
    new DefaultAzureCredential());
```

Имя секрета Key Vault AzureAd--ClientCredentials--0--ClientSecret сопоставляется автоматически с пути конфигурации AzureAd:ClientCredentials:0:ClientSecret.

Подсказка

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

Создание секрета клиента на портале Azure

Выполните следующие действия, чтобы зарегистрировать секрет клиента для приложения в Microsoft Entra ID:

Войдите в Центр администрирования Microsoft Entra.
Перейдите к Identity>Applications>Регистрация приложений.
Выберите приложение из списка.
В меню слева выберите сертификаты и секреты.
Перейдите на вкладку секретов клиента .
Выберите новый секрет клиента.
В панели Добавление секрета клиента:
- Введите описание секрета (например, "Секрет разработки").
- Выберите длительность истечения срока действия. Доступные варианты включают 180 дней, 365 дней, 730 дней или настраиваемую дату.
- Нажмите кнопку "Добавить".
Скопируйте значение секрета немедленно. Значение отображается только один раз и не может быть извлечено после перехода с страницы.

Это важно

Запишите значение секрета в безопасном расположении сразу после создания. Microsoft Entra ID отображает значение только в момент создания. Если вы потеряете значение, необходимо создать новый секрет.

Управление истечением срока действия секрета и его ротацией

У конфиденциальных данных клиента есть максимальный срок действия, и они истекают в дату, указанную при создании. Запланируйте смену секретов, чтобы избежать сбоев приложений.

Мониторинг срока действия

Проверьте столбец "Срок действия" на странице "Сертификаты и секреты " регистрации приложения.
Настройте рекомендации Microsoft Entra для получения оповещений до истечения срока действия учетных данных.

Стратегия смены

Используйте ClientCredentials массив для поддержки ротации без прерывания работы.

Создайте новый секрет клиента на портале Azure.
Добавьте новый секрет в качестве дополнительной записи в ClientCredentials массив. Разместите новый секрет перед старым, чтобы он использовался в первую очередь.
```
{
  "AzureAd": {
    "ClientCredentials": [
      {
        "SourceType": "ClientSecret",
        "ClientSecret": "[NEW_SECRET_REFERENCE]"
      },
      {
        "SourceType": "ClientSecret",
        "ClientSecret": "[OLD_SECRET_REFERENCE]"
      }
    ]
  }
}
```
Разверните обновленную конфигурацию. Microsoft.Identity.Web пытается использовать первое средство аутентификации и переходит ко второму, если первое завершается ошибкой.
После подтверждения работы нового секрета удалите старый секрет из конфигурации и портала Azure.

Миграция на рабочие учетные данные

Перед развертыванием в рабочей среде перейдите из секретов клиента в более безопасный тип учетных данных:

Проверка подлинности на основе сертификатов

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

{
  "AzureAd": {
    "ClientCredentials": [
      {
        "SourceType": "KeyVault",
        "KeyVaultUrl": "https://your-keyvault-name.vault.azure.net",
        "KeyVaultCertificateName": "your-certificate-name"
      }
    ]
  }
}

Подробные инструкции см. в разделе Использование сертификатов с Microsoft. Identity.Web.

Управляемое удостоверение (без сертификата)

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

{
  "AzureAd": {
    "ClientCredentials": [
      {
        "SourceType": "SignedAssertionFromManagedIdentity",
        "ManagedIdentityClientId": "YOUR_MANAGED_IDENTITY_CLIENT_ID"
      }
    ]
  }
}

Подробные инструкции см. в разделе Certificateless authentication with Microsoft. Identity.Web.

Контрольный список действий по миграции

[ ] Создание или подготовка новых учетных данных (сертификат или управляемое удостоверение).
[ ] Обновите конфигурацию приложения, чтобы использовать новый тип учетных данных.
[ ] Проверьте новые учетные данные на тестовом стенде.
[ ] Развертывание в рабочей среде.
[ ] Удалите старый секрет клиента с портала Azure.
[ ] Проверьте правильность функций приложения без старого секрета.

Избегайте распространенных ошибок безопасности

Ознакомьтесь со следующими антишаблоны и их рекомендуемыми альтернативами при работе с секретами клиента:

Антипаттерн	Риск	Recommendation
Секреты жесткого программирования в исходном коде	Секрет, раскрытый в системе управления версиями	Используйте секреты пользователей, переменные среды или Key Vault
Фиксация `appsettings.Development.json` с помощью секретов	Секрет, предоставляемый всем пользователям с доступом к репозиторию	Добавьте файл в `.gitignore`, а затем используйте секреты пользователей.
Обмен секретами между средами	Скомпрометированный секрет разработчика раскрывает данные в рабочей среде	Использование уникальных секретов для каждой среды
Использование секретов в рабочей среде	Более высокий риск кражи учетных данных	Переходите на использование сертификатов или управляемых удостоверений
Создание секретов без плана окончания срока действия	Сбой приложения при истечении срока действия секрета	Установка напоминаний о истечении срока действия и реализация смены
Логирование конфиденциальных данных	Секрет был выявлен в журналах	Никогда не регистрируйте значения учетных данных; регистрируйте только тип источника.
Хранение секретов в файлах обычного текста на серверах	Секрет, предоставляемый любому пользователю с доступом к серверу	Используйте переменные среды или Key Vault

Устранение распространенных ошибок

В этом разделе рассматриваются часто возникающие ошибки при настройке секретов клиента.

Недопустимый секрет клиента

Ошибка:AADSTS7000215: Invalid client secret provided.

Возможные причины:

Значение секрета было скопировано неправильно. Значения секретов могут содержать специальные символы, которые усечены во время операций копирования и вставки.
Секрет был создан для другой регистрации приложения, чем та, что настроена в ClientId.
Путь конфигурации неверен, и приложение не считывает секретное значение.

Резолюция:

Создайте новый секрет клиента на портале Azure и тщательно скопируйте полное значение.
Проверьте, что ClientId и TenantId в вашей конфигурации соответствуют регистрации приложения, в которой был создан секрет.

Добавьте точку останова или лог-запись, чтобы проверить правильность загрузки конфигурации.

// For debugging only — remove before committing
var config = builder.Configuration.GetSection("AzureAd:ClientCredentials:0:ClientSecret").Value;
Console.WriteLine($"Secret loaded: {!string.IsNullOrEmpty(config)}");

Секрет клиента с истекшим сроком действия

Ошибка:AADSTS7000222: The provided client secret keys for app '{app-id}' are expired.

Резолюция:

Перейдите к регистрации приложения в Центр администрирования Microsoft Entra.
Проверьте дату окончания срока действия в разделе "Сертификаты и секреты>клиента".
Создайте секрет и обновите конфигурацию приложения.
Удалите секрет с истекшим сроком действия на портале.

Секрет не найден в конфигурации

Симптом: Приложение выдает NullReferenceException или не выполняет проверку подлинности, так как значение секрета равно null.

Возможные причины:

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

Резолюция:

Убедитесь, что пользовательские секреты инициализированы, проверив наличие показателя UserSecretsId в файле .csproj.
Убедитесь, что секрет задан путем выполнения dotnet user-secrets list.
Проверьте, соответствует ли путь конфигурации точно: AzureAd:ClientCredentials:0:ClientSecret
При работе вне среды разработки убедитесь, что в наличии соответствующий источник конфигурации (переменная среды или Key Vault).

Сертификаты с Microsoft.Identity.Web
Проверка подлинности без сертификата
Общие сведения о кэше маркеров
Безопасное хранилище секретов приложений в процессе разработки в ASP.NET Core
Поставщик конфигурации для Azure Key Vault в ASP.NET Core

Обратная связь

Были ли сведения на этой странице полезными?

Last updated on 2026-04-29

Используйте секреты клиента с Microsoft. Identity.Web

Выберите тип учетных данных

Настройка секрета клиента в appsettings.json

Хранение секретов для разработки

.NET секреты пользователей

Переменные среды

Хранение секретов для более высоких сред

Добавление Azure Key Vault в качестве источника конфигурации

Создание секрета клиента на портале Azure

Управление истечением срока действия секрета и его ротацией

Мониторинг срока действия

Стратегия смены

Миграция на рабочие учетные данные

Проверка подлинности на основе сертификатов

Управляемое удостоверение (без сертификата)

Контрольный список действий по миграции

Избегайте распространенных ошибок безопасности

Устранение распространенных ошибок

Недопустимый секрет клиента

Секрет клиента с истекшим сроком действия

Секрет не найден в конфигурации

Связанный контент

Обратная связь

Дополнительные ресурсы