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

Маркер идентификатора — это базовое расширение OpenID Connect для OAuth 2.0. Маркеры идентификаторов выдаются сервером авторизации и содержат утверждения с информацией о пользователе. Их можно отправлять вместе с маркером доступа или вместо него. Сведения в маркерах идентификаторов позволяют клиенту убедиться, что пользователь — именно тот, за кого себя выдает. Маркеры идентификаторов предназначены для распознавания приложениями сторонних разработчиков. Маркеры идентификаторов не следует использовать в целях авторизации. Для авторизации используются маркеры доступа. Утверждения, предоставляемые маркерами идентификаторов, можно использовать для пользовательского интерфейса в приложении, в качестве ключей в базе данных и для обеспечения доступа к клиентскому приложению.

Предварительные требования

Прежде чем продолжать изучение данной статьи, будет полезно ознакомиться с этой:

Утверждения в маркере идентификатора

Маркеры идентификаторов — это маркеры JSON Web Token (JWT). Они состоят из заголовка, полезных данных и сигнатуры. Заголовок и сигнатуру можно использовать для проверки подлинности маркера, а полезные данные содержат сведения о пользователе, запрашиваемые клиентом. Маркеры идентификаторов версий 1.0 и 2.0 содержат разную информацию. Версия зависит от конечной точки, из которой поступил запрос. Существующие приложения, вероятно, используют конечную точку AAD (версия 1.0), однако новые приложения должны использовать конечную точку "Платформа удостоверений Майкрософт" (версия 2.0).

  • Конечная точка AAD (версия 1.0): https://login.microsoftonline.com/common/oauth2/authorize.
  • Конечная точка "Платформа удостоверений Майкрософт" (версия 2.0): https://login.microsoftonline.com/common/oauth2/v2.0/authorize.

Пример маркера идентификатора версии 1.0

eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6IjdfWnVmMXR2a3dMeFlhSFMzcTZsVWpVWUlHdyIsImtpZCI6IjdfWnVmMXR2a3dMeFlhSFMzcTZsVWpVWUlHdyJ9.eyJhdWQiOiJiMTRhNzUwNS05NmU5LTQ5MjctOTFlOC0wNjAxZDBmYzljYWEiLCJpc3MiOiJodHRwczovL3N0cy53aW5kb3dzLm5ldC9mYTE1ZDY5Mi1lOWM3LTQ0NjAtYTc0My0yOWYyOTU2ZmQ0MjkvIiwiaWF0IjoxNTM2Mjc1MTI0LCJuYmYiOjE1MzYyNzUxMjQsImV4cCI6MTUzNjI3OTAyNCwiYWlvIjoiQVhRQWkvOElBQUFBcXhzdUIrUjREMnJGUXFPRVRPNFlkWGJMRDlrWjh4ZlhhZGVBTTBRMk5rTlQ1aXpmZzN1d2JXU1hodVNTajZVVDVoeTJENldxQXBCNWpLQTZaZ1o5ay9TVTI3dVY5Y2V0WGZMT3RwTnR0Z2s1RGNCdGsrTExzdHovSmcrZ1lSbXY5YlVVNFhscGhUYzZDODZKbWoxRkN3PT0iLCJhbXIiOlsicnNhIl0sImVtYWlsIjoiYWJlbGlAbWljcm9zb2Z0LmNvbSIsImZhbWlseV9uYW1lIjoiTGluY29sbiIsImdpdmVuX25hbWUiOiJBYmUiLCJpZHAiOiJodHRwczovL3N0cy53aW5kb3dzLm5ldC83MmY5ODhiZi04NmYxLTQxYWYtOTFhYi0yZDdjZDAxMWRiNDcvIiwiaXBhZGRyIjoiMTMxLjEwNy4yMjIuMjIiLCJuYW1lIjoiYWJlbGkiLCJub25jZSI6IjEyMzUyMyIsIm9pZCI6IjA1ODMzYjZiLWFhMWQtNDJkNC05ZWMwLTFiMmJiOTE5NDQzOCIsInJoIjoiSSIsInN1YiI6IjVfSjlyU3NzOC1qdnRfSWN1NnVlUk5MOHhYYjhMRjRGc2dfS29vQzJSSlEiLCJ0aWQiOiJmYTE1ZDY5Mi1lOWM3LTQ0NjAtYTc0My0yOWYyOTU2ZmQ0MjkiLCJ1bmlxdWVfbmFtZSI6IkFiZUxpQG1pY3Jvc29mdC5jb20iLCJ1dGkiOiJMeGVfNDZHcVRrT3BHU2ZUbG40RUFBIiwidmVyIjoiMS4wIn0=.UJQrCA6qn2bXq57qzGX_-D3HcPHqBMOKDPx4su1yKRLNErVD8xkxJLNLVRdASHqEcpyDctbdHccu6DPpkq5f0ibcaQFhejQNcABidJCTz0Bb2AbdUCTqAzdt9pdgQvMBnVH1xk3SCM6d4BbT4BkLLj10ZLasX7vRknaSjE_C5DI7Fg4WrZPwOhII1dB0HEZ_qpNaYXEiy-o94UJ94zCr07GgrqMsfYQqFR7kn-mn68AjvLcgwSfZvyR_yIK75S_K37vC3QryQ7cNoafDe9upql_6pB2ybMVlgWPs_DmbJ8g0om-sPlwyn74Cc1tW3ze-Xptw_2uVdPgWyqfuWAfq6Q

