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

Маркеры доступа позволяют клиентам безопасно вызывать защищенные веб-API, которые используют эти маркеры для проверки подлинности и авторизации. Согласно спецификации OAuth, маркеры доступа представляют собой непрозрачные строки без заданного формата: некоторые поставщики удостоверений используют идентификаторы GUID, а другие — зашифрованные BLOB-объекты. Платформа удостоверений Майкрософт использует различные форматы маркеров доступа в зависимости от конфигурации API, который принимает маркер. Для пользовательских API, которые зарегистрированы разработчиками на платформе удостоверений Майкрософт, доступны два формата веб-маркеров JSON (JWT) — версии 1.0 и 2.0. Для разработанных корпорацией Майкрософт API, например Microsoft Graph или API-интерфейсов в Azure, также доступны дополнительные собственные форматы. Эти собственные форматы включают зашифрованные маркеры, маркеры JWT или специальные похожие на JWT маркеры, которые не будут проверяться.

Клиенты должны обрабатывать маркеры как непрозрачные строки, так как их содержимое предназначено только для ресурса (интерфейса API). Только для проверки и отладки разработчики могут декодировать JWT через jwt.ms или другой аналогичный сайт. Но имейте в виду, что маркеры, которые вы получаете для API Майкрософт, не обязательно являются маркерами JWT и вы не всегда сможете их декодировать.

Для получения подробной информации о том, что находится внутри маркера доступа, нужно использовать данные ответа, которые возвращаются клиенту с этим маркером. Когда клиент запрашивает маркер доступа, платформа удостоверений Майкрософт также возвращает некоторые метаданные об этом маркере для приложения. Эти сведения включают срок действия маркера доступа и области, для которых он действителен. Благодаря этим данным приложение может выполнять интеллектуальное кэширование маркеров доступа, не анализируя сам маркер.

В разделах статьи ниже показано, как API может проверять и использовать утверждения в маркере доступа.

Примечание

Вся документация на этой странице, если не указано иное, относится только к маркерам, которые выпущены для зарегистрированных вами API. Эта информация не применима к маркерам, которые выпущены для принадлежащих Майкрософт API. Эти маркеры также нельзя использовать для проверки того, как платформа удостоверений Майкрософт будет выпускать маркеры для API, который вы создаете.

Форматы маркеров и владение

Версии 1.0 и 2.0

На платформе удостоверений Майкрософт доступны две версии маркеров доступа: 1.0 и 2.0. Эти версии определяют, какие утверждения входят в маркер. Это гарантирует, что веб-API сможет управлять тем, как выглядят маркеры. При регистрации веб-API по умолчанию выбирается версия 1.0 для приложений, предназначенных только для Azure AD, и версия 2.0 для приложений, которые поддерживают учетные записи потребителей. Это можно контролировать в манифесте приложения с помощью параметра accessTokenAcceptedVersion, где null и 1 соответствуют маркерам версии 1.0, а 2 — маркерам версии 2.0.

Для какого приложения предназначен маркер?

В запросе маркера доступа участвуют две стороны: клиент, который запрашивает маркер, и ресурс (API), который его принимает при вызове API. Утверждение aud в маркере указывает на ресурс, для которого предназначен это маркер (его аудиторию). Клиенты используют маркер, но не должны распознавать его или пытаться проанализировать. Ресурсы принимают маркер.

Платформа удостоверений Майкрософт поддерживает выпуск любой версии маркера из любой конечной точки — они не связаны между собой. Если для параметра ресурса accessTokenAcceptedVersion задано значение 2, то клиент, который вызывает конечную точку версии 1.0 для получения маркера для этого API, получит маркер доступа версии 2.0. Ресурсы всегда владеют своими маркерами с их утверждением aud и являются единственными приложениями, которые могут изменять данные этих маркеров. Поэтому изменение необязательных утверждений маркера доступа для клиента не изменяет маркер доступа, полученный при запросе для user.read, который принадлежит ресурсу Microsoft Graph.

Примеры маркеров

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

Версия 1.0

eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Imk2bEdrM0ZaenhSY1ViMkMzbkVRN3N5SEpsWSIsImtpZCI6Imk2bEdrM0ZaenhSY1ViMkMzbkVRN3N5SEpsWSJ9.eyJhdWQiOiJlZjFkYTlkNC1mZjc3LTRjM2UtYTAwNS04NDBjM2Y4MzA3NDUiLCJpc3MiOiJodHRwczovL3N0cy53aW5kb3dzLm5ldC9mYTE1ZDY5Mi1lOWM3LTQ0NjAtYTc0My0yOWYyOTUyMjIyOS8iLCJpYXQiOjE1MzcyMzMxMDYsIm5iZiI6MTUzNzIzMzEwNiwiZXhwIjoxNTM3MjM3MDA2LCJhY3IiOiIxIiwiYWlvIjoiQVhRQWkvOElBQUFBRm0rRS9RVEcrZ0ZuVnhMaldkdzhLKzYxQUdyU091TU1GNmViYU1qN1hPM0libUQzZkdtck95RCtOdlp5R24yVmFUL2tES1h3NE1JaHJnR1ZxNkJuOHdMWG9UMUxrSVorRnpRVmtKUFBMUU9WNEtjWHFTbENWUERTL0RpQ0RnRTIyMlRJbU12V05hRU1hVU9Uc0lHdlRRPT0iLCJhbXIiOlsid2lhIl0sImFwcGlkIjoiNzVkYmU3N2YtMTBhMy00ZTU5LTg1ZmQtOGMxMjc1NDRmMTdjIiwiYXBwaWRhY3IiOiIwIiwiZW1haWwiOiJBYmVMaUBtaWNyb3NvZnQuY29tIiwiZmFtaWx5X25hbWUiOiJMaW5jb2xuIiwiZ2l2ZW5fbmFtZSI6IkFiZSAoTVNGVCkiLCJpZHAiOiJodHRwczovL3N0cy53aW5kb3dzLm5ldC83MmY5ODhiZi04NmYxLTQxYWYtOTFhYi0yZDdjZDAxMjIyNDcvIiwiaXBhZGRyIjoiMjIyLjIyMi4yMjIuMjIiLCJuYW1lIjoiYWJlbGkiLCJvaWQiOiIwMjIyM2I2Yi1hYTFkLTQyZDQtOWVjMC0xYjJiYjkxOTQ0MzgiLCJyaCI6IkkiLCJzY3AiOiJ1c2VyX2ltcGVyc29uYXRpb24iLCJzdWIiOiJsM19yb0lTUVUyMjJiVUxTOXlpMmswWHBxcE9pTXo1SDNaQUNvMUdlWEEiLCJ0aWQiOiJmYTE1ZDY5Mi1lOWM3LTQ0NjAtYTc0My0yOWYyOTU2ZmQ0MjkiLCJ1bmlxdWVfbmFtZSI6ImFiZWxpQG1pY3Jvc29mdC5jb20iLCJ1dGkiOiJGVnNHeFlYSTMwLVR1aWt1dVVvRkFBIiwidmVyIjoiMS4wIn0.D3H6pMUtQnoJAGq6AHd

Изучите этот маркер версии 1.0 на сайте jwt.ms.

Версия 2.0

eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6Imk2bEdrM0ZaenhSY1ViMkMzbkVRN3N5SEpsWSJ9.eyJhdWQiOiI2ZTc0MTcyYi1iZTU2LTQ4NDMtOWZmNC1lNjZhMzliYjEyZTMiLCJpc3MiOiJodHRwczovL2xvZ2luLm1pY3Jvc29mdG9ubGluZS5jb20vNzJmOTg4YmYtODZmMS00MWFmLTkxYWItMmQ3Y2QwMTFkYjQ3L3YyLjAiLCJpYXQiOjE1MzcyMzEwNDgsIm5iZiI6MTUzNzIzMTA0OCwiZXhwIjoxNTM3MjM0OTQ4LCJhaW8iOiJBWFFBaS84SUFBQUF0QWFaTG8zQ2hNaWY2S09udHRSQjdlQnE0L0RjY1F6amNKR3hQWXkvQzNqRGFOR3hYZDZ3TklJVkdSZ2hOUm53SjFsT2NBbk5aY2p2a295ckZ4Q3R0djMzMTQwUmlvT0ZKNGJDQ0dWdW9DYWcxdU9UVDIyMjIyZ0h3TFBZUS91Zjc5UVgrMEtJaWpkcm1wNjlSY3R6bVE9PSIsImF6cCI6IjZlNzQxNzJiLWJlNTYtNDg0My05ZmY0LWU2NmEzOWJiMTJlMyIsImF6cGFjciI6IjAiLCJuYW1lIjoiQWJlIExpbmNvbG4iLCJvaWQiOiI2OTAyMjJiZS1mZjFhLTRkNTYtYWJkMS03ZTRmN2QzOGU0NzQiLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJhYmVsaUBtaWNyb3NvZnQuY29tIiwicmgiOiJJIiwic2NwIjoiYWNjZXNzX2FzX3VzZXIiLCJzdWIiOiJIS1pwZmFIeVdhZGVPb3VZbGl0anJJLUtmZlRtMjIyWDVyclYzeERxZktRIiwidGlkIjoiNzJmOTg4YmYtODZmMS00MWFmLTkxYWItMmQ3Y2QwMTFkYjQ3IiwidXRpIjoiZnFpQnFYTFBqMGVRYTgyUy1JWUZBQSIsInZlciI6IjIuMCJ9.pj4N-w_3Us9DrBLfpCt

