Настройте расшифровку токенов в Microsoft.Identity.Web

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

По умолчанию платформа идентификации Microsoft выдает токены (токены идентификации, токены SAML) как подписанные, но незашифрованные JWT-типы. Любой посредник, перехватывающий маркер, может считывать утверждения этого маркера. Для приложений, которые обрабатывают конфиденциальные утверждения или работают в строгих средах соответствия требованиям, платформа удостоверений Майкрософт поддерживает шифрование token. Когда включена, платформа удостоверений шифрует полезные данные токена с помощью открытого ключа, зарегистрированного в вашем приложении. Только ваше приложение, которое содержит соответствующий закрытый ключ, может расшифровывать и считывать маркер.

Принцип работы шифрования токенов

Вы создаете сертификат с парой открытого и закрытого ключа.
Вы загружаете открытый ключ (файл .cer) в учетную запись Microsoft Entra ID.
Когда платформа удостоверений Майкрософт выдает маркер для приложения, он шифрует маркер с помощью открытого ключа.
Приложение использует закрытый ключ для расшифровки маркера перед обработкой утверждений.

Шифрование использует двухуровневую схему: полезная нагрузка токена шифруется с помощью ключа симметричного шифрования содержимого, который обернут (зашифрован) с помощью вашего открытого ключа. Microsoft Entra поддерживает алгоритмы упаковки ключей RSA-OAEP и RSA-OAEP-256.

Определение необходимости настройки расшифровки токена

Настройте расшифровку токена, если ваше приложение соответствует одному из следующих условий:

Получает зашифрованные токены SAML — корпоративные приложения, использующие единый вход на основе SAML, и требуют зашифрованных утверждений SAML по соответствию или нормативным причинам.
Получает зашифрованные маркеры идентификатора — веб-приложения, которые выбирают шифрование маркеров идентификатора для защиты конфиденциальных утверждений (членства в группах, пользовательских утверждений) от чтения при передаче.
Работает в средах с высоким уровнем безопасности — приложения в государственных, финансовых или медицинских сценариях, где конфиденциальность токенов требуется политикой.

Замечание

Шифрование маркеров является необязательным. Большинству приложений это не нужно. Включите шифрование маркеров только в том случае, если у вас есть определенное требование, так как она добавляет операционную сложность (управление сертификатами, смену) и затрудняет устранение неполадок.

Соответствие предварительным требованиям

Перед настройкой расшифровки токенов проверьте следующие требования:

An X.509 certificate with a private key — требуется сертификат в формате .pfx (PKCS#12) или хранящийся в расположении, доступном для приложения (Azure Key Vault, хранилища сертификатов или файловой системы). Для расшифровки маркеров требуется закрытый ключ.
Регистрация Приложения, настроенная для шифрования токенов — отправьте открытый ключ сертификата в регистрацию приложения в Microsoft Entra ID. См. раздел "Регистрация сертификата расшифровки " далее в этой статье.
Microsoft. Identity.Web 2.1.0 или более поздней версии — свойство конфигурации TokenDecryptionCredentials доступно в Microsoft. Identity.Web 2.1.0 и более поздних версий.

Настройте расшифровку токенов в appsettings.json

Microsoft. Identity.Web использует массив TokenDecryptionCredentials в разделе конфигурации AzureAd. Этот массив соответствует тому же формату описания учетных данных, что и ClientCredentials, поэтому вы можете загружать сертификаты расшифровки из Azure Key Vault, хранилища сертификатов, пути к файлу или строке в кодировке Base64.

Настройка базовой конфигурации

В следующем примере показана минимальная конфигурация для загрузки сертификата расшифровки из Azure Key Vault:

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

    "TokenDecryptionCredentials": [
      {
        "SourceType": "KeyVault",
        "KeyVaultUrl": "https://mykeyvault.vault.azure.net",
        "KeyVaultCertificateName": "MyCertificate"
      }
    ]
  }
}

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

