Справочник по утверждениям маркера идентификатора

Статья
10/24/2023

Маркеры идентификаторов — это маркеры JSON Web Token (JWT). Маркеры идентификаторов версий 1.0 и 2.0 содержат разную информацию. Версия зависит от конечной точки, из которой поступил запрос. Хотя существующие приложения, скорее всего, используют конечную точку Azure AD версии 1.0, новые приложения должны использовать конечную точку версии 2.0.

Версия 1.0: https://login.microsoftonline.com/common/oauth2/authorize
v2.0: https://login.microsoftonline.com/common/oauth2/v2.0/authorize

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

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

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

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

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

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

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

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

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

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

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

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

Дополнительные сведения о маркерах идентификатора, используемых в идентификаторе Microsoft Entra.

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