Общие сведения о учетных данных для Microsoft. Identity.Web

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

Эта статья поможет вам понять доступные типы учетных данных, выбрать подходящий для вашего сценария и настроить учетные данные в приложении.

Почему выбор учетных данных имеет значение

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

Microsoft. Identity.Web предоставляет единую модель конфигурации, которая позволяет:

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

Поддерживаемые типы учетных данных

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

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

Учетные данные без сертификатов используют управляемое удостоверение Azure в сочетании с учетными данными федеративной идентификации (FIC) для аутентификации вашего приложения без необходимости управления секретами или сертификатами. Azure полностью обрабатывает жизненный цикл учетных данных.

Как это работает: Ваше приложение использует управляемое удостоверение для получения токена, который платформа идентификации Microsoft принимает в качестве доказательства удостоверения приложения через предварительно настроенное доверительное отношение федерации.

Идеально для: Производственных рабочих нагрузок в Azure.

Дополнительные сведения о проверке подлинности без сертификатов

Certificates

Сертификаты обеспечивают надежную асимметричную проверку подлинности на основе ключа. Ваше приложение удостоверяет свою личность, подписывая заявление с помощью закрытого ключа сертификата. Microsoft. Identity.Web может загружать сертификаты из нескольких источников:

  • Azure Key Vault — централизованное, управляемое хранилище сертификатов с политиками доступа.
  • Certificate Store — хранилище сертификатов Windows (CurrentUser или LocalMachine).
  • Путь к файлу — файл сертификата в формате PFX на диске.
  • В кодировке Base64 — сертификат, внедренный непосредственно в конфигурацию.

Лучше всего: Рабочие нагрузки, в которых учетные данные без сертификатов недоступны или гибридные среды.

Дополнительные сведения об учетных данных сертификата

Секреты клиента

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

Лучше всего: Только локальная разработка и тестирование.

Дополнительные сведения о секретах клиента

Выберите подходящий тип учетных данных

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

Is your application running on Azure?
├── Yes
│   ├── Can you use Managed Identity?
│   │   ├── Yes → Use certificateless credentials (recommended)
│   │   └── No → Use certificates from Azure Key Vault
└── No
    ├── Is this a production environment?
    │   ├── Yes → Use certificates (Key Vault, Certificate Store, or file path)
    │   └── No → Use client secrets for development/testing

Общие рекомендации

Следуйте этим принципам при выборе типа учетных данных.

  • Всегда предпочитайте учетные данные без сертификатов когда ваше приложение работает на Azure. Они полностью устраняют управление учетными данными.
  • Используйте сертификаты, если учетные данные без сертификатов недоступны. По возможности сохраните их в Azure Key Vault.
  • Ограничить использование секретов клиента только в средах разработки. Никогда не используйте секреты клиента в рабочих развертываниях.

Сравнение типов учетных данных

В следующей таблице приведены основные различия между типами учетных данных:

Характеристика Без сертификата (FIC + MI) Certificates Секреты клиента
Уровень безопасности Самый высокий Высокий Низкий
Риск раскрытия секрета Нет - нет секрета утечки Низкий уровень — защита закрытым ключом Высокая — можно скопировать строку
Требуется вращение Нет . Azure управляет жизненным циклом Да— до истечения срока действия сертификата Да - до истечения срока действия секрета
Сложность поворота Нет Средний — обновление сертификата, повторное развертывание Низкий приоритет — обновление строки, повторное развертывание
Настройка портала Azure Управляемое удостоверение + доверие FIC Отправка сертификата в регистрацию приложения Создание секрета при регистрации приложения
Подходящие среды Azure в промышленной эксплуатации Любая рабочая среда Только разработка и тестирование
Зависимость инфраструктуры вычислительный ресурс Azure Хранилище сертификатов или Key Vault Нет
Соблюдение закона Соответствует требованиям нулевого доверия Соответствует большинству платформ соответствия требованиям Может не соответствовать политикам безопасности

Настройка учетных данных в appsettings.json

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