Просмотрите этот пример маркера версии 1.0 в jwt.ms.

Пример маркера идентификатора версии 2.0

eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6IjFMVE16YWtpaGlSbGFfOHoyQkVKVlhlV01xbyJ9.eyJ2ZXIiOiIyLjAiLCJpc3MiOiJodHRwczovL2xvZ2luLm1pY3Jvc29mdG9ubGluZS5jb20vOTEyMjA0MGQtNmM2Ny00YzViLWIxMTItMzZhMzA0YjY2ZGFkL3YyLjAiLCJzdWIiOiJBQUFBQUFBQUFBQUFBQUFBQUFBQUFJa3pxRlZyU2FTYUZIeTc4MmJidGFRIiwiYXVkIjoiNmNiMDQwMTgtYTNmNS00NmE3LWI5OTUtOTQwYzc4ZjVhZWYzIiwiZXhwIjoxNTM2MzYxNDExLCJpYXQiOjE1MzYyNzQ3MTEsIm5iZiI6MTUzNjI3NDcxMSwibmFtZSI6IkFiZSBMaW5jb2xuIiwicHJlZmVycmVkX3VzZXJuYW1lIjoiQWJlTGlAbWljcm9zb2Z0LmNvbSIsIm9pZCI6IjAwMDAwMDAwLTAwMDAtMDAwMC02NmYzLTMzMzJlY2E3ZWE4MSIsInRpZCI6IjkxMjIwNDBkLTZjNjctNGM1Yi1iMTEyLTM2YTMwNGI2NmRhZCIsIm5vbmNlIjoiMTIzNTIzIiwiYWlvIjoiRGYyVVZYTDFpeCFsTUNXTVNPSkJjRmF0emNHZnZGR2hqS3Y4cTVnMHg3MzJkUjVNQjVCaXN2R1FPN1lXQnlqZDhpUURMcSFlR2JJRGFreXA1bW5PcmNkcUhlWVNubHRlcFFtUnA2QUlaOGpZIn0.1AFWW-Ck5nROwSlltm7GzZvDwUkqvhSQpm55TQsmVo9Y59cLhRXpvB8n-55HCr9Z6G_31_UbeUkoz612I2j_Sm9FFShSDDjoaLQr54CreGIJvjtmS3EkK9a7SJBbcpL1MpUtlfygow39tFjY7EVNW9plWUvRrTgVk7lYLprvfzw-CIqw3gHC-T7IK_m_xkr08INERBtaecwhTeN4chPC4W3jdmw_lIxzC48YoQ0dB1L9-ImX98Egypfrlbm0IBL5spFzL6JDZIRRJOu8vecJvj1mq-IUhGt0MacxX8jdxYLP-KUu2d9MbNKpCKJuZ7p8gwTL5B7NlUdh_dmSviPWrw

