Учетные данные сертификата проверки подлинности приложения платформы удостоверений Майкрософт

Платформа удостоверений Майкрософт позволяет приложению использовать для проверки подлинности свои собственные учетные данные везде, где может использоваться секрет клиента, например в потоке предоставления учетных данных клиента OAuth 2.0 и потоке On-Behalf-Of (OBO).

Одной из форм учетных данных, которые приложение может использовать для аутентификации, является утверждение JSON Web Token (JWT), подписанное с помощью сертификата приложения. Описание доступно в спецификации OpenID Connect для параметра проверки подлинности клиента private_key_jwt.

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

Формат утверждения

Чтобы вычислить утверждение, можно использовать одну из множества библиотек JWT на удобном для вас языке (для этого в MSAL используется .WithCertificate()). Эти данные переносятся маркером в заголовке, утверждениях и сигнатуре.

Параметр Комментарий
alg Должен иметь значение RS256
typ Должен иметь значение JWT
x5t Отпечаток SHA-1 в кодировке Base64url для кодировки DER сертификата X.509. Например для хэша сертификата X.509 84E05C1D98BCE3A5421D225B140B36E86A3D5534 (Hex) утверждение x5t будет равно hOBcHZi846VCHSJbFAs26Go9VTQ (Base64url).

Утверждения (полезные данные)

Тип утверждения значение Описание
aud https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token Утверждение "aud" (аудитория) определяет получателей, для которым предназначен JWT (здесь идентификатор Microsoft Entra) См . раздел RFC 7519, раздел 4.1.3. В данном случае получатель — это сервер входа (login.microsoftonline.com).
exp 1601519414 Утверждение exp (время окончания срока действия) указывает время окончания срока действия или время, начиная с которого маркер JWT не должен приниматься в обработку. См. раздел 4.1.4 RFC 7519. Утверждение может быть использовано в течение установленного срока, поэтому не делайте его слишком большим (не более 5–10 мин после nbf). Идентификатор Microsoft Entra не помещает ограничения на exp время в данный момент.
iss {ClientID} Утверждение "iss" (издатель) обозначает субъект, который выдал JWT (в данном случае — клиентское приложение). Используйте идентификатор приложения GUID.
jti (идентификатор GUID) Утверждение jti (идентификатор маркера JWT) предоставляет уникальный идентификатор JWT. Значение идентификатора должно быть назначено таким образом, чтобы гарантировать, что существует незначимая вероятность того, что одно и то же значение будет случайно назначено другому объекту данных; если приложение использует несколько издателей, то столкновения должны быть запрещены среди значений, созданных различными издателями. Значение "jti" является строкой с учетом регистра. RFC 7519, раздел 4.1.7
nbf 1601519114 Утверждение "nbf" (не ранее) определяет время, до которого маркер JWT НЕ ДОЛЖЕН приниматься в обработку. RFC 7519, раздел 4.1.5 Допускается использование текущего времени.
sub {ClientID} Утверждение "sub" (субъект) обозначает субъект JWT, в данном случае — также ваше приложение. Используйте то же значение, что и для iss.
iat 1601519114 Утверждение iat (время выдачи) обозначает время, в которое был создан токен JWT. Это утверждение можно использовать для оценки возраста конкретного токена JWT. RFC 7519, раздел 4.1.5

Подпись

Подпись формируется путем применения сертификата, как описано в спецификации RFC 7519 на JSON Web Token.

Пример декодированного утверждения JWT

{
  "alg": "RS256",
  "typ": "JWT",
  "x5t": "gx8tGysyjcRqKjFPnd7RFwvwZI0"
}
.
{
  "aud": "https: //login.microsoftonline.com/contoso.onmicrosoft.com/oauth2/v2.0/token",
  "exp": 1484593341,
  "iss": "97e0a5b7-d745-40b6-94fe-5f77d35c6e05",
  "jti": "22b3bb26-e046-42df-9c96-65dbd72c1c81",
  "nbf": 1484592741,
  "sub": "97e0a5b7-d745-40b6-94fe-5f77d35c6e05"
}
.
"Gh95kHCOEGq5E_ArMBbDXhwKR577scxYaoJ1P{a lot of characters here}KKJDEg"

Пример закодированного утверждения JWT

Ниже приводится строка, которая является примером закодированного утверждения. Если внимательно ее изучить, то можно заметить, что она состоит из трех частей, разделенных точками (.).

  • В первом разделе закодирован заголовок.
  • Во втором разделе закодированы утверждения (полезные данные).
  • Последний раздел является сигнатурой, вычисленной с помощью сертификатов из содержимого первых двух разделов.
"eyJhbGciOiJSUzI1NiIsIng1dCI6Imd4OHRHeXN5amNScUtqRlBuZDdSRnd2d1pJMCJ9.eyJhdWQiOiJodHRwczpcL1wvbG9naW4ubWljcm9zb2Z0b25saW5lLmNvbVwvam1wcmlldXJob3RtYWlsLm9ubWljcm9zb2Z0LmNvbVwvb2F1dGgyXC90b2tlbiIsImV4cCI6MTQ4NDU5MzM0MSwiaXNzIjoiOTdlMGE1YjctZDc0NS00MGI2LTk0ZmUtNWY3N2QzNWM2ZTA1IiwianRpIjoiMjJiM2JiMjYtZTA0Ni00MmRmLTljOTYtNjVkYmQ3MmMxYzgxIiwibmJmIjoxNDg0NTkyNzQxLCJzdWIiOiI5N2UwYTViNy1kNzQ1LTQwYjYtOTRmZS01Zjc3ZDM1YzZlMDUifQ.
Gh95kHCOEGq5E_ArMBbDXhwKR577scxYaoJ1P{a lot of characters here}KKJDEg"

Зарегистрируйте сертификат на платформе удостоверений Майкрософт

Учетные данные сертификата можно связать с клиентским приложением в платформа удостоверений Майкрософт через Центр администрирования Microsoft Entra с помощью любого из следующих методов:

Отправка файла сертификата

На вкладке Регистрация приложений клиентского приложения:

  1. Выберите Сертификаты и секреты>Сертификаты.
  2. Нажмите Отправить сертификат и выберите файл сертификата для отправки.
  3. Нажмите кнопку Добавить. После передачи сертификата отображаются значения отпечатка сертификата, даты начала и истечения срока действия.

Обновление манифеста приложения

После получения сертификата вычислите следующие значения:

  • $base64Thumbprint — значение хэша сертификата в кодировке Base64.
  • $base64Value — значение необработанных данных сертификата в кодировке Base64.

В качестве ключа в манифесте приложения ($keyId) предоставьте идентификатор GUID.

При регистрации приложения Azure для клиентского приложения сделайте следующее.

  1. Щелкните Манифест, чтобы открыть манифест приложения.

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

    "keyCredentials": [
        {
            "customKeyIdentifier": "$base64Thumbprint",
            "keyId": "$keyid",
            "type": "AsymmetricX509Cert",
            "usage": "Verify",
            "value":  "$base64Value"
        }
    ]
    
  3. Сохраните изменения в манифесте приложения и передайте его на платформу удостоверений Майкрософт.

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

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

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

Параметр Стоимость Описание
client_assertion_type urn:ietf:params:oauth:client-assertion-type:jwt-bearer Это фиксированное значение, указывающее, что используются учетные данные сертификата.
client_assertion JWT Созданный выше JWT.

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

Библиотека MSAL.NET обслуживает этот сценарий в одной строке кода.

Консольное приложение управляющей программы .NET с помощью примера кода платформа удостоверений Майкрософт на GitHub показывает, как приложение использует собственные учетные данные для проверки подлинности. В нем также показано, как создать самозаверяющий сертификат с помощью командлета PowerShell New-SelfSignedCertificate. Вы также можете воспользоваться скриптами создания приложений для создания сертификатов, вычисления отпечатков и т. д.