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

Необязательный справочник по утверждениям

  • Статья

Вы можете использовать необязательные утверждения для:

  • Выберите утверждения для включения в маркеры для приложения.
  • Измените поведение определенных утверждений, возвращаемых платформой удостоверений Майкрософт в токенах.
  • Добавление и доступ к пользовательским утверждениям для приложения.

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

Тип учетной записи Токены версии 1.0 Токены версии 2.0
Личная учетная запись Майкрософт N/A Поддержанный
Учетная запись Microsoft Entra Поддержанный Поддержанный

набор необязательных утверждений версии 1.0 и версии 2.0

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

Заметка

Большинство этих утверждений можно включить в JWTs для токенов версии 1.0 и версии 2.0, но не токенов SAML, за исключением того, где указано в столбце "Тип токена". Учетные записи потребителей поддерживают подмножество этих утверждений, помеченное в столбце "Тип пользователя". Многие утверждения, перечисленные в списке, не применяются к пользователям-потребителям (у них нет клиента, поэтому tenant_ctry не имеет значения).

В следующей таблице перечислены наборы необязательных утверждений версии 1.0 и версии 2.0.

Имя Описание Тип токена Тип пользователя Примечания
acct Состояние учетной записи пользователей в клиенте JWT, SAML Если пользователь является членом клиента, значение 0. Если он гость, это значение 1.
acrs Идентификаторы контекста проверки подлинности JWT Идентификатор Microsoft Entra Указывает идентификаторы контекста проверки подлинности операций, которые может выполнять носитель. Идентификаторы контекста проверки подлинности можно использовать для активации требования к поэтапной проверке подлинности из приложения и служб. Часто используется вместе с утверждением xms_cc.
auth_time Время последнего проверки подлинности пользователя. JWT
ctry Страна или регион пользователя JWT Это утверждение возвращается, если оно присутствует, и значение поля является стандартным двухбуквенный код страны или региона, например FR, JP, SZ и т. д.
email Указанный адрес электронной почты для этого пользователя JWT, SAML MSA, идентификатор Microsoft Entra Это значение включается по умолчанию, если пользователь является гостем в клиенте. Для управляемых пользователей (пользователей внутри клиента) его необходимо запросить с помощью этого необязательного утверждения или только в версии 2.0 с областью OpenID. Это значение не гарантирует правильность и может изменяться с течением времени— никогда не используйте его для авторизации или сохранения данных для пользователя. Дополнительные сведения см. в статье Проверка разрешения пользователя на доступ к этим данным. Если вы используете утверждение электронной почты для авторизации, рекомендуется выполнить миграцию, чтобы перейти к более безопасному утверждению. Если вам требуется адрес электронной почты в приложении, запросите эти данные от пользователя напрямую, используя это утверждение в качестве предложения или предварительной заполнения пользовательского интерфейса.
fwd IP-адрес JWT Добавляет исходный адрес запрашивающего клиента (при создании виртуальной сети).
groups Необязательное форматирование для утверждений группы JWT, SAML Утверждение groups используется с параметром GroupMembershipClaims в манифесте приложения , который также должен быть задан.
idtyp Тип токена Маркеры доступа JWT Специальные: только в маркерах доступа только для приложений Значение app, если маркер является маркером только для приложений. Это утверждение является наиболее точным способом для API определить, является ли маркер приложения маркером или маркером приложения+пользователя.
login_hint Указание для входа JWT MSA, идентификатор Microsoft Entra Непрозрачное утверждение с указанием надежного входа, закодированное в кодировке Base 64. Не изменяйте это значение. Это утверждение является лучшим значением для login_hint параметра OAuth во всех потоках для получения единого входа. Его можно передать между приложениями для автоматического единого входа. Приложение A может войти в систему пользователя, прочитать утверждение login_hint, а затем отправить утверждение и текущий контекст клиента приложению B в строке запроса или фрагменте, когда пользователь выбирает ссылку, которая принимает их в приложение B. Чтобы избежать проблем с состоянием гонки и надежностью, утверждения login_hint не включать текущий клиент для пользователя и по умолчанию используется домашний клиент пользователя. В гостевом сценарии, где пользователь находится из другого клиента, идентификатор клиента должен быть указан в запросе на вход. и передайте то же самое в приложения, с которыми вы сотрудничаете. Это утверждение предназначено для использования с существующими функциями login_hint пакета SDK, однако они предоставляются.
tenant_ctry Страна или регион клиента ресурсов JWT То же, что и ctry, за исключением того, что задано на уровне клиента администратором. Также должно быть стандартным двухбуквенный значение.
tenant_region_scope Регион клиента ресурса JWT
upn UserPrincipalName JWT, SAML Идентификатор пользователя, который можно использовать с параметром username_hint. Не является устойчивым идентификатором пользователя и не следует использовать для авторизации или уникальной информации о пользователе удостоверений (например, в качестве ключа базы данных). Вместо этого используйте идентификатор объекта пользователя (oid) в качестве ключа базы данных. Дополнительные сведения см. в разделе Безопасные приложения и API путем проверки утверждений. Пользователи, войдите с помощью альтернативного идентификатора входа не должны отображаться имя участника-пользователя (UPN). Вместо этого используйте следующие утверждения маркера идентификатора для отображения состояния входа пользователю: preferred_username или unique_name для токенов версии 1 и preferred_username для токенов версии 2. Хотя это утверждение автоматически включается, его можно указать как необязательное утверждение для присоединения других свойств для изменения его поведения в гостевом случае пользователя. Вы должны использовать утверждение login_hint для использования login_hint — удобочитаемые пользователем идентификаторы, такие как имя участника-пользователя, являются ненадежными.
verified_primary_email Источник из primaryAuthoritativeEmail пользователя JWT
verified_secondary_email Источник из вторичнойauthoritativeEmail пользователя JWT
vnet Сведения описатель виртуальной сети. JWT
xms_cc Возможности клиента JWT Идентификатор Microsoft Entra Указывает, может ли клиентское приложение, полученное маркером, обрабатывать проблемы с утверждениями. Он часто используется вместе с утверждением acrs. Это утверждение обычно используется в сценариях условного доступа и непрерывной оценки доступа. Сервер ресурсов или приложение службы, выданное маркером для управления наличием этого утверждения в маркере. Значение cp1 в маркере доступа является авторитетным способом идентификации того, что клиентское приложение может обрабатывать вызов утверждений. Дополнительные сведения см. в разделе Проблемы утверждений, запросы утверждений и возможности клиента.
xms_edov Логическое значение, указывающее, проверен ли владелец домена электронной почты пользователя. JWT Адрес электронной почты считается доменом, который проверяется, принадлежит ли он клиенту, где находится учетная запись пользователя, и администратор клиента выполнил проверку домена. Кроме того, электронная почта должна быть получена из учетной записи Майкрософт (MSA), учетной записи Google или используется для проверки подлинности с помощью потока однократного секретного кода (OTP). Учетные записи Facebook и SAML/WS-Fed не имеют проверенные домены. Для возврата этого утверждения в токене требуется наличие утверждения email.
xms_pdl Предпочтительное расположение данных JWT Для клиентов с несколькими регионами предпочтительное расположение данных — это трехбуквенный код, показывающий географический регион, в котором находится пользователь. Дополнительные сведения см. в документации Microsoft Entra Connect о предпочтительном расположении данных.
xms_pl Предпочтительный язык пользователя JWT Предпочтительный язык пользователя, если задан. Источник из своего домашнего клиента в сценариях гостевого доступа. Форматированные LL-CC ("en-us").
xms_tpl Предпочитаемый язык клиента JWT Предпочтительный язык клиента ресурса, если задан. Форматированный LL ("en").
ztdid Идентификатор развертывания нулевого касания JWT Удостоверение устройства, используемое для Windows AutoPilot.

Предупреждение

Никогда не используйте email или upn значения утверждений для хранения или определения того, должен ли пользователь в маркере доступа иметь доступ к данным. Изменяемые значения утверждений, такие как эти, могут изменяться со временем, что делает их небезопасными и ненадежными для авторизации.

Дополнительный набор утверждений версии 2.0

Эти утверждения всегда включаются в токены версии 1.0, но не включены в маркеры версии 2.0, если не запрошено. Эти утверждения применимы только для JWTs (маркеры идентификатора и маркеры доступа).

Утверждение JWT Имя Описание Примечания
ipaddr IP-адрес IP-адрес клиента, вошедшего в систему.
onprem_sid Локальный идентификатор безопасности
pwd_exp Время истечения срока действия пароля Количество секунд после истечения срока действия пароля в iat утверждения. Это утверждение включается только в том случае, если срок действия пароля истекает в ближайшее время (в соответствии с "днями уведомления" в политике паролей).
pwd_url Изменение URL-адреса пароля URL-адрес, который пользователь может посетить, чтобы изменить пароль. Это утверждение включается только в том случае, если срок действия пароля истекает в ближайшее время (в соответствии с "днями уведомления" в политике паролей).
in_corp Внутри корпоративной сети Сигнализирует о входе клиента из корпоративной сети. Если это не так, утверждение не включено. На основе параметров доверенных IP-адресов в MFA.
family_name Фамилия Предоставляет фамилию, фамилию или фамилию пользователя, как определено в объекте пользователя. Например, "family_name":"Miller". Поддерживается в MSA и идентификаторе Microsoft Entra. Требуется область profile.
given_name Имя Предоставляет первое или заданное имя пользователя, как указано в объекте пользователя. Например, "given_name": "Frank". Поддерживается в MSA и идентификаторе Microsoft Entra. Требуется область profile.
upn Имя участника-пользователя Идентификатор пользователя, который можно использовать с параметром username_hint. Не является устойчивым идентификатором пользователя и не следует использовать для авторизации или уникальной информации о пользователе удостоверений (например, в качестве ключа базы данных). Дополнительные сведения см. в разделе Безопасные приложения и API путем проверки утверждений. Вместо этого используйте идентификатор объекта пользователя (oid) в качестве ключа базы данных. Пользователи, войдите с помощью альтернативного идентификатора входа не должны отображаться имя участника-пользователя (UPN). Вместо этого используйте следующее preferred_username утверждение для отображения состояния входа пользователю. Требуется область profile.

Дополнительный набор утверждений версии 1.0

Некоторые улучшения формата маркера версии 2 доступны для приложений, использующих формат токена версии 1, так как они помогают повысить безопасность и надежность. Эти улучшения применяются только к JWT, а не к токенам SAML.

Утверждение JWT Имя Описание Примечания
aud Публика Всегда присутствует в JWTs, но в маркерах доступа версии 1 его можно создать различными способами : любой URI appID, с конечным косой чертой или без него и идентификатором клиента ресурса. Это случайное преобразование может быть трудно закодировать при выполнении проверки маркеров. Используйте additionalProperties для этого утверждения, чтобы убедиться, что он всегда имеет идентификатор клиента ресурса в маркерах доступа версии 1. Только маркеры доступа JWT версии 1
preferred_username Предпочтительное имя пользователя Предоставляет предпочтительное утверждение имени пользователя в токенах версии 1. Это утверждение упрощает предоставление приложений подсказок имени пользователя и отображение отображаемых имен, доступных для чтения, независимо от их типа токена. Рекомендуется использовать это необязательное утверждение вместо использования, upn или unique_name. Маркеры идентификатора версии 1 и маркеры доступа

additionalProperties необязательных утверждений

Некоторые необязательные утверждения можно настроить для изменения способа возврата утверждения. Эти additionalProperties в основном используются для миграции локальных приложений с различными ожиданиями данных. Например, include_externally_authenticated_upn_without_hash помогает клиентам, которые не могут обрабатывать хэш-метки (#) в имени участника-участника-участника.

Имя свойства имя additionalProperty Описание
upn Можно использовать для ответов SAML и JWT, а также для токенов версии 1.0 и версии 2.0.
include_externally_authenticated_upn Включает гостевую имя участника-пользователя, хранящуюся в клиенте ресурса. Например, foo_hometenant.com#EXT#@resourcetenant.com.
include_externally_authenticated_upn_without_hash То же, что указано ранее, за исключением того, что хэш-знаки (#) заменяются подчеркиваниями (_), например foo_hometenant.com_EXT_@resourcetenant.com.
aud В маркерах доступа версии 1 это утверждение используется для изменения формата утверждения aud. Это утверждение не действует в маркерах версии 2 или маркерах идентификатора версии, где утверждение aud всегда является идентификатором клиента. Используйте эту конфигурацию, чтобы убедиться, что API может упростить проверку аудитории. Как и все необязательные утверждения, влияющие на маркер доступа, ресурс в запросе должен задать это необязательное утверждение, так как ресурсы принадлежат маркеру доступа.
use_guid Выводит идентификатор клиента ресурса (API) в формате GUID в качестве утверждения aud всегда вместо того, чтобы зависеть от среды выполнения. Например, если ресурс задает этот флаг и его идентификатор клиента 00001111-aaaa-2222-bbbb-3333cccc4444, любое приложение, которое запрашивает маркер доступа для этого ресурса, получает маркер доступа с aud : 00001111-aaaa-2222-bbbb-3333cccc4444. Без этого набора утверждений API может получить маркеры с утверждением audapi://MyApi.com, api://MyApi.com/, api://myapi.com/AdditionalRegisteredField или любым другим значением, заданным в качестве URI идентификатора приложения для этого API, и идентификатором клиента ресурса.
idtyp Это утверждение используется для получения типа маркера (приложения, пользователя, устройства). По умолчанию он создается только для маркеров только для приложений. Как и все необязательные утверждения, влияющие на маркер доступа, ресурс в запросе должен задать это необязательное утверждение, так как ресурсы принадлежат маркеру доступа.
include_user_token Выдает утверждение idtyp для маркера пользователей. Без этого дополнительного свойства для набора утверждений idtyp API получает утверждение только для маркеров приложений.

пример additionalProperties

"optionalClaims": {
    "idToken": [
        {
            "name": "upn",
            "essential": false,
            "additionalProperties": [
                "include_externally_authenticated_upn"
            ]
        }
    ]
}

Этот объект optionalClaims приводит к тому, что маркер идентификатора, возвращенный клиенту, будет включать утверждение upn с другими сведениями о домашнем клиенте и клиенте ресурсов. Утверждение upn изменяется только в маркере, если пользователь является гостем в клиенте (который использует другой поставщик удостоверений для проверки подлинности).

См. также

  • маркера доступа
  • маркера идентификатора

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

  • Дополнительные сведения о настройке необязательных утверждений.