Изучите этот маркер версии 2.0 на сайте jwt.ms.

Утверждения в маркерах доступа

JWT (веб-маркеры JSON) состоят из трех частей.

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

Эти части разделяются точками (.) и кодируются в Base64 по отдельности.

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

Некоторые утверждения помогают Azure AD защищать маркеры от повторного использования. Они отмечаются в описании как Opaque (Непрозрачные), то есть недоступные для широкого использования. Такие утверждения могут присутствовать или отсутствовать в маркере, и в любой момент без предварительного уведомления могут быть добавлены новые.

Утверждения заголовка

Утверждение Формат Описание
typ Строка — всегда JWT Указывает, что маркер имеет тип JWT.
alg Строка Обозначает алгоритм, с помощью которого был подписан маркер, например RS256.
kid Строка Указывает отпечаток открытого ключа, который можно использовать для проверки подписи маркера. Выпускаются в маркерах доступа версий 1.0 и 2.0.
x5t Строка Действует и указывается точно так же, как kid. x5t — устаревшее утверждение, которое выпускается только в маркерах доступа версии 1.0 для обеспечения совместимости.

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

Утверждение Формат Описание
aud Строка с URI идентификатора приложения или GUID Определяет целевого получателя маркера — его аудиторию. API должен проверить это значение и отклонить маркер при его несоответствии. В маркерах версии 2.0 всегда указывается идентификатор клиента API, а в маркерах версии 1.0 это может быть идентификатор клиента или URI ресурса, который использовался в запросе (в зависимости от того, как клиент запросил маркер).
iss Строка с URI службы маркеров безопасности Определяет службу маркеров безопасности (STS), которая создает и возвращает маркер, а также клиент Azure AD, в котором пользователь прошел аутентификацию. Если выданный маркер является маркером версии 2.0 (см. утверждение ver), URI заканчивается на /v2.0. GUID, который указывает, что пользователь является потребителем с учетной записью Майкрософт: 9188040d-6c67-4c5b-b112-36a304b66dad. При необходимости приложение может использовать часть утверждения, содержащую GUID, для ограничения списка клиентов, которым разрешено входить в приложение.
idp Строка, обычно — URI STS Фиксирует поставщика удостоверений, который проверил подлинность субъекта маркера. Это значение идентично значению утверждения издателя, за исключением случаев, когда учетная запись пользователя и издатель принадлежат разным клиентам (например, гости). Если утверждение отсутствует, это означает, что взамен можно использовать значение iss. Для пользовательских учетных записей, используемых в контексте организации (например, приглашение пользовательской учетной записи в клиент Azure AD), утверждение idp может быть live.com или URI STS, содержащим клиент учетной записи Microsoft 9188040d-6c67-4c5b-b112-36a304b66dad.
iat int, метка времени Unix Значение Issued At (Выпущено в) показывает, когда произошла проверка подлинности этого маркера.
nbf int, метка времени Unix Утверждение nbf (не ранее) определяет время, до которого маркер JWT не должен приниматься в обработку.
exp int, метка времени Unix Утверждение exp (время окончания срока действия) указывает время окончания срока действия или время, начиная с которого маркер JWT не должен приниматься в обработку. Важно отметить, что ресурс может отклонить маркер и раньше указанного времени, если, например, требуется изменить способ аутентификации или маркер был отозван.
aio Непрозрачная строка Внутреннее утверждение, в котором Azure AD сохраняет данные для повторного использования маркеров. Ресурсы не должны использовать это утверждение.
acr Строка со значением 0 или 1 Присутствует только в маркерах версии 1.0. Утверждение Authentication context class (Класс контекста аутентификации). Значение 0 означает, что аутентификация конечного пользователя не соответствовала требованиям ISO/IEC 29115.
amr Массив строк в формате JSON Присутствует только в маркерах версии 1.0. Указывает способ проверки подлинности субъекта токена. Дополнительные сведения см. в разделе об утверждении amr.
appid Строка с идентификатором GUID Присутствует только в маркерах версии 1.0. Идентификатор приложения клиента, использующего маркер. Приложение может действовать самостоятельно или от имени пользователя. Идентификатор приложения, как правило, представляет объект приложения, но может также представлять и объект субъекта-службы в Azure AD.
azp Строка с идентификатором GUID Только в маркерах версии 2.0. Заменяет appid. Идентификатор приложения клиента, использующего маркер. Приложение может действовать самостоятельно или от имени пользователя. Идентификатор приложения, как правило, представляет объект приложения, но может также представлять и объект субъекта-службы в Azure AD.
appidacr 0, 1 или 2 Присутствует только в маркерах версии 1.0. Указывает на способ проверки подлинности клиента. Для общедоступного клиента значение равно 0. При использовании идентификатора и секрета клиента значение равно 1. Если для аутентификации использовался сертификат клиента, значение равно 2.
azpacr 0, 1 или 2 Только в маркерах версии 2.0. Заменяет appidacr. Указывает на способ проверки подлинности клиента. Для общедоступного клиента значение равно 0. При использовании идентификатора и секрета клиента значение равно 1. Если для аутентификации использовался сертификат клиента, значение равно 2.
preferred_username Строка Основное имя пользователя, представляющее пользователя. Это может быть адрес электронной почты, телефонный номер или универсальное имя пользователя без определенного формата. Его значение не является неизменяемым и может меняться с течением времени. Так как это значение является изменяемым, его нельзя использовать для принятия решений об авторизации. Но его можно применять для подсказок имени пользователя и в качестве имени пользователя в понятном для человека интерфейсе. Чтобы получить это утверждение, необходимо указать область profile. Присутствует только в маркерах версии 2.0.
name Строка Предоставляет удобное для восприятия значение, которое идентифицирует субъект маркера. Это значение не обязательно должно быть уникальным. Оно изменяемое и предназначено только для отображения. Чтобы получить это утверждение, необходимо указать область profile.
scp Строка, список областей с разделителями-пробелами Набор областей, предоставляемых приложением, для которых клиентское приложение уже запросило (и получило) согласие. Приложению следует проверить, что здесь указаны допустимые предоставляемые приложением области, а затем принять решение об авторизации на основе значений для этих областей. Включаются только в маркеры пользователя.
roles Массив строк, список разрешений Набор разрешений, предоставляемых приложением, на вызов которых запрашивающему приложению или пользователю предоставлены разрешения. Для маркеров приложений это используется в потоке учетных данных клиента (v1.0, v2.0) вместо областей пользователя. Для маркеров пользователей он заполняется ролями, которым пользователь был назначен в целевом приложении.
wids Массив GUID RoleTemplateID Обозначает роли на уровне клиента, назначенные этому пользователю из раздела ролей на странице встроенных ролей Azure AD. Это утверждение настраивается на уровне приложения с использованием свойства groupMembershipClaims манифеста приложения. Для него необходимо задать значение ALL или DirectoryRole. Может отсутствовать в маркерах, полученных через неявный поток из-за проблем с длиной маркера.
groups Массив идентификаторов GUID в формате JSON Предоставляет идентификаторы объектов, представляющие членство субъекта в группах. Эти значения уникальны (см. раздел «Object ID»), их можно безопасно использовать для управления доступом, например для принудительной авторизации для доступа к ресурсу. Группы, входящие в утверждение groups, настраиваются для конкретного приложения с помощью свойства groupMembershipClaims в манифесте приложения. Если установлено значение null, исключаются все группы. Значение SecurityGroup подразумевает включение только групп безопасности Active Directory, а значение All — групп безопасности и списков рассылки Microsoft 365.