Выбор источника учетных данных

Массив TokenDecryptionCredentials поддерживает те же исходные типы, что и ClientCredentials. В следующей таблице перечислены все варианты:

Тип источника	Описание	Обязательные свойства
Хранилище ключей	Загрузите сертификат из Azure Key Vault. Рекомендуется для эксплуатации в производственной среде.	`KeyVaultUrl`, `KeyVaultCertificateName`
StoreWithThumbprint	Загрузка из локального хранилища сертификатов с помощью отпечатка.	`CertificateStorePath`, `CertificateThumbprint`
StoreWithDistinguishedName	Загружается из локального хранилища сертификатов по различающемся имени субъекта.	`CertificateStorePath`, `CertificateDistinguishedName`
Путь	Загрузка из файла в файловой `.pfx` системе.	`CertificateDiskPath`, `CertificatePassword`
Base64Encoded	Загрузка из строки в кодировке `.pfx` Base64 (полезна для переменных среды).	`Base64EncodedValue`

Key Vault (рекомендуется для продакшна)

Следующая конфигурация загружает сертификат расшифровки из Azure Key Vault:

{
  "TokenDecryptionCredentials": [
    {
      "SourceType": "KeyVault",
      "KeyVaultUrl": "https://mykeyvault.vault.azure.net",
      "KeyVaultCertificateName": "TokenDecryptionCert"
    }
  ]
}

У управляемого удостоверения или субъекта-службы приложения должны быть разрешения Get и List для сертификатов Key Vault.

Хранилище сертификатов (Windows)

Следующая конфигурация загружает сертификат из хранилища сертификатов Windows по отпечатку:

{
  "TokenDecryptionCredentials": [
    {
      "SourceType": "StoreWithThumbprint",
      "CertificateStorePath": "CurrentUser/My",
      "CertificateThumbprint": "A1B2C3D4E5F6..."
    }
  ]
}

Путь к файлу

Следующая конфигурация загружает сертификат из .pfx файла на диске:

{
  "TokenDecryptionCredentials": [
    {
      "SourceType": "Path",
      "CertificateDiskPath": "/var/ssl/private/decrypt-cert.pfx",
      "CertificatePassword": "your-certificate-password"
    }
  ]
}

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

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

Кодировка Base64

Следующая конфигурация загружает сертификат из строки в кодировке Base64:

{
  "TokenDecryptionCredentials": [
    {
      "SourceType": "Base64Encoded",
      "Base64EncodedValue": "MIIJ..."
    }
  ]
}

Этот параметр полезен при внедрении сертификата с помощью переменной среды или секрета конвейера CI/CD.

Настройка нескольких сертификатов расшифровки

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

{
  "TokenDecryptionCredentials": [
    {
      "SourceType": "KeyVault",
      "KeyVaultUrl": "https://mykeyvault.vault.azure.net",
      "KeyVaultCertificateName": "TokenDecryptionCert-New"
    },
    {
      "SourceType": "KeyVault",
      "KeyVaultUrl": "https://mykeyvault.vault.azure.net",
      "KeyVaultCertificateName": "TokenDecryptionCert-Old"
    }
  ]
}

Регистрация сертификата расшифровки в Microsoft Entra ID

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

Войдите в Центр администрирования Microsoft Entra.
Перейдите к Identity>Applications>Регистрация приложений и выберите приложение.
Выберите Сертификаты и секреты>Сертификаты>Загрузить сертификат.
Отправьте файл (только открытый .cer ключ) сертификата расшифровки.
После отправки обратите внимание на значение отпечатка — оно должно соответствовать сертификату, который использует приложение.

Включите шифрование токенов для приложения

После отправки сертификата необходимо настроить приложение для получения зашифрованных маркеров. В настоящее время эта конфигурация доступна через Microsoft API Graph или PowerShell:

Using Microsoft Graph PowerShell:

