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

Статья
10/24/2023

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

Войдите в Центр администрирования Microsoft Entra как минимум облачные приложения Администратор istrator.
Перейдите к приложениям> удостоверений>Регистрация приложений.
Выберите приложение, для которого необходимо настроить необязательные утверждения на основе вашего сценария и желаемого результата.
В разделе Управление выберите Конфигурация токена.
- Колонка Конфигурация токена параметра пользовательского интерфейса недоступна для приложений, зарегистрированных в арендаторе Azure AD B2C: их можно настроить, изменив манифест приложения. Дополнительные сведения см. в статье Добавление утверждений и настройка пользовательского ввода с помощью настраиваемых политик в Azure Active Directory B2C.

Настройте утверждения с помощью манифеста:

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

Следующая запись в манифесте приложения добавляет дополнительные утверждения 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
        }
    ]
}
```
После завершения выберите Сохранить. Теперь указанные необязательные утверждения включены в маркеры для приложения.

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

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

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

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

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

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

Важно!

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

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

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

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

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

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

Совет

Действия, описанные в этой статье, могут немного отличаться на портале, с который вы начинаете работу.

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

Важно!

Количество групп, создаваемых в маркере, ограничено 150 для утверждений SAML и 200 для JWT, включая вложенные группы. Дополнительные сведения об ограничениях групп и важных предостережениях для утверждений группы из локальных атрибутов см. в разделе "Настройка утверждений группы для приложений".

Выполните следующие действия, чтобы настроить необязательные утверждения групп с помощью портал Azure:

Выберите приложение, для которого необходимо настроить необязательные утверждения.
В разделе Управление выберите Конфигурация токена.
Выберите Добавить утверждение группы.
Выберите типы групп для возврата (группы безопасности или роли каталога, все группы и/или группы, назначенные приложению):
- Вариант Группы, назначенные приложению включает только группы, назначенные данному приложению. Группы, назначенные параметру приложения, рекомендуется для крупных организаций из-за ограничения количества групп в токене. Чтобы изменить группы, назначенные приложению, выберите приложение из списка "Корпоративные приложения". Выберите "Пользователи и группы", затем — "Добавить пользователя". Выберите группы, которые вы хотите добавить в приложение, из списка "Пользователи и группы".
- Вариант Все группы включает группы SecurityGroup, DirectoryRole и DistributionList, но не назначенные приложению группы.
Необязательно: выберите свойства определенного типа маркера, чтобы изменить значение утверждения групп, чтобы оно содержало атрибуты локальной группы, или чтобы изменить тип утверждения на утверждение роли.
Выберите Сохранить.

Выполните следующие действия, чтобы настроить необязательные утверждения групп с помощью манифеста приложения:

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

Допустимые значения:
- "Все" (этот параметр включает SecurityGroup, DirectoryRole и DistributionList)
- "SecurityGroup"
- "DirectoryRole"
- "ApplicationGroup" (этот параметр включает только группы, которые назначены приложению)
Например:
```
"groupMembershipClaims": "SecurityGroup"
```
По умолчанию идентификаторы объектов группы создаются в значении утверждения группы. Чтобы изменить значение утверждения, содержащее атрибуты локальной группы, или изменить тип утверждения на роль, используйте optionalClaims конфигурацию следующим образом:

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

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

В списке можно указать несколько типов маркеров:

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`, `netbios_domain_and_sam_account_namedns_domain_and_sam_account_nameemit_as_roles` и .`cloud_displayname`

В additionalProperties одном из sam_account_nameних netbios_domain_and_sam_account_name требуются только один из нихdns_domain_and_sam_account_name. Если указано более одного, используется первый, а остальные игнорируются. Вы также можете добавить cloud_displayname отображаемое имя облачной группы. Этот параметр работает только в том случае, если groupMembershipClaims задано значение ApplicationGroup.

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

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

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

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

"optionalClaims": {
    "accessToken": [
        {
            "name": "groups",
            "additionalProperties": [
                "dns_domain_and_sam_account_name"
            ]
        }
    ]
}

Удаляйте имена групп, возвращаемые в формате, как утверждение ролей в netbiosDomain\sAMAccountName токенах идентификатора SAML и OIDC.

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

Выведите имена групп в формате sam_account_name локальных синхронизированных групп и имя для облачных групп в токенах идентификатора SAML и cloud_display OIDC для групп, назначенных приложению.

"groupMembershipClaims": "ApplicationGroup",
"optionalClaims": {
    "saml2Token": [
        {
            "name": "groups",
            "additionalProperties": [
                "sam_account_name",
                "cloud_displayname"
            ]
        }
    ],
    "idToken": [
        {
            "name": "groups",
            "additionalProperties": [
                "sam_account_name",
                "cloud_displayname"
            ]
        }
    ]
}

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

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

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

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

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

Настройте утверждения в портал Azure:

Выберите приложение, для которого необходимо настроить необязательные утверждения.
В разделе Управление выберите Конфигурация токена.
Выберите Добавить необязательное утверждение, тип маркера ИД, в списке утверждений выберите upn, а затем нажмите Добавить.
Выберите Добавить необязательное утверждение, тип маркера Доступ, в списке утверждений выберите auth_time, а затем нажмите Добавить.
На странице общих сведений о конфигурации маркера щелкните значок карандаша рядом с утверждением upn, установите переключатель Внешняя проверка подлинности и нажмите Сохранить.
Выберите "Добавить необязательное утверждение", выберите тип токена SAML , выберите extn.skypeID из списка утверждений (только если вы создали объект пользователя Microsoft Entra с именем skypeID), а затем нажмите кнопку "Добавить".

Настройте утверждения в манифесте:

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

Можно напрямую изменить манифест с помощью этого редактора. Манифест соответствует схеме для сущности приложения и автоматически форматирует манифест после сохранения. Новые элементы добавляются в 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
        }
    ]
}

Завершив изменение манифеста, нажмите Сохранить, чтобы сохранить его.

См. также

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

Дополнительные сведения о маркерах и утверждениях в платформа удостоверений Майкрософт.