Просмотрите этот пример маркера версии 2.0 в jwt.ms.

Все приведенные ниже утверждения JWT отображаются в маркерах версий 1.0 и 2.0, если не указано иное.

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

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

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

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

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

Утверждение Формат Описание
aud Строка, GUID идентификатора приложения Определяет целевого получателя маркера. Аудитория — это идентификатор вашего приложения в id_tokens, назначенный приложению на портале Azure. Это значение должно быть проверено. Маркер должен быть отклонен, если он не соответствует идентификатору вашего приложения.
iss Строка, URI издателя Определяет издателя или "сервер авторизации", который конструирует и возвращает маркер. Кроме того, это утверждение определяет, в каком клиенте AAD пользователь прошел проверку подлинности. Если маркер был выпущен конечной точкой версии 2.0, универсальный код ресурса (URI) заканчивается значением /v2.0. GUID, который указывает, что пользователь является потребителем с учетной записью Майкрософт: 9188040d-6c67-4c5b-b112-36a304b66dad. Приложению также следует использовать часть утверждения, содержащую GUID, для ограничения списка клиентов, которым разрешено входить в приложение, если это применимо.
iat int, метка времени UNIX Значение Issued At (Выпущено в) показывает, когда произошла проверка подлинности этого маркера.
idp Строка, обычно — URI STS Фиксирует поставщика удостоверений, который проверил подлинность субъекта маркера. Это значение идентично значению утверждения издателя, за исключением случаев, когда учетная запись пользователя и издатель принадлежат разным клиентам (например, гости). Если утверждение отсутствует, это означает, что взамен можно использовать значение iss. Для пользовательских учетных записей, используемых в контексте организации (например, приглашение пользовательской учетной записи в клиент Azure AD), утверждение idp может быть live.com или URI STS, содержащим клиент учетной записи Microsoft 9188040d-6c67-4c5b-b112-36a304b66dad.
nbf int, метка времени UNIX Утверждение "nbf" (не ранее) определяет время, до которого маркер JWT НЕ ДОЛЖЕН приниматься в обработку.
exp int, метка времени UNIX Утверждение "exp" (время окончания срока действия) указывает время окончания срока действия или время, после которого маркер JWT НЕ ДОЛЖЕН приниматься в обработку. Важно отметить, что в определенных обстоятельствах ресурс может отклонить маркер до этого времени. Например, это происходит, если требуется изменение в процессе проверки подлинности или обнаружен отзыв маркера.
c_hash Строка Хэш-код включается в состав маркеров идентификации, только если маркер идентификации выдается вместе с кодом авторизации OAuth 2.0. Его можно использовать для проверки подлинности кода авторизации. Сведения о том, как выполнить эту проверку, см. в спецификации OpenID Connect.
at_hash Строка Хэш-маркер доступа входит в состав маркеров идентификаторов, только если маркер идентификатора выдан конечной точкой /authorize вместе с маркером доступа OAuth 2.0. Его можно использовать для проверки подлинности маркера доступа. Сведения о том, как выполнить эту проверку, см. в спецификации OpenID Connect. Это утверждение не возвращается для маркеров идентификаторов из конечной точки /token.
aio Непрозрачная строка Внутреннее утверждение, в котором Azure AD сохраняет данные для повторного использования маркеров. Можно пропустить.
preferred_username Строка Основное имя пользователя, представляющее пользователя. Это может быть адрес электронной почты, телефонный номер или универсальное имя пользователя без определенного формата. Его значение не является неизменяемым и может меняться с течением времени. Это изменяемое значение, поэтому его нельзя использовать для принятия решений об авторизации. Чтобы получить это утверждение, необходимо указать область profile.
email Строка Утверждение email по умолчанию указывается для гостевых учетных записей, у которых есть адрес электронной почты. Приложение может запрашивать утверждение электронной почты для управляемых пользователей (пользователи из того же клиента, что и ресурс) с помощью необязательного утвержденияemail. На конечной точке версии 2.0 приложение может также запросить область OpenID Connect email. Чтобы получить утверждение, вам не нужно запрашивать необязательное утверждение и область. Утверждение электронной почты поддерживает только адресуемую почту из профиля со сведениями о пользователе.
name Строка Утверждение name предоставляет удобное для восприятия значение, определяющее субъект маркера. Это значение не обязательно должно быть уникальным, оно изменяемое и предназначено только для отображения. Чтобы получить это утверждение, необходимо указать область profile.
nonce Строка Функция nonce соответствует параметру, включенному в исходный запрос или запрос авторизации в IDP. Если он не соответствует, приложению следует отклонить маркер.
oid Строка с идентификатором GUID Неизменяемый идентификатор объекта в системе идентификации Майкрософт. В данном случае это учетная запись пользователя. Этот идентификатор уникально идентифицирует пользователя в приложениях. Если один пользователь войдет в два различных приложения с помощью двух разных идентификаторов клиента, эти приложения получат одинаковое значение в утверждении oid. Microsoft Graph возвратит этот идентификатор в качестве свойства id указанной учетной записи. Так как oid позволяет нескольким приложениям сопоставлять пользователей, для получения этого утверждения необходимо указать область profile. Обратите внимание: если один пользователь существует в нескольких клиентах, его учетная запись в каждом клиенте будет содержать разные идентификаторы объекта. Такие учетные записи считаются разными, даже если пользователь входит в каждую из них с помощью одних и тех же учетных данных. Утверждение oid представляет собой GUID, и его нельзя использовать повторно.
roles Массив строк Набор ролей, назначенных пользователю, который входит в систему.
rh Непрозрачная строка Внутреннее утверждение, используемое Azure для повторной проверки маркеров. Можно пропустить.
sub Строка Субъект, в отношении которого маркер утверждает сведения, например данные о пользователе приложения. Это значение является неизменяемым и не может быть переназначено или повторно использовано. Субъект — это попарный идентификатор, который является уникальным для определенного идентификатора приложения. Если один пользователь войдет в два приложения с помощью двух разных идентификаторов клиента, эти приложения получат два разных значения в утверждении субъекта. Это может быть необходимо в зависимости от требований к архитектуре и конфиденциальности.
tid Строка с идентификатором GUID Представляет арендатор, в который входит пользователь. Для рабочих и учебных учетных записей значением GUID является неизменяемый идентификатор арендатора организации, в который входит пользователь. Для входа в арендатор личной учетной записи Майкрософт (такие службы, как Xbox, Teams for Life и Outlook) значение равно 9188040d-6c67-4c5b-b112-36a304b66dad. Чтобы получить это утверждение, ваше приложение должно запросить область profile.
unique_name Строка Предоставляет удобное для восприятия значение, которое идентифицирует субъект маркера. Это значение уникально в каждый момент, но так как адреса электронной почты и другие идентификаторы могут использоваться повторно, оно может вновь появляться для других учетных записей. Таким образом, это значение должно использоваться только для отображения. Выпущен только id_tokens версии 1.0.
uti Непрозрачная строка Внутреннее утверждение, используемое Azure для повторной проверки маркеров. Можно пропустить.
ver Строка со значением 1.0 или 2.0 Указывает номер версии маркера "id_token".
hasgroups Логическое Если это утверждение присутствует, оно всегда имеет значение true (истина). Это означает, что пользователь входит по крайней мере в одну группу. Используется вместо утверждения groups для JWT в потоках неявного предоставления разрешения, если полное утверждение groups расширило бы фрагмент URI за пределы ограничения длины URL-адреса (в настоящее время шесть или более групп). Указывает на то, что клиент должен использовать 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" }