См. описание утверждения hasgroups ниже, чтобы получить сведения об использовании утверждения groups с неявным разрешением.
Для других потоков: если число групп, в которые входит пользователь, превышает лимит (150 для SAML и 200 для JWT), тогда избыточное утверждение будет добавлено к источникам утверждений, указывая на конечную точку Microsoft Graph, содержащую список групп для пользователя.
hasgroups Логическое Если он присутствует, всегда имеет значение true. Это обозначает, что пользователь входит как минимум в одну группу. Используется вместо утверждения groups для JWT в неявных потоках предоставления, если утверждение полной группы расширяет фрагмент URI за пределы ограничения длины URL-адреса (в настоящее время 6 или более групп). Указывает на то, что клиент должен использовать API Microsoft Graph для определения групп пользователя (https://graph.microsoft.com/v1.0/users/{userID}/getMemberObjects).
groups:src1 Объект JSON Для запросов маркеров, которые не ограничены по длине (см. hasgroups выше), но все еще слишком большие для маркеров, будет добавлена ссылка на полный список групп, в которые входит пользователь. Используется для JWT в качестве распределенного утверждения и для SAML в качестве нового утверждения вместо groups.

Пример значения JWT:
"groups":"src1"
"_claim_sources: "src1" : { "endpoint" : "https://graph.microsoft.com/v1.0/users/{userID}/getMemberObjects" }
sub Строка Субъект, в отношении которого маркер утверждает сведения, например данные о пользователе приложения. Это значение является неизменяемым и не может быть переназначено или повторно использовано. Это значение можно использовать для безопасных проверок авторизации, например, когда маркер используется для доступа к ресурсу, а также в качестве ключа в таблицах базы данных. Так как субъект всегда присутствует в выдаваемых Azure AD маркерах, мы советуем использовать это значение в системе авторизации общего назначения. Тем не менее субъект — это попарный идентификатор, который является уникальным для конкретного приложения. Если один пользователь войдет в два различных приложения с помощью двух разных идентификаторов клиента, эти приложения получат два разных значения в утверждении субъекта. Это может быть или не быть необходимым в зависимости от требований архитектуры и конфиденциальности. См. также утверждение oid (которое остается неизменным в разных приложениях внутри клиента).
oid Строка с идентификатором GUID Неизменяемый идентификатор для субъекта запроса — пользователя или субъекта-службы, удостоверение которого прошло проверку. В маркерах идентификации и маркерах для приложений и пользователей это идентификатор объекта пользователя. В маркерах только для приложений это идентификатор объекта вызывающего субъекта-службы. Его можно использовать для безопасных проверок авторизации, а также в качестве ключа в таблицах базы данных. Этот идентификатор однозначно определяет субъект в приложениях. Если один и тот же пользователь войдет в два различных приложения, эти приложения получат одинаковое значение в утверждении oid. Это означает, что oid может использоваться при выполнении запросов к веб-службам корпорации Майкрософт, например Microsoft Graph. Microsoft Graph возвратит этот идентификатор в качестве свойства id указанной учетной записи пользователя. Так как oid позволяет нескольким приложениям сопоставлять субъекты, для получения этого утверждения для пользователей необходимо указать область profile. Обратите внимание, что если один пользователь существует в нескольких клиентах, его учетная запись в каждом клиенте будет содержать разные идентификаторы объекта. Такие учетные записи считаются разными, даже если пользователь входит в каждую из них с помощью одних учетных данных.
tid Строка с идентификатором GUID Представляет арендатор, в который входит пользователь. Для рабочих и учебных учетных записей значением GUID является неизменяемый идентификатор арендатора организации, в который входит пользователь. Для входа в арендатор личной учетной записи Майкрософт (такие службы, как Xbox, Teams for Life и Outlook) значение равно 9188040d-6c67-4c5b-b112-36a304b66dad. Чтобы получить это утверждение, ваше приложение должно запросить область profile.
unique_name Строка Присутствует только в маркерах версии 1.0. Предоставляет удобное для восприятия значение, которое идентифицирует субъект маркера. Это значение не обязательно должно быть уникальным в пределах клиента. Оно используется только для отображения.
uti Непрозрачная строка Внутреннее утверждение, используемое Azure для повторной проверки маркеров. Ресурсы не должны использовать это утверждение.
rh Непрозрачная строка Внутреннее утверждение, используемое Azure для повторной проверки маркеров. Ресурсы не должны использовать это утверждение.
ver Строка со значением 1.0 или 2.0 Обозначает номер версии маркера доступа.

Утверждение избытка групп

Чтобы размер маркера не превышал ограничения на размер заголовка HTTP, Azure AD ограничивает количество идентификаторов объектов, включаемых в утверждение групп. Azure AD не выдает утверждение групп в маркере, если число групп, в которых состоит пользователь, выходит за предел избытка: 150 для маркеров SAML, 200 для маркеров JWT и 6 при выпуске через неявный поток. Вместо этого в маркер включается утверждение избытка, которое указывает приложению выполнить запрос к API Microsoft Graph для получения групп, в которых состоит пользователь.

{
  ...
  "_claim_names": {
   "groups": "src1"
    },
    {
  "_claim_sources": {
    "src1": {
        "endpoint":"[Url to get this user's group membership from]"
        }
       }
     }
  ...
}

Вы можете использовать BulkCreateGroups.ps1, предоставленный в папке Скрипты создания приложений, чтобы тестировать сценарии избытка.

Базовые утверждения в версии 1.0

Следующие утверждения (если они применимы) по умолчанию включаются в маркеры версии 1.0, но не включаются в маркеры версии 2.0. Если вы используете версию 2.0 и намерены использовать одно из этих утверждений, запросите его через механизм необязательных утверждений.

Утверждение Формат Описание
ipaddr Строка IP-адрес, с которого пользователь прошел аутентификацию.
onprem_sid Строка в формате SID В тех случаях, когда пользователь использует локальную аутентификацию, это утверждение содержит его идентификатор безопасности. Вы можете использовать onprem_sid для авторизации в приложениях прежних версий.
pwd_exp int, метка времени Unix Указывает, когда истекает срок действия пароля пользователя.
pwd_url Строка URL-адрес, на который можно направить пользователя для сброса пароля.
in_corp Логическое Посылает сигнал, если клиент входит в корпоративную сеть. В противном случае это утверждение не добавляется.
nickname Строка Дополнительное имя для пользователя, отдельное от имени или фамилии.
family_name Строка Указывает фамилию пользователя, которая определена в объекте пользователя.
given_name Строка Указывает личное имя пользователя, которое задано в объекте пользователя.
upn Строка Имя пользователя. Может содержать номер телефона, адрес электронной почты или любую неформатированную строку. Должно использоваться только для отображения и подсказки имени пользователя в сценариях повторной аутентификации.

Утверждение amr

Проверку подлинности удостоверений Майкрософт можно выполнять несколькими способами, с учетом особенностей приложения. Утверждение amr представляет собой массив с несколькими элементами, например ["mfa", "rsa", "pwd"], и используется при аутентификации с помощью пароля и приложения Authenticator.

Значение Описание
pwd Проверка пароля. Это может быть пароль учетной записи Майкрософт для пользователя или секрет клиента для приложения.
rsa Аутентификация выполнялась путем проверки ключа RSA, например с помощью приложения Microsoft Authenticator. Сюда же включается аутентификация по JWT с самозаверяющим сертификатом X509 службы.
otp Одноразовый секретный код, переданный по электронной почте или в текстовом сообщении.
fed Использовалось утверждение федеративной проверки подлинности (например, JWT или SAML).
wia Встроенная проверка подлинности Windows
mfa Использовалась многофакторная проверка подлинности. Если указано это утверждение, будут перечислены и другие методы проверки подлинности.
ngcmfa Эквивалентно mfa, используется для подготовки определенных расширенных типов учетных данных.
wiaormfa Пользователь использовал для аутентификации учетные данные Windows или MFA.
none Аутентификация не выполнялась.

Время существования маркера доступа

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

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

Проверка маркеров

Не все приложения должны проверять маркеры. Такая проверка должна происходить только в определенных сценариях:

  • Веб-API должны проверять маркеры доступа, отправленные клиентом. Они должны принимать только маркеры, которые содержат соответствующее значение для утверждения aud.
  • Прежде чем разрешить доступ к данным пользователя или установить сеанс, конфиденциальные веб-приложения, например ASP.NET Core, должны проверять маркеры идентификации, которые отправлены им через браузер пользователя в гибридном потоке.

Если ни один из описанных выше сценариев не применим, приложение не получит преимуществ от проверки маркера и может представлять угрозу для безопасности и надежности, если решения принимаются на основе допустимости маркера. Общедоступные клиенты, например собственные или одностраничные приложения, также не получают преимуществ от проверки маркеров: приложение напрямую взаимодействует с поставщиком удостоверений, поэтому защита SSL гарантирует допустимость маркеров.

API-интерфейсы и веб-приложения должны проверять только маркеры c утверждением aud, которое соответствует приложению. Другие ресурсы могут иметь собственные правила проверки маркеров. Например, маркеры для Microsoft Graph не будут проверяться согласно этим правилам, так как они представляют собой собственный формат. Проверка и прием маркеров, которые предназначены для другого ресурса, являются примером проблемы неумышленного посредника (confused deputy).

Если приложению требуется проверить параметр id_token или access_token в соответствии с приведенной выше информацией, оно должно сначала проверить подпись и издателя маркера по значениям в документе обнаружения OpenID. Например, версия документа для любых клиентов находится в https://login.microsoftonline.com/common/.well-known/openid-configuration.

Ниже предоставлена информация для тех, кто хочет разобраться в базовых процессах. ПО промежуточного слоя Azure AD содержит встроенные возможности для проверки маркеров доступа. Вы можете найти пример для выбранного вами языка в нашем наборе примеров. Для проверки JWT доступны несколько сторонних библиотек с открытым кодом. Среди них вы найдете как минимум один вариант практически для каждой платформы и языка. Дополнительные сведения и примеры кода см. в статье о библиотеках проверки подлинности в Azure AD.

Проверка подписи

Маркер JWT содержит три сегмента, разделенных символом . . Первый сегмент называется заголовком, второй — телом, а третий — подписью. Сегмент подписи можно использовать для проверки подлинности маркера, чтобы приложение доверяло ему.

Маркеры, выдаваемые Azure AD, подписываются при помощи стандартных отраслевых алгоритмов асимметричного шифрования, таких как RS256. Заголовок JWT содержит сведения о ключе и методе шифрования, используемых для подписания маркера.

{
  "typ": "JWT",
  "alg": "RS256",
  "x5t": "iBjL1Rcqzhiy4fpxIxdZqohM2Yk",
  "kid": "iBjL1Rcqzhiy4fpxIxdZqohM2Yk"
}

Утверждение alg определяет алгоритм, использованный для подписания маркера, а утверждение kid — конкретный открытый ключ, использованный для проверки маркера.

Azure AD может в любой момент времени подписать маркер идентификации с использованием любой пары открытого и закрытого ключей из определенного набора пар. Azure AD периодически изменяет возможный набор ключей, поэтому при создании приложения необходимо обеспечить автоматическую обработку подобных изменений ключей. Рекомендуем проверять наличие обновлений открытых ключей, которые использует служба Azure AD, каждые 24 часа.

Данные ключа подписи, необходимые для проверки подписи, можно найти в документе метаданных OpenID Connect по ссылке:

https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration

Совет

Попробуйте ввести этот URL-адрес в браузере.

Документ метаданных:

  • Это объект в формате JSON, который содержит несколько полезных блоков информации, таких как расположение различных конечных точек, необходимых для проверки подлинности OpenID Connect.
  • Он включает jwks_uri с информацией о расположении набора открытых ключей, которые соответствуют закрытым ключам, используемым для подписания маркеров. Документ веб-ключа JSON (JWK), который находится в jwks_uri, содержит все сведения об открытых ключах, используемые в конкретный момент времени. Формат JWK описан в RFC 7517. Приложение может использовать утверждение kid в заголовке маркера JWT, чтобы выбрать открытый ключ в этом документе, который соответствует закрытому ключу, использованному для подписания определенного маркера. Затем оно может выполнить проверку подписи с использованием правильного общедоступного ключа и указанного алгоритма.

Примечание

Мы рекомендуем использовать утверждение kid для проверки маркера. Маркеры версии 1.0 содержат утверждения x5t и kid, а маркеры версии 2.0 — только утверждение kid.

Выполнение проверки подписи выходит за рамки этого документа. Если вам требуется помощь в этом вопросе, воспользуйтесь всевозможными библиотеками с открытым исходным кодом. Но платформа удостоверений Майкрософт имеет одно расширение подписывания маркеров для стандартов — пользовательские ключи подписывания.

Если в приложении есть настраиваемые ключи подписывания в результате использования функции сопоставления утверждений, необходимо добавить параметр запроса appid, содержащий идентификатор приложения, чтобы получить jwks_uri, указывающий на сведения о ключе подписывания приложения, которые следует использовать для проверки. Например: https://login.microsoftonline.com/{tenant}/.well-known/openid-configuration?appid=6731de76-14a6-49ae-97bc-6eba6914391e содержит jwks_uri для https://login.microsoftonline.com/{tenant}/discovery/keys?appid=6731de76-14a6-49ae-97bc-6eba6914391e.

Авторизация на основе утверждений

Этот шаг зависит от бизнес-логики конкретного приложения. Ниже просто описаны несколько распространенных методов авторизации.

  • Используйте утверждение aud, чтобы убедиться, что пользователь собирался вызвать ваше приложение. Если в утверждении aud отсутствует идентификатор ресурса, отклоните его.
  • Используйте утверждение scp, чтобы убедиться, что пользователь предоставил вызывающему приложению разрешение на вызов API.
  • Используйте утверждения roles и wids, чтобы убедиться, что у самого пользователя есть разрешение на вызов API. Например, администратор может иметь разрешение на запись в ваш API, но у обычного пользователя такого права может не быть.
  • С помощью утверждения appid убедитесь, что вызывающий клиент имеет право вызывать API.
  • Убедитесь, что tid обозначает клиент, который имеет право вызывать этот API.
  • С помощью утверждения amr проверьте, прошел ли пользователь многофакторную проверку подлинности. Это требование нужно предварительно применять при помощи Условного доступа.
  • Если вы запросили в маркере доступа утверждения roles или groups, убедитесь, что пользователь входит в группу, которая может выполнять это действие.
    • В случае с маркерами, получаемых через неявный поток, для получения этих данных обычно нужно запрашивать Microsoft Graph, ведь их размер часто превышает допустимый для маркера.

Маркеры пользователя и приложения

Приложение может получать маркеры для пользователя (обычно рассматриваемый поток) или непосредственно из приложения (через поток учетных данных клиента). Маркеры для приложений указывают, что вызов поступает от самого приложения, а не по запросу пользователя. По большей части эти маркеры обрабатываются как обычно:

  • Используйте roles, чтобы просмотреть разрешения, предоставленные субъекту маркера.
  • Используйте oid или sub, чтобы проверить, является ли вызывающий субъект-служба ожидаемым.

Если необходимо, чтобы приложение различало маркеры доступа только для приложений и маркеры доступа для пользователей, используйте необязательное утверждение idtyp. Если в поле accessToken добавить утверждение idtyp и проверить значение app, то можно обнаружить маркеры доступа только для приложений. Маркеры идентификации и маркеры доступа для пользователей не будут содержать утверждение idtyp.

Отзыв маркеров

Маркеры обновления могут стать недействительными или могут быть отозваны в любое время по различным причинам. Эти причины делятся на две основные категории: время ожидания и отзыв.

Время ожидания для маркеров

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

  • MaxInactiveTime: если маркер обновления не использовался в течение времени, указанного в параметре MaxInactiveTime, этот маркер обновления считается недопустимым.
  • MaxSessionAge: если MaxAgeSessionMultiFactor или MaxAgeSessionSingleFactor имеют значения, отличные от значений по умолчанию (Until-revoked), то по истечении периода, заданного в параметре MaxAgeSession*, потребуется повторная аутентификация.
  • Примеры:
    • Для клиента параметр MaxInactiveTime имеет значение 5 дней. Пользователь провел неделю в отпуске, а значит, в течение 7 дней от него не поступало запросов к Azure AD на получение маркеров. При следующем запросе маркера от этого пользователя выяснится, что маркер обновления уже отозван, а значит, учетные данные нужно ввести заново.
    • Для важных приложений параметр MaxAgeSessionSingleFactor имеет значение 1 день. Если пользователь выполнит вход в понедельник, то по истечении 25 часов (во вторник) ему придется пройти проверку подлинности повторно.

Запрет доступа

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

Изменение Файл cookie на основе пароля Маркер на основе пароля Файл cookie без использования пароля Маркер без использования пароля Конфиденциальный маркер клиента
Срок действия пароля Остается активным Остается активным Остается активным Остается активным Остается активным
Пароль изменен пользователем Отменен Отменен Остается активным Остается активным Остается активным
Пользователь выполняет SSPR Отменен Отменен Остается активным Остается активным Остается активным
Администратор сбрасывает пароль Отменен Отменен Остается активным Остается активным Остается активным
Пользователь отменяет свои маркеры обновления с помощью PowerShell Отменен Отменен Отменен Отменен Отменен
Администратор отменяет все маркеры обновления для пользователя с помощью PowerShell Отменен Отменен Отменен Отменен Отменен
Единый выход (v 1.0, v 2.0) в Интернете Отменен Остается активным Отменен Остается активным Остается активным

Без использования пароля

Вход без использования пароля означает, что пользователь не вводит пароль, чтобы войти. Примеры входа без пароля:

  • Распознавание лица в Windows Hello
  • Ключ FIDO2
  • SMS
  • Голосовая связь
  • PIN-код

Ознакомьтесь с основными маркерами обновления.

Дальнейшие действия