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

  • Статья

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

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

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

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

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

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

Примечание.

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

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

Имя Описание Тип маркера Тип пользователя Примечания.
acct Состояние учетной записи пользователя в арендаторе JWT, SAML Если пользователь является членом клиента, это значение равно 0. Если он является гостем, это значение равно 1.
acrs Идентификаторы контекста проверки подлинности JWT Microsoft Entra ID Указывает идентификаторы контекста проверки подлинности операций, которые может выполнять носитель. Идентификаторы контекста проверки подлинности можно использовать для активации требования к поэтапной проверке подлинности из приложения и служб. Часто используется вместе с утверждением 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. Не изменяйте это значение. Это утверждение является лучшим значением для параметра OAuth login_hint во всех потоках для обеспечения возможности единого входа. Его можно передавать между приложениями для выполнения автоматического единого входа. Приложение A может войти в учетную запись пользователя, прочитать утверждение login_hint, а затем отправить утверждение и текущий контекст клиента в приложение B в виде строки запроса или фрагмента, когда пользователь выбирает ссылку, которая ведет к приложению B. Чтобы избежать состояния гонки и проблем с надежностью, утверждение login_hintне включает текущий клиент для пользователя, и по умолчанию используется домашний клиент пользователя. В гостевом сценарии, где пользователь находится из другого клиента, идентификатор клиента должен быть указан в запросе на вход. и передайте то же самое в приложения, с которыми вы сотрудничаете. Это утверждение предназначено для использования с существующими функциональными возможностями login_hint вашего пакета средств разработки.
sid Идентификатор сеанса, используемый для выхода пользователя на сеанс JWT Личные и учетные записи Microsoft Entra.
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, понятные для человека идентификаторы, такие как UPN, ненадежны.
verified_primary_email Источник: PrimaryAuthoritativeEmail пользователя JWT
verified_secondary_email Источник: SecondaryAuthoritativeEmail пользователя JWT
vnet Сведения об описателе виртуальной сети. JWT
xms_cc Возможности клиента JWT Microsoft Entra ID Указывает, может ли клиентское приложение, полученное маркером, обрабатывать проблемы с утверждениями. Он часто используется вместе с утверждением acrs. Это утверждение обычно используется в сценариях условного доступа и непрерывной оценки доступа. Сервер ресурсов или приложение службы, выданное маркером для управления наличием этого утверждения в маркере. Значение cp1 маркера доступа — это достоверный способ определить, что клиентское приложение может обрабатывать вызов утверждений. Дополнительные сведения см. в разделе "Проблемы утверждений", "Запросы утверждений" и возможности клиента.
xms_edov Логическое значение, указывающее, проверен ли владелец домена электронной почты пользователя. JWT Адрес электронной почты считается доменом, который проверяется, принадлежит ли он клиенту, где находится учетная запись пользователя, и администратор клиента выполнил проверку домена. Кроме того, электронная почта должна быть получена из учетной записи Майкрософт (MSA), учетной записи Google или используется для проверки подлинности с помощью потока однократного секретного кода (OTP). Учетные записи Facebook и SAML/WS-Fed не имеют проверенных доменов. Для возврата этого утверждения в токене требуется наличие email утверждения.
xms_pdl Предпочтительное расположение данных JWT Для клиентов с несколькими регионами предпочтительным расположением данных является трехбуквенный код, показывающий, в каком географическом регионе находится пользователь. Дополнительные сведения см. в документации по Microsoft Entra Подключение о предпочтительном расположении данных.
xms_pl Предпочитаемый язык пользователя JWT Предпочитаемый язык пользователя, если задан. Источник: домашний клиент пользователя в сценариях гостевого доступа. Формат: ЯЯ-СС ("en-us").
xms_tpl Предпочитаемый язык клиента JWT Предпочитаемый язык клиента ресурса, если задан. Формат: ЯЯ ("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

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

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

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

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

Имя свойства Имя в additionalProperty Description
upn Может использоваться для ответов SAML и JWT и для токенов v1.0 и v2.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 может получить маркеры с aud утверждением api://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 в маркере, только если пользователь является гостем в клиенте (который использует другой поставщик удостоверений для проверки подлинности).

См. также

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