Дополнительные сведения см. в разделе Утверждение избытка групп.

Использование утверждений для надежной идентификации пользователя (субъект и идентификатор объекта)

При идентификации пользователя (например, при его поиске в базе данных или при принятии решения о том, какие разрешения у него есть) очень важно использовать сведения, которые останутся постоянными и уникальными с течением времени. В устаревших приложениях иногда используются такие поля, как адрес электронной почты, номер телефона или имя субъекта-пользователя. Все эти данные могут меняться со временем, а также использоваться повторно. Например, сотрудник может изменить свое имя или получить адрес электронной почты, которым раньше пользовался человек, уже не являющийся сотрудником. Таким образом, очень важно, чтобы приложение не применяло для идентификации данные, которые пользователи могут прочитать, так как у кого-то может возникнуть желание изменить эти сведения. Вместо этого используйте утверждения, соответствующие стандарту OIDC, или утверждения расширения, предоставляемые корпорацией Майкрософт (sub и oid).

Чтобы правильно хранить информацию для каждого пользователя, применяйте только sub или только oid (они представляют собой идентификаторы GUID и потому уникальны), при необходимости используя tid для маршрутизации или сегментирования. Если необходимо использовать данные в разных службах, наилучшим вариантом будет oid + tid, так как все приложения получают одинаковые утверждения oid и tid для конкретного пользователя, действующего на данном арендаторе. Утверждение sub на платформе удостоверений Майкрософт является "парным": это уникальное значение, основанное на сочетании получателя маркера, клиента и пользователя. По этой причине два приложения, которые запрашивают маркеры идентификаторов для конкретного пользователя, получат для него разные утверждения sub, но одинаковые утверждения oid.

Примечание

Не используйте утверждение idp для хранения сведений о пользователе, пытаясь сопоставить пользователей между клиентами. Это сделать не удастся, так как утверждения oid sub для одного пользователя различаются в разных клиентах. Благодаря этому приложения не могут отслеживать пользователей в других клиентах.

В случаях, когда пользователь, находящийся в одном клиенте, проходит проверку подлинности в другом, он должен считаться абсолютно новым пользователем для службы. Ваши документы и привилегии в клиенте Contoso не должны применяться в клиенте Fabrikam. Это важно для предотвращения случайной утечки данных между клиентами и принудительного применения жизненных циклов данных. При удалении гостя из арендатора необходимо также удалить доступ к данным, которые гость создал на этом арендаторе.

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

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

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

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

По умолчанию маркер идентификатора действителен в течение одного часа, после чего клиент должен получить новый маркер идентификатора.

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

Проверка маркера идентификатора

Проверка маркера идентификатора аналогична первому этапу проверки маркера доступа. Клиент может проверить, был ли маркер незаконно изменен. Он также может проверить подлинность издателя, отправившего маркер. Поскольку маркеры идентификаторов ​​всегда являются маркерами JWT, существует множество библиотек для их проверки. Рекомендуем воспользоваться одной из них, а не создавать их самостоятельно. Обратите внимание: проверять маркеры идентификаторов должны только конфиденциальные клиенты (у которых есть секрет). Общедоступным приложениям (это код, выполняющийся полностью на устройстве или в сети, которые вы не контролируете, например в браузере или в домашней сети пользователя) нет смысла проверять маркер идентификатора. Это связано с тем, что злоумышленник может перехватить и изменить ключи, которые используются для проверки маркера.

Чтобы вручную проверить маркер, см. в разделе Проверка маркера доступа. Перечисленные ниже утверждения JWT должны быть проверены в маркере идентификатора после проверки сигнатуры маркера. Эти утверждения также можно проверить с помощью библиотеки проверки маркеров.

  • Метки времени. Метки времени iat, nbf, и exp следует соответственно выполнить до или после текущего момента времени.
  • Аудитория. Утверждение aud должно соответствовать идентификатору вашего приложения.
  • Nonce. Утверждение nonce в полезных данных должно соответствовать параметру nonce, переданному в конечную точку, или авторизации конечной точки во время первоначального запроса.

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