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

Статья
04/10/2024

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

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

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

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

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

Параметр	Комментарий
`alg`	Должен быть PS256
`typ`	Должен иметь значение JWT
`x5t#s256`	Отпечаток SHA-256 в кодировке Base64url для кодировки DER сертификата X.509.

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

Тип утверждения	значение	Описание
`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. Используйте заполнение PSS.

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

{
  "alg": "PS256",
  "typ": "JWT",
  "x5t#sha256": "A1bC2dE3fH4iJ5kL6mN7oP8qR9sT0u"
}
.
{
  "aud": "https: //login.microsoftonline.com/contoso.onmicrosoft.com/oauth2/v2.0/token",
  "exp": 1484593341,
  "iss": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
  "jti": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
  "nbf": 1484592741,
  "sub": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb"
}
.
"A1bC2dE3fH4iJ5kL6mN7oP8qR9sT0u..."

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

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

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

"eyJhbGciOiJSUzI1NiIsIng1dCI6Imd4OHRHeXN5amNScUtqRlBuZDdSRnd2d1pJMCJ9.eyJhdWQiOiJodHRwczpcL1wvbG9naW4ubWljcm9zb2Z0b25saW5lLmNvbVwvam1wcmlldXJob3RtYWlsLm9ubWljcm9zb2Z0LmNvbVwvb2F1dGgyXC90b2tlbiIsImV4cCI6MTQ4NDU5MzM0MSwiaXNzIjoiOTdlMGE1YjctZDc0NS00MGI2LTk0ZmUtNWY3N2QzNWM2ZTA1IiwianRpIjoiMjJiM2JiMjYtZTA0Ni00MmRmLTljOTYtNjVkYmQ3MmMxYzgxIiwibmJmIjoxNDg0NTkyNzQxLCJzdWIiOiI5N2UwYTViNy1kNzQ1LTQwYjYtOTRmZS01Zjc3ZDM1YzZlMDUifQ.
Gh95kHCOEGq5E_ArMBbDXhwKR577scxYaoJ1P{a lot of characters here}KKJDEg"

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

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

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

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

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

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

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

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

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

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

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

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

"keyCredentials": [
    {
        "customKeyIdentifier": "$base64Thumbprint",
        "keyId": "$keyid",
        "type": "AsymmetricX509Cert",
        "usage": "Verify",
        "value":  "$base64Value"
    }
]

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

Свойство 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. Вы также можете воспользоваться скриптами создания приложений для создания сертификатов, вычисления отпечатков и т. д.

Поделиться через