Необязательный справочник по утверждениям
Необязательные утверждения можно использовать, чтобы:
- Выберите утверждения для включения в маркеры для приложения.
- изменить поведение определенных утверждений в токенах, возвращаемых платформой удостоверений Майкрософт;
- добавлять пользовательские утверждения для приложения и обращаться к ним.
Несмотря на то что необязательные утверждения поддерживаются в маркерах формата версий 1.0 и 2.0, а также в токенах SAML, большую ценность они представляют при переходе с версии 1.0 на 2.0. В платформа удостоверений Майкрософт используются меньшие размеры маркеров для обеспечения оптимальной производительности клиентами. В результате нескольких утверждений, ранее включенных в маркеры доступа и идентификаторов, больше нет в токенах версии 2.0 и их нужно запрашивать специально для каждого приложения.
Тип счета | маркеры версии 1.0; | маркеры версии 2.0. |
---|---|---|
Личная учетная запись Майкрософт | Н/П | Поддерживается |
Учетная запись Microsoft Entra | Поддерживается | Поддерживается |
Набор необязательных утверждений, доступных по умолчанию для используемых приложений, приведен в следующей таблице. Вы можете использовать пользовательские данные в атрибутах расширения и расширениях каталога для добавления необязательных утверждений для приложения. При добавлении утверждений в маркер доступа утверждения применяются к маркерам доступа, запрошенным для приложения (веб-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
определения того, должен ли пользователь в маркере доступа иметь доступ к данным. Изменяемые значения утверждений, подобные этим, могут меняться со временем, делая их небезопасными и ненадежными для авторизации.
Эти утверждения всегда включаются в токены версии 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, доступны некоторые улучшения формата маркеров версии 2, позволяющие повысить безопасность и надежность. Эти улучшения относятся только к JWT, а не к токенам SAML.
Утверждение JWT | Имя | Описание | Основание |
---|---|---|---|
aud |
Аудитория | Всегда содержится в JWT, но в маркерах доступа версии 1 может создаваться различными способами — в виде любого URI appID, с косой чертой или без нее, и идентификатора клиента ресурса. При проверке маркера предусмотреть в коде такие вариации формата бывает непросто. Используйте additionalProperties это утверждение, чтобы убедиться, что он всегда имеет идентификатор клиента ресурса в маркерах доступа версии 1. |
Только маркеры доступа JWT версии 1 |
preferred_username |
Предпочтительное имя пользователя | Содержит предпочтительное утверждение имени пользователя в маркерах версии 1. Это утверждение упрощает выдачу подсказок с именами пользователя и отображение понятных отображаемых имен в приложениях независимо от типа маркера. Рекомендуется использовать это необязательное утверждение вместо использования upn или unique_name . |
Маркеры доступа и маркеры идентификации версии 1 |
Некоторые необязательные утверждения можно настроить так, чтобы изменить способ возврата утверждения. Они 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 получает утверждение только для маркеров приложений. |
"optionalClaims": {
"idToken": [
{
"name": "upn",
"essential": false,
"additionalProperties": [
"include_externally_authenticated_upn"
]
}
]
}
Этот optionalClaims
объект приводит к тому, что маркер идентификатора, возвращенный клиенту, включает upn
утверждение с другими сведениями о клиенте дома и клиенте ресурсов. Он может изменить утверждение upn
в маркере, только если пользователь является гостем в клиенте (который использует другой поставщик удостоверений для проверки подлинности).
- Дополнительные сведения о настройке необязательных утверждений.