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

  • Статья

Маркеры доступа — это веб-маркеры JSON (JWT). JWTs содержат следующие части:

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

Каждая часть разделена точкой (.) и отдельно закодирована в кодировке Base 64.

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

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

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

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

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

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

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

Пример значения JWT:
"groups":"src1"
"_claim_sources: "src1" : { "endpoint" : "https://graph.microsoft.com/v1.0/users/{userID}/getMemberObjects" }
sub Строка Субъект, связанный с маркером. Например, пользователь приложения. Это значение неизменяемо, не переназначьте или повторно используете. Тема — это попарный идентификатор, уникальный для определенного идентификатора приложения. Если один пользователь войдет в два приложения с помощью двух разных идентификаторов клиента, эти приложения получают два разных значения в утверждении субъекта. Использование двух разных значений зависит от архитектуры и требований к конфиденциальности. См. также 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 Строка Утверждение идентификатора маркера, эквивалентное jti в спецификации JWT. Уникальный идентификатор маркера с учетом регистра.
rh Непрозрачная строка Внутреннее утверждение, используемое Azure для повторной проверки маркеров. Ресурсы не должны использовать это утверждение.
ver Строка со значением 1.0 или 2.0 Обозначает номер версии маркера доступа.
xms_cc Массив строк в формате JSON Указывает, может ли клиентское приложение, полученное маркером, обрабатывать проблемы с утверждениями. Он часто используется вместе с утверждением acrs. Это утверждение обычно используется в сценариях условного доступа и непрерывной оценки доступа. Сервер ресурсов или приложение службы, выданное маркером для управления наличием этого утверждения в маркере. Значение cp1 маркера доступа — это достоверный способ определить, что клиентское приложение может обрабатывать вызов утверждений. Дополнительные сведения см. в разделе "Проблемы утверждений", "Запросы утверждений" и возможности клиента.

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

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

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

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

Примечание.

Возвращенный URL-адрес будет URL-адресом Графа Azure AD (т. е. graph.windows.net). Вместо того чтобы полагаться на этот URL-адрес, службы должны вместо этого использовать idtyp необязательное утверждение (которое определяет, является ли маркер приложением или маркером приложения+пользователя) для создания URL-адреса Microsoft Graph для запроса полного списка групп.

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

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

Утверждение Формат Description
ipaddr Строка IP-адрес, с которого пользователь прошел аутентификацию.
onprem_sid Строка в формате SID В тех случаях, когда пользователь использует локальную аутентификацию, это утверждение содержит его идентификатор безопасности. Используйте это утверждение для авторизации в приложениях прежних версий.
pwd_exp int, метка времени Unix Указывает, когда истекает срок действия пароля пользователя.
pwd_url Строка URL-адрес, в котором пользователи могут сбросить пароль.
in_corp boolean Посылает сигнал, если клиент входит в корпоративную сеть.
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 Указывает, что проверка подлинности не завершена.

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