Практические инструкции: предоставление дополнительных утверждений для приложения

Разработчики приложений могут использовать дополнительные утверждения в своих приложениях Azure AD, чтобы указать утверждения, которые нужно поместить в токены, отправляемые в приложение.

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

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

Список стандартных утверждений см. в документации по утверждениям маркера доступа и id_token.

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

Таблица 1. Применимость

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

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

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

Примечание

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

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

Имя Описание Тип маркера Тип пользователя Примечания
acct Состояние учетной записи пользователя в арендаторе JWT, SAML Если пользователь является членом клиента, это значение равно 0. Если он является гостем, это значение равно 1.
auth_time Время, когда пользователь последний раз проходил аутентификацию. Ознакомьтесь со спецификацией OpenID Connect. JWT
ctry Страна/регион пользователя JWT Azure AD возвращает необязательное утверждение ctry, если оно имеется, и значением поля является стандартный двухбуквенный код страны/региона, например FR, JP, SZ и т. д.
email Доступный адрес электронной почты для этого пользователя (если имеется). JWT, SAML MSA, Azure AD Это значение добавляется по умолчанию, если пользователь является гостем в клиенте. Для управляемых пользователей (в клиенте) это значение должно запрашиваться посредством необязательного утверждения или, в версии 2.0, с использованием области OpenID. Адреса электронной почты для управляемых пользователей должны быть заданы на портале администрирования Office.
fwd IP-адрес. JWT Добавляет исходный IPv4-адрес запрашивающего клиента (при использовании внутри виртуальной сети)
groups Необязательный формат для утверждений групп JWT, SAML Используется вместе с параметром GroupMembershipClaims в манифесте приложения, который также должен быть установлен. Дополнительные сведения см. в разделе утверждения групп ниже. Дополнительные сведения об утверждениях групп см. в разделе Настройка утверждений групп.
idtyp Тип маркера Маркеры доступа JWT Особый: только в маркерах доступа для приложений Значение равно app, если маркер является маркером только для приложения. Это наиболее точный способ, позволяющий API определить, является ли маркер только маркером приложения или маркером приложения и пользователя.
login_hint Указания имени для входа JWT MSA, Azure AD Утверждение указания непрозрачного, но надежного имени для входа в систему. Это утверждение является лучшим значением для параметра OAuth login_hint во всех потоках для обеспечения возможности единого входа. Его можно передавать между приложениями для выполнения автоматического единого входа. Приложение A может войти в учетную запись пользователя, прочитать утверждение login_hint, а затем отправить утверждение и текущий контекст клиента в приложение B в виде строки запроса или фрагмента, когда пользователь нажимает ссылку, которая ведет к приложению B. Чтобы избежать состояния гонки и проблем с надежностью, утверждение login_hint не включает текущий клиент для пользователя, и по умолчанию используется домашний клиент пользователя. Если вы используете гостевой сценарий, где пользователь использует другой клиент, вы все равно должны указать идентификатор клиента в запросе на вход и передать его в приложения, с которыми вы взаимодействуете. Это утверждение предназначено для использования с существующими функциональными возможностями login_hint вашего пакета средств разработки.
sid ИД сеанса, используемый для выхода пользователя из конкретного сеанса. JWT Личные учетные записи и учетные записи Azure AD.
tenant_ctry Страна/регион ресурса клиента JWT То же, что и ctry, однако устанавливается на уровне арендатора администратором. Также должно быть стандартным значением из двух букв.
tenant_region_scope Регион клиента ресурса JWT
upn UserPrincipalName JWT, SAML Идентификатор пользователя, который можно использовать с параметром username_hint. Не является долговременным идентификатором для пользователя и не должен использоваться для уникальной идентификации пользовательских сведений (например, в качестве ключа базы данных). Вместо этого используйте в качестве ключа базы данных идентификатор объекта пользователя (oid). Пользователи, которые входят с альтернативным идентификатором входа, не должны видеть своего имени участника-пользователя (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_pdl Предпочтительное расположение данных JWT Для клиентов с несколькими регионами предпочтительным расположением данных является трехбуквенный код, показывающий, в каком географическом регионе находится пользователь. Дополнительные сведения см. в документации по Azure AD Connect, посвященной предпочтительному расположению данных.
Например: APC для Азиатско-Тихоокеанского региона.
xms_pl Предпочитаемый язык пользователя JWT Предпочитаемый язык пользователя, если задан. Источник: домашний клиент пользователя в сценариях гостевого доступа. Формат: ЯЯ-СС ("en-us").
xms_tpl Предпочитаемый язык клиента JWT Предпочитаемый язык клиента ресурса, если задан. Формат: ЯЯ ("en").
ztdid Идентификатор развертывания без участия пользователя JWT Идентификатор устройства, используемый для Windows AutoPilot

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

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

Таблица 3. Необязательные утверждения, предназначенные только для версии 2.0

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

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

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

Таблица 4. Необязательные утверждения, предназначенные только для версии 1.0

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

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

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

Таблица 4. Значения для настройки необязательных утверждений

Имя свойства Имя дополнительного свойства Описание
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 всегда независимо от среды выполнения. Например, если ресурс установил этот флаг, а идентификатор клиента равен bb0a297b-6a42-4a55-ac40-09a501456577, любое приложение, запрашивающее маркер доступа для этого ресурса, получит маркер доступа со следующим значением aud: bb0a297b-6a42-4a55-ac40-09a501456577.

Если это утверждение не задано, API может получать токены с утверждением aud, равным api://MyApi.com, api://MyApi.com/, api://myapi.com/AdditionalRegisteredField или любому другому значению, заданному в качестве URI идентификатора приложения для этого API, а также с идентификатором клиента ресурса.

Пример дополнительных свойств:

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

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

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

Важно!

Маркеры доступа всегда создаются с помощью манифеста ресурса, а не клиента. Поэтому в запросе ...scope=https://graph.microsoft.com/user.read... ресурсом является API Microsoft Graph. Таким же маркер доступа создается с помощью манифеста API Microsoft Graph, а не манифеста клиента. Изменение манифеста для приложения никогда не приведет к тому, что маркеры для API Microsoft Graph будут выглядеть иначе. Чтобы проверить, применяются ли изменения в accessToken, запросите маркер для своего приложения, а не для другого приложения.

Настроить необязательные утверждения для приложения можно с помощью пользовательского интерфейса или манифеста приложения.

  1. Перейдите на портал Azure.
  2. Найдите и выберите Azure Active Directory.
  3. В разделе Управление выберите Регистрация приложений.
  4. Выберите в списке приложение, для которого нужно настроить необязательные утверждения.

Настройка необязательных утверждений с помощью пользовательского интерфейса

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

  1. В разделе Управление выберите Конфигурация токена.

  2. Выберите Добавить необязательное утверждение.

  3. Выберите тип токена, который нужно настроить.

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

  5. Выберите Добавить.

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

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

  1. В разделе Управление выберите Манифест. Откроется веб-редактор манифеста, в котором можно изменить манифест. При необходимости можно выбрать Скачать и изменить манифест локально, а затем повторно применить его для приложения с помощью команды Отправить. Дополнительные сведения о манифесте приложения см. в статье Манифест приложения Azure Active Directory.

    Следующая запись в манифесте приложения добавляет дополнительные утверждения auth_time, ipaddr и upn в маркеры идентификации, доступа и SAML.

    "optionalClaims": {
        "idToken": [
            {
                "name": "auth_time",
                "essential": false
            }
        ],
        "accessToken": [
            {
                "name": "ipaddr",
                "essential": false
            }
        ],
        "saml2Token": [
            {
                "name": "upn",
                "essential": false
            },
            {
                "name": "extension_ab603c56068041afb2f6832e2a17e237_skypeId",
                "source": "user",
                "essential": false
            }
        ]
    }
    
  2. По завершении нажмите Сохранить. Теперь указанные необязательные утверждения будут включаться в маркеры для вашего приложения.

Тип OptionalClaims

Объявляет необязательные утверждения, запрошенные приложением. В приложении можно настроить необязательные утверждения, которые должны возвращаться в каждый из трех типов маркеров (маркер идентификации, маркер доступа, маркер SAML 2), которые оно может получить из службы токенов безопасности. Приложение может настроить различные наборы необязательных утверждений, которые будут возвращаться в каждый тип токена. Свойство optionalClaims сущности приложения — это объект optionalClaims.

Таблица 5. Свойства типа OptionalClaims

Имя Тип Описание
idToken Коллекция (OptionalClaim) Необязательные утверждения, возвращаемые в токен идентификации JWT.
accessToken Коллекция (OptionalClaim) Необязательные утверждения, возвращаемые в маркер доступа JWT.
saml2Token Коллекция (OptionalClaim) Необязательные утверждения, возвращаемые в токен SAML.

Тип OptionalClaim

Содержит необязательное утверждение, связанное с приложением или субъект-службой. Свойства idToken, accessToken и saml2Token типа OptionalClaims являются коллекцией OptionalClaim. С помощью поля AdditionalProperties можно изменить поведение OptionalClaim, если это поддерживается определенным утверждением.

Таблица 6. Свойства типа OptionalClaims

Имя Тип Описание
name Edm.String Имя необязательного утверждения.
source Edm.String Источник утверждения (объект каталога). Существуют стандартные утверждения и определяемые пользователем утверждения из свойств расширения. Если исходное значение равно null, утверждение будет являться предопределенным необязательным утверждением. Если исходное значение — user, значение в имени свойства будет свойством расширения из объекта пользователя.
essential Edm.Boolean Если значение равно true, утверждение, указанное клиентом, необходимо для обеспечения плавной авторизации конкретной задачи, запрашиваемой пользователем. Значение по умолчанию — false.
additionalProperties Коллекция (Edm.String) Дополнительные свойства утверждений. Если свойство существует в коллекции, оно изменяет поведение дополнительного утверждения, указанного в свойстве имени.

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

Помимо стандартного набора необязательных утверждений, маркеры также можно настроить для включения расширений. Дополнительные сведения см. в документации по Microsoft Graph extensionProperty.

Схемы и открытые расширения не поддерживаются необязательными утверждениями, а только расширениями каталогов в стиле AAD-Graph. Эта возможность полезна при присоединении дополнительных сведений о пользователях, которые может использовать приложение, например, дополнительный идентификатор или важный параметр конфигурации, заданный пользователем. Пример см. внизу этой страницы.

Расширения схемы каталога — это возможность, предназначенная только для Azure AD, поэтому если ваш манифест приложения запрашивает пользовательское расширение, а пользователь MSA регистрируется в вашем приложении, эти расширения не будут возвращены.

Форматирование расширения каталога

При настройке дополнительных утверждений для расширения каталога с помощью манифеста приложения используйте полное имя расширения (в формате: extension_<appid>_<attributename>). <appid> должен совпадать с идентификатором приложения, запрашивающего утверждение.

В рамках JWT эти утверждения будут передаваться с помощью следующего формата имени: extn.<attributename>.

В рамках токенов SAML эти утверждения будут передаваться с помощью следующего формата URI: http://schemas.microsoft.com/identity/claims/extn.<attributename>

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

Далее описываются параметры конфигурации в разделе необязательных утверждений для изменения атрибутов группы, используемых в утверждениях группы, из группы по умолчанию для атрибутов, синхронизированных из локальной Active Directory Windows. Настроить необязательные утверждения групп для приложения можно с помощью пользовательского интерфейса или манифеста приложения.

Важно!

Дополнительные сведения, включая важные предостережения, касающиеся утверждений групп из локальных атрибутов, см. в разделе Настройка утверждений групп для приложений с помощью Azure AD.

Настройка необязательных утверждений групп с помощью пользовательского интерфейса

  1. Войдите на портал Azure.
  2. Пройдя аутентификацию, выберите клиент Azure AD, щелкнув его в правом верхнем углу страницы.
  3. Найдите и выберите Azure Active Directory.
  4. В разделе Управление выберите Регистрация приложений.
  5. Выберите в списке приложение, для которого нужно настроить необязательные утверждения.
  6. В разделе Управление выберите Конфигурация токена.
  7. Выберите Добавить утверждение группы.
  8. Выберите типы возвращаемых групп (группы безопасности или роли каталогов, все группы и/или группы, назначенные приложению). Вариант Группы, назначенные приложению включает только группы, назначенные данному приложению. Вариант Все группы включает группы SecurityGroup, DirectoryRole и DistributionList, но не назначенные приложению группы.
  9. Необязательно: выберите свойства определенного типа маркера, чтобы изменить значение утверждения групп, чтобы оно содержало атрибуты локальной группы, или чтобы изменить тип утверждения на утверждение роли.
  10. Нажмите кнопку Сохранить.

Настройка необязательных утверждений групп с помощью манифеста приложения.

  1. Войдите на портал Azure.

  2. Пройдя аутентификацию, выберите клиент Azure AD, щелкнув его в правом верхнем углу страницы.

  3. Найдите и выберите Azure Active Directory.

  4. Выберите в списке приложение, для которого нужно настроить необязательные утверждения.

  5. В разделе Управление выберите Манифест.

  6. Добавьте следующую запись с помощью редактора манифеста:

    Допустимые значения:

    • "Все" (этот параметр включает SecurityGroup, DirectoryRole и DistributionList)
    • "SecurityGroup"
    • "DirectoryRole"
    • "ApplicationGroup" (этот параметр включает только группы, которые назначены приложению)

    Пример:

    "groupMembershipClaims": "SecurityGroup"
    

    По умолчанию группы ObjectID будут выдаваться в значении утверждения группы. Чтобы изменить значение утверждения в соответствии с атрибутами локальной группы или изменить тип утверждения на роль, используйте конфигурацию OptionalClaims следующим образом.

  7. Задайте необязательные утверждения для конфигурации имени группы.

    Если вы хотите, чтобы группы в токене содержали атрибуты локальной группы AD, в разделе необязательных утверждений укажите, к какому типу маркера следует применить обязательное утверждение, имя запрошенного необязательного утверждения и дополнительные свойства. В списке можно указать несколько типов маркеров:

    • idToken для маркера идентификатора OIDC;
    • accessToken для маркера доступа OAuth;
    • Saml2Token для маркеров SAML.

    Тип Saml2Token применяется к маркерам формата SAML1.1 и SAML2.0.

    Для каждого соответствующего типа токена измените утверждение групп, чтобы в манифесте использовался раздел OptionalClaims. Схема OptionalClaims выглядит следующим образом:

    {
        "name": "groups",
        "source": null,
        "essential": false,
        "additionalProperties": []
    }
    
    Схема необязательного утверждения Значение
    name: Должно быть "groups"
    source: Не используется. Пропустите или укажите "null"
    essential: Не используется. Пропустите или укажите "false"
    additionalProperties: Список дополнительных свойств. Допустимые значения: "sam_account_name", "dns_domain_and_sam_account_name", "netbios_domain_and_sam_account_name", "emit_as_roles".

    В additionalProperties требуется только один из них: "sam_account_name", "dns_domain_and_sam_account_name", "netbios_domain_and_sam_account_name". Если указано более одного, используется первый, а остальные игнорируются.

    Некоторым приложениям требуются сведения о группе пользователя в утверждении роли. Чтобы изменить тип утверждения с утверждения группы на утверждение роли, добавьте "emit_as_roles" к дополнительным свойствам. Значения группы будут выдаваться в утверждении роли.

    Если используется "emit_as_roles", все роли приложения, настроенные для назначения пользователя, не будут отображаться в утверждении роли.

Примеры:

  1. Выдача групп в качестве имен групп в маркерах доступа OAuth в формате dnsDomainName\sAMAccountName.

    Настройка с помощью пользовательского интерфейса.

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

    Запись в манифесте приложения.

    "optionalClaims": {
        "accessToken": [
            {
                "name": "groups",
                "additionalProperties": [
                    "dns_domain_and_sam_account_name"
                ]
            }
        ]
    }
    
  2. Выдача имен групп в формате netbiosDomain\sAMAccountName в качестве утверждения роли в маркерах SAML и маркерах идентификатора OIDC.

    Настройка с помощью пользовательского интерфейса.

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

    Запись в манифесте приложения.

    "optionalClaims": {
        "saml2Token": [
            {
                "name": "groups",
                "additionalProperties": [
                    "netbios_name_and_sam_account_name",
                    "emit_as_roles"
                ]
            }
        ],
        "idToken": [
            {
                "name": "groups",
                "additionalProperties": [
                    "netbios_name_and_sam_account_name",
                    "emit_as_roles"
                ]
            }
        ]
    }
    

Пример необязательного утверждения

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

  • Можно использовать пользовательский интерфейс (см. пример ниже).
  • Можно использовать манифест (см. пример ниже). Ознакомьтесь со статьей Манифест приложения Azure Active Directory, чтобы получить общие сведения о манифесте.
  • Вы также можете написать приложение, в котором для обновления используется API Microsoft Graph. При настройке необязательных утверждений могут помочь сведения о типе OptionalClaims в справочнике по API Graph.

Пример.

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

  • Теперь токены идентификации содержат имена участников-пользователей федеративных пользователей в полной форме (<upn>_<homedomain>#EXT#@<resourcedomain>).
  • Маркеры доступа, запрашиваемые для этого приложения другими клиентами, будут включены в утверждение auth_time.
  • Токен SAML будет содержать расширение схемы каталога skypeId (в этом примере идентификатор этого приложения — ab603c56068041afb2f6832e2a17e237). Токен SAML представит идентификатор Skype как extension_skypeId.

Настройка с помощью пользовательского интерфейса.

  1. Войдите на портал Azure.

  2. Пройдя аутентификацию, выберите клиент Azure AD, щелкнув его в правом верхнем углу страницы.

  3. Найдите и выберите Azure Active Directory.

  4. В разделе Управление выберите Регистрация приложений.

  5. Найдите в списке приложение, для которого нужно настроить необязательные утверждения, и выберите его.

  6. В разделе Управление выберите Конфигурация токена.

  7. Выберите Добавить необязательное утверждение, тип маркера ИД, в списке утверждений выберите upn, а затем нажмите Добавить.

  8. Выберите Добавить необязательное утверждение, тип маркера Доступ, в списке утверждений выберите auth_time, а затем нажмите Добавить.

  9. На странице общих сведений о конфигурации маркера щелкните значок карандаша рядом с утверждением upn, установите переключатель Внешняя проверка подлинности и нажмите Сохранить.

  10. Выберите Добавить необязательное утверждение, выберите тип маркера SAML, в списке утверждений выберите extn.skypeID (применимо только в том случае, если вы создали объект пользователя Azure AD с именем skypeID), а затем нажмите Добавить.

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

Настройка с помощью манифеста.

  1. Войдите на портал Azure.

  2. Пройдя аутентификацию, выберите клиент Azure AD, щелкнув его в правом верхнем углу страницы.

  3. Найдите и выберите Azure Active Directory.

  4. Найдите в списке приложение, для которого нужно настроить необязательные утверждения, и выберите его.

  5. В разделе Управление выберите Манифест, чтобы открыть встроенный редактор манифестов.

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

    "optionalClaims": {
        "idToken": [
            {
                "name": "upn",
                "essential": false,
                "additionalProperties": [
                    "include_externally_authenticated_upn"
                ]
            }
        ],
        "accessToken": [
            {
                "name": "auth_time",
                "essential": false
            }
        ],
        "saml2Token": [
            {
                "name": "extension_ab603c56068041afb2f6832e2a17e237_skypeId",
                "source": "user",
                "essential": true
            }
        ]
    }
    
  7. Завершив изменение манифеста, нажмите Сохранить, чтобы сохранить его.

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

Дополнительные сведения о стандартных утверждениях, предоставляемых Azure AD, см. в следующих статьях.