Структура конфигурации

В следующем примере показана минимальная конфигурация с одними учетными данными без сертификата:

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "your-tenant-id",
    "ClientId": "your-client-id",

    "ClientCredentials": [
      {
        "SourceType": "SignedAssertionFromManagedIdentity",
        "ManagedIdentityClientId": "user-assigned-managed-identity-client-id"
      }
    ]
  }
}

Значения SourceType

Свойство SourceType соответствует перечислению CredentialSource и определяет, как Microsoft. Identity.Web загружает учетные данные:

Значение SourceType Тип учетных данных Описание
SignedAssertionFromManagedIdentity Без сертификата Использует управляемое удостоверение для получения подписанного утверждения. Рекомендуется для Azure рабочей среды.
KeyVault Сертификат Загружает сертификат из Azure Key Vault по URI.
StoreWithThumbprint Сертификат Загружает сертификат из хранилища сертификатов Windows по отпечатку.
StoreWithDistinguishedName Сертификат Загружает сертификат из хранилища сертификатов Windows по различительному имени субъекта сертификата.
Path Сертификат Загружает сертификат из PFX-файла на диске.
Base64Encoded Сертификат Загружает сертификат из строки в кодировке Base64 в конфигурации.
ClientSecret Секрет клиента Использует строку секрета клиента.
AutoDecryptKeys Расшифровка маркера Автоматически извлекает ключи для расшифровки зашифрованных маркеров.
SignedAssertionFilePath Федеративный Считывает подписанное заявление из указанного пути к файлу (для удостоверения идентичности рабочей нагрузки в Kubernetes).

Примеры удостоверяющих данных по типу

В следующих примерах показано, как настроить каждый тип учетных данных в appsettings.json, а также, где это возможно, в коде C#.

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

Используйте управляемое удостоверение, назначаемое пользователем, указав его идентификатор клиента:

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "your-tenant-id",
    "ClientId": "your-client-id",
    "ClientCredentials": [
      {
        "SourceType": "SignedAssertionFromManagedIdentity",
        "ManagedIdentityClientId": "user-assigned-managed-identity-client-id"
      }
    ]
  }
}

Для управляемого удостоверения, назначаемого ManagedIdentityClientId системой, опустите свойство:

{
  "AzureAd": {
    "ClientCredentials": [
      {
        "SourceType": "SignedAssertionFromManagedIdentity"
      }
    ]
  }
}

Сертификат из Azure Key Vault

Загрузите сертификат, хранящийся в Azure Key Vault, указав URL-адрес хранилища и имя сертификата:

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

Вы также можете использовать вспомогательный CredentialDescription метод в C#:

var credential = CredentialDescription.FromKeyVault(
    "https://your-keyvault.vault.azure.net",
    "your-certificate-name");

Сертификат из хранилища сертификатов

Загрузите сертификат из хранилища сертификатов Windows по отпечатку:

{
  "AzureAd": {
    "ClientCredentials": [
      {
        "SourceType": "StoreWithThumbprint",
        "CertificateThumbprint": "ABC123DEF456...",
        "CertificateStorePath": "CurrentUser/My"
      }
    ]
  }
}

Вы также можете использовать различающееся имя, что упрощает смену сертификатов, так как новый сертификат выбирается автоматически:

{
  "AzureAd": {
    "ClientCredentials": [
      {
        "SourceType": "StoreWithDistinguishedName",
        "CertificateDistinguishedName": "CN=YourAppCertificate",
        "CertificateStorePath": "CurrentUser/My"
      }
    ]
  }
}

В C#используйте вспомогательный метод:

// By thumbprint
var credential = CredentialDescription.FromCertificateStore(
    "CurrentUser/My",
    thumbprint: "ABC123DEF456...");

// By distinguished name (recommended for rotation)
var credential = CredentialDescription.FromCertificateStore(
    "CurrentUser/My",
    distinguishedName: "CN=YourAppCertificate");

Сертификат, полученный из пути к файлу

Загрузите сертификат из файла на .pfx диске:

{
  "AzureAd": {
    "ClientCredentials": [
      {
        "SourceType": "Path",
        "CertificateDiskPath": "/var/certs/app-cert.pfx",
        "CertificatePassword": "certificate-password"
      }
    ]
  }
}

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

Избегайте хранения паролей сертификатов непосредственно в appsettings.json. Используйте диспетчер секретов ASP.NET Core, переменные среды или Azure Key Vault для конфиденциальных значений.

Сертификат в кодировке Base64

Внедрение сертификата непосредственно в конфигурацию в виде строки в кодировке Base64:

{
  "AzureAd": {
    "ClientCredentials": [
      {
        "SourceType": "Base64Encoded",
        "Base64EncodedValue": "MIIKcQIBAzCCCi0..."
      }
    ]
  }
}

Секрет клиента

Укажите строку секрета клиента для разработки и тестирования:

{
  "AzureAd": {
    "ClientCredentials": [
      {
        "SourceType": "ClientSecret",
        "ClientSecret": "your-client-secret"
      }
    ]
  }
}

Предостережение

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

Использование нескольких учетных данных с резервным вариантом

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

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "your-tenant-id",
    "ClientId": "your-client-id",
    "ClientCredentials": [
      {
        "SourceType": "SignedAssertionFromManagedIdentity",
        "ManagedIdentityClientId": "your-managed-identity-client-id"
      },
      {
        "SourceType": "KeyVault",
        "KeyVaultUrl": "https://your-keyvault.vault.azure.net",
        "KeyVaultCertificateName": "your-certificate-name"
      },
      {
        "SourceType": "ClientSecret",
        "ClientSecret": "development-only-secret"
      }
    ]
  }
}

В этом примере:

  1. Приложение сначала пытается выполнить проверку подлинности без сертификата с помощью управляемого удостоверения (работает на Azure).
  2. Если управляемое удостоверение недоступно, используется сертификат из Хранилища ключей.
  3. В качестве последнего средства он использует секрет клиента (для локальной разработки).

Этот подход позволяет использовать один и тот же файл конфигурации в средах без изменений кода.

Настройка учетных данных в коде

Вы также можете программно настроить учетные данные в Program.cs или Startup.cs.

using Microsoft.Identity.Web;

builder.Services.AddMicrosoftIdentityWebAppAuthentication(builder.Configuration, "AzureAd")
    .EnableTokenAcquisitionToCallDownstreamApi()
    .AddDownstreamApi("MyApi", builder.Configuration.GetSection("MyApi"))
    .AddDistributedTokenCaches();

// Or configure credentials programmatically
builder.Services.Configure<MicrosoftIdentityOptions>(options =>
{
    options.ClientCredentials = new[]
    {
        new CredentialDescription
        {
            SourceType = CredentialSource.SignedAssertionFromManagedIdentity,
            ManagedIdentityClientId = "your-managed-identity-client-id"
        }
    };
});

Учетные данные расшифровки токенов

Помимо учетных данных клиента для проверки подлинности, Microsoft.Identity.Web также поддерживает учетные данные для расшифровки маркеров. Используйте учетные данные расшифровки маркеров, когда приложение получает зашифрованные маркеры и требует их расшифровки.

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

{
  "AzureAd": {
    "TokenDecryptionCredentials": [
      {
        "SourceType": "KeyVault",
        "KeyVaultUrl": "https://your-keyvault.vault.azure.net",
        "KeyVaultCertificateName": "token-decryption-cert"
      }
    ]
  }
}

Дополнительные сведения о расшифровке токенов

Лучшие практики

При настройке учетных данных для приложения следует учитывать следующие рекомендации:

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

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

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

Храните конфиденциальные значения за пределами файлов конфигурации. Используйте Azure Key Vault, переменные среды или диспетчер секретов ASP.NET Core для паролей сертификатов и секретов клиента. Не фиксируйте конфиденциальные значения в системе управления версиями.

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

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

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

  • Last updated on