# Get the key credential ID of the uploaded certificate
$app = Get-MgApplication -Filter "appId eq 'your-client-id'"
$keyId = ($app.KeyCredentials | Where-Object { $_.DisplayName -eq "CN=TokenDecryptionCert" }).KeyId

# Set the token encryption key ID
Update-MgApplication -ApplicationId $app.Id -BodyParameter @{
    "tokenEncryptionKeyId" = $keyId
}

Это важно

Свойство tokenEncryptionKeyId в объекте приложения определяет, какой загруженный сертификат Microsoft Entra используется для шифрования маркеров. Одновременно может быть активен только один ключ шифрования.

Смена сертификатов расшифровки

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

Шаги вращения

Создайте новый сертификат — создайте новый сертификат X.509 с закрытым ключом.
Добавьте новый сертификат в конфигурацию приложения— добавьте новый сертификат в TokenDecryptionCredentials массив вместе с существующим сертификатом. Сначала поместите новый сертификат в массив.
Загрузите новый открытый ключ — загрузите файл нового сертификата .cer в регистрацию приложения в Microsoft Entra.
Разверните приложение— разверните обновленную конфигурацию, чтобы приложение может расшифровать маркеры с помощью любого сертификата.
Переключите активный ключ шифрования— обновитеtokenEncryptionKeyId объект приложения, чтобы он указывал на новый сертификат keyId.
Убедитесь, что приложение успешно расшифровывает токены, зашифрованные новым сертификатом.
Удалите старый сертификат. После льготного периода (по крайней мере 24 часа, чтобы позволить кэшированным токенам истечь), удалите старый сертификат из регистрации и конфигурации вашего приложения.

Конфигурация во время вращения

В окне вращения TokenDecryptionCredentials должны содержаться оба сертификата.

{
  "TokenDecryptionCredentials": [
    {
      "SourceType": "KeyVault",
      "KeyVaultUrl": "https://mykeyvault.vault.azure.net",
      "KeyVaultCertificateName": "TokenDecryptionCert-2026"
    },
    {
      "SourceType": "KeyVault",
      "KeyVaultUrl": "https://mykeyvault.vault.azure.net",
      "KeyVaultCertificateName": "TokenDecryptionCert-2025"
    }
  ]
}

Подсказка

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

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

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

Ошибки расшифровки токенов

Симптом: Приложение выдает SecurityTokenDecryptionFailedException или возвращает ошибку 401/500 при обработке маркеров.

Распространенные причины:

Причина	Решение
Сертификат не найден	Убедитесь, что сертификат существует в настроенном расположении (Key Vault, хранилище или путь к файлу). Убедитесь, что у приложения есть необходимые разрешения для доступа к нему.
Неправильный сертификат	Убедитесь, что отпечаток сертификата в конфигурации приложения соответствует сертификату, отправленном в регистрацию приложения.
`tokenEncryptionKeyId` не задано	Задайте свойство `tokenEncryptionKeyId` объекта приложения в Microsoft Entra. Без этого свойства платформа идентификации не шифрует токены.

Отсутствует закрытый ключ

Симптом:CryptographicException: The certificate key is not accessible или InvalidOperationException: Certificate does not have a private key.

Причины и решения

Сертификат, экспортируемый без закрытого ключа , — повторно экспортируйте сертификат в .pfx формате и убедитесь, что во время экспорта включен закрытый ключ.
политика доступа Key Vault — при использовании Azure Key Vault убедитесь, что удостоверение приложения имеет разрешение Get на Certificates и Secrets. Закрытый ключ хранится в виде секрета в Key Vault.
Certificate store permissions — в Windows убедитесь, что удостоверение пула приложений или учетная запись службы имеют доступ на чтение к закрытому ключу. Используйте параметр Управление закрытыми ключами в оснастке MMC хранилища сертификатов.

Несоответствие алгоритма

Симптом:SecurityTokenDecryptionFailedException с сообщением, указывающим неподдерживаемый алгоритм.

Причины и решения

Неподдерживаемый тип ключа — Microsoft Entra поддерживает сертификаты RSA для шифрования токенов. Убедитесь, что сертификат использует пару ключей RSA (не EC/ECDSA).
Слишком маленький размер ключа — используйте по крайней мере 2048 бит. Ключи RSA меньше 2048 бит могут быть отклонены.
Algorithm не поддерживается — Microsoft Entra использует RSA-OAEP для упаковки ключей. Убедитесь, что ваш сертификат и инфраструктура приложений поддерживают этот алгоритм.

Зашифрованные токены не выдаются

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

Причины и решения

tokenEncryptionKeyId не настроено — необходимо явно задать это свойство через Microsoft Graph. Отправка сертификата в одиночку не является достаточной.
Срок действия сертификата истек в регистрации приложения . Убедитесь, что сертификат, отправленный в регистрацию приложения, не истек. При необходимости отправьте новый сертификат.
Маркеры доступа не шифруются. Шифрование маркеров применяется только к маркерам идентификатора и токенам SAML . Токены доступа из Microsoft Entra не шифруются вашим сертификатом.

Сравнение декодирования токенов и учетных данных клиента

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

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

{
  "AzureAd": {
    "ClientCredentials": [
      {
        "SourceType": "KeyVault",
        "KeyVaultUrl": "https://mykeyvault.vault.azure.net",
        "KeyVaultCertificateName": "AppAuthCert"
      }
    ],
    "TokenDecryptionCredentials": [
      {
        "SourceType": "KeyVault",
        "KeyVaultUrl": "https://mykeyvault.vault.azure.net",
        "KeyVaultCertificateName": "AppAuthCert"
      }
    ]
  }
}

Замечание

При использовании одного и того же сертификата в обоих целях сертификат должен использовать KeyEncipherment ключ и использовать спецификацию KeyExchange ключа (не Signature). Сертификаты, созданные с использованием KeySpec = Signature, работают для учетных данных клиента, но не работают для расшифровки токенов.

Следуйте лучшим практикам

При реализации расшифровки токена примените эти рекомендации.

Use Azure Key Vault — хранение сертификатов расшифровки в Key Vault для централизованного управления, контроля доступа и ведения журнала аудита.

Планирование смены — всегда есть стратегия смены перед развертыванием шифрования токенов. Включать как новые, так и старые сертификаты во время окна ротации.

Используйте ключи RSA 2048 или более крупные— убедитесь, что сертификаты используют ключи RSA по крайней мере 2048 бит для обеспечения надлежащей безопасности.

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

Тестирование в промежуточной среде — подтвердите шифрование и расшифровку токенов в непроизводственной среде перед включением в производственной среде.

Не храните закрытые ключи в системе контроля версий — используйте Key Vault, переменные среды или диспетчер секретов для хранения сертификатов.

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

Не включите шифрование токенов без сертификата расшифровки . Приложение не сможет обрабатывать маркеры, если он не может расшифровать их.

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

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

Last updated on 2026-04-19

Настройте расшифровку токенов в Microsoft.Identity.Web

Принцип работы шифрования токенов

Определение необходимости настройки расшифровки токена

Соответствие предварительным требованиям

Настройте расшифровку токенов в appsettings.json

Настройка базовой конфигурации

Выбор источника учетных данных

Key Vault (рекомендуется для продакшна)

Хранилище сертификатов (Windows)

Путь к файлу

Кодировка Base64

Настройка нескольких сертификатов расшифровки

Регистрация сертификата расшифровки в Microsoft Entra ID

Включите шифрование токенов для приложения

Смена сертификатов расшифровки

Шаги вращения

Конфигурация во время вращения

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

Ошибки расшифровки токенов

Отсутствует закрытый ключ

Несоответствие алгоритма

Зашифрованные токены не выдаются

Сравнение декодирования токенов и учетных данных клиента

Следуйте лучшим практикам

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

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

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