Справочник по утверждениям маркера доступа
Маркеры доступа — это веб-маркеры 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. Для других потоков, если число групп, в которых пользователь находится, переходит более 150 для SAML и 200 для JWT, то идентификатор Microsoft Entra ID добавляет утверждение о превышении в источники утверждений. Источники утверждений указывают на конечную точку Microsoft Graph, содержащую список групп для пользователя. |
Эти значения можно использовать для управления доступом, таких как применение авторизации для доступа к ресурсу. |
hasgroups |
Логический | Если это утверждение присутствует (всегда имеет значение true), оно указывает, входит ли пользователь по крайней мере в одну группу. Указывает на то, что клиент должен использовать 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 маркера доступа — это достоверный способ определить, что клиентское приложение может обрабатывать вызов утверждений. Дополнительные сведения см. в разделе "Проблемы утверждений", "Запросы утверждений" и возможности клиента. |
Примечание.
groupsУтверждения rolesи scpwids утверждения не являются исчерпывающим списком того, как ресурс может авторизовать пользователя или приложения, а также не является исчерпывающим списком разрешений, предоставленных вызывающему объекту. Целевой ресурс может использовать другой метод для авторизации доступа к защищенным ресурсам.
Утверждение избытка групп
Идентификатор Microsoft Entra ограничивает количество идентификаторов объектов, которые он включает в утверждения групп, чтобы оставаться в пределах ограничения размера заголовка HTTP. Если пользователь является членом более групп, чем превышение (150 для токенов SAML, 200 для токенов JWT), то идентификатор 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 |
Указывает, что проверка подлинности не завершена. |
Следующие шаги
- Дополнительные сведения о маркерах доступа, используемых в идентификаторе Microsoft Entra.