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

Платформа удостоверений Майкрософт позволяет приложению использовать для проверки подлинности свои собственные учетные данные везде, где может использоваться секрет клиента, например в потоке предоставления учетных данных клиента 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 (здесь это Azure AD) согласно RFC 7519, разделу 4.1.3. В данном случае получатель — это сервер входа (login.microsoftonline.com).
exp 1601519414 Утверждение "exp" (время окончания срока действия) указывает время окончания срока действия или время, после которого маркер JWT НЕ ДОЛЖЕН приниматься в обработку. См. раздел 4.1.4 RFC 7519. Утверждение может быть использовано в течение установленного срока, поэтому не делайте его слишком большим (не более 5–10 мин после nbf). В настоящее время в Azure AD нет ограничений на длительность 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"

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

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

Передача файла сертификата

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

  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 Core с использованием платформы удостоверений Майкрософт на GitHub показано, как приложение использует собственные учетные данные для проверки подлинности. В нем также показано, как создать самозаверяющий сертификат с помощью командлета PowerShell New-SelfSignedCertificate. Вы также можете воспользоваться скриптами создания приложений для создания сертификатов, вычисления отпечатков